The shape of the protocol
A server declares what it can do; a client asks for that list and then invokes items from it. Three kinds of thing can be declared: tools (actions the model may call), resources (data the client may read), and prompts (workflows a user may pick). Each tool has a name, a JSON Schema for its input, and a structured result. That is very nearly the whole surface.
Why it caught on
Before it, every assistant needed a bespoke integration with every tool. Afterwards, a tool implements one protocol and every client that speaks it can call it. That is the entire argument, and it is the same one that made a standard protocol win in code editors — the property that matters is not elegance, it is that N×M becomes N+M.
Two transports, and which to pick
stdio: the client launches your server as a subprocess and talks over pipes. Ideal for local tools, trivially secure by virtue of being local, and impossible to share. Streamable HTTP: your server lives at a URL and the client makes ordinary HTTP requests. That is what a hosted server needs, and it is what drags authorisation into the picture.
Authorisation is where hosted servers get hard
A local subprocess inherits your trust. A URL does not. This deployment accepts a bearer API key and also implements OAuth 2.1 with dynamic client registration and PKCE, plus the metadata documents clients discover it through:
GET /.well-known/oauth-protected-resource
GET /.well-known/oauth-authorization-server
POST /oauth/register # dynamic client registration
GET /oauth/authorize # PKCE required
POST /oauth/token # and POST /oauth/revokeThe bug worth knowing about, because it was found here: revocation has to cover refresh tokens as well as access tokens. Blocking only the access token downgrades "revoked" into "expires a little sooner".
A server, in about fifty lines
Structurally every server is this — a list, and a switch:
// tools/list → declare
{ tools: [{
name: "publish_html",
description: "Publish a document and get back an unlisted URL.",
inputSchema: {
type: "object",
properties: {
content: { type: "string" },
title: { type: "string" },
password: { type: "string" }
},
required: ["content"]
}
}]}
// tools/call → do the thing, return structured content
async function call(name, args) {
if (name === "publish_html") {
const site = await publish(args);
return { content: [{ type: "text", text: site.url }] };
}
throw new Error("unknown tool: " + name);
}What makes a good tool list
- Verbs, not endpoints. A tool is something the model decides to do, so name it that
way —
set_expirybeatspatch_site_settings. - Descriptions written for the caller. The model reads them to choose. A description that restates the name teaches it nothing.
- Errors that say what to do next. "not_found" is a dead end; "no site with that id — call list_sites" is a step.
- Few enough to hold in context. Twelve here, and each is something a person would ask for out loud.
What this server exposes
| Tool | What it does |
|---|---|
publish_html | Publish a document and get back an unlisted URL. |
update_site | Replace the content behind an existing URL, in place. |
get_site | Read one site's settings, counters and share URL. |
list_sites | List everything the calling key owns. |
delete_site | Hard-delete the record and the stored bytes. |
set_password | Put a passphrase in front of the page, or clear it. |
set_expiry | Move the expiry, or pin the link open forever. |
set_email_gate | Restrict opens to one work-email domain. |
set_agentation | Turn the on-page toolbar (notes, reactions, feedback) on or off. |
list_feedback | Read what viewers left, newest first. |
resolve_feedback | Mark one piece of feedback handled. |
link_wallet | Attach a wallet identity to the account that owns a page. |
Register it in any client that speaks the HTTP transport:
claude mcp add --transport http opentree https://read.botook.ai/mcp \
--header "Authorization: Bearer otr_live_YOUR_KEY"Do I need MCP, or is a REST API enough?
A REST API is the surface; MCP is how a model finds and calls it without being told the shape each time. This deployment ships both, and the REST API came first.
Can one server support stdio and HTTP?
Yes, and most do — transports are separate from tool implementations. The difference that matters is that HTTP forces you to answer the authorisation question.
How do clients discover a hosted server?
Through the well-known metadata documents, plus the discovery catalogue at
/.well-known/ai-catalog.json and the server card. All are public — discovery
should be anonymous even when use is not.
How many tools is too many?
When the model starts picking the wrong one. The fix is usually merging near-duplicates rather than writing better descriptions.