# For developers

What a client needs to know about the server, and how to call it without an assistant in between.

## The protocol as we serve it

- Streamable HTTP at `https://api.publicwww.com/mcp`: one JSON-RPC message per `POST` (a batch is accepted too), answers are plain `application/json`. No server-sent events, no sessions - every request carries its token. `GET` is `405`.
- Both generations of the protocol are served at the same URL: the revisions with the `initialize` handshake (2024-11-05 to 2025-11-25) and 2026-07-28 with `server/discover`, where the version and client capabilities travel in `params._meta` of every request and `Mcp-Method` / `Mcp-Name` must match the body.
- Without a token, `initialize`, `server/discover`, `ping`, `tools/list`, resources and the `read_docs` tool work. Any other call, a body that is not JSON or a token that was deleted is `401`, with a `WWW-Authenticate` header naming the protected resource metadata (RFC 9728), from which an OAuth client finds the authorization server. The message says whether the token is missing or not valid, and `error.data` links to the instructions. The flow is in [OAuth 2.1 for applications](https://publicwww.com/docs/api/authentication/#oauth).
- Tools: `search`, `account`, `read_docs` and eight for clusters, described in [Tools](https://publicwww.com/docs/mcp/tools/). Resources: this documentation and the price list in Markdown - `publicwww://docs` and `publicwww://docs/<page>`, optionally with `?lang=`. No prompts, and the lists do not change between calls.
- Without a token, the [server card](https://api.publicwww.com/mcp/server-card) describes the server: name, address, protocol versions and links. It is listed in `https://publicwww.com/.well-known/ai-catalog.json`. The tool list is not part of the card; it comes from `tools/list`.
- Outside MCP, every page of this documentation is also Markdown at its address plus `index.md` (`/docs/api/limits/index.md`) or at the address itself with `Accept: text/markdown`, the prices at `/prices.md`, everything in one file at [`/llms-full.txt`](https://publicwww.com/llms-full.txt), and the map at [`/llms.txt`](https://publicwww.com/llms.txt).

## Calling it with curl

The server keeps no state between calls, so a tool can be called straight away, without the handshake:

```
curl https://api.publicwww.com/mcp \
     -H "Authorization: Bearer $PUBLICWWW_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
          "params":{"name":"search","arguments":{"query":"\"angular.min.js\"","rows":3}}}'
```

With the same headers, `-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'` lists the tools with their input schemas. These calls and an account check, as one script: [mcp-curl.sh](https://github.com/publicwww-com/publicwww-mcp/blob/main/examples/mcp-curl.sh).

For a script that only needs search results, the [REST API](https://publicwww.com/docs/api/) is the simpler road: the same search and token, with CSV, NDJSON and the other formats.

Source: https://publicwww.com/docs/mcp/developers/
