◈OpenTree DashboardSign in

$ date -I # 2026-07-25

What an MCP server actually is, for someone who will write one

The Model Context Protocol is the thing that lets an assistant call your code. It is smaller than its adoption suggests — most of a server is a list of typed functions and a way to be reached — and the parts people get wrong are the same three every time.

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/revoke

The 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

What this server exposes

ToolWhat it does
publish_htmlPublish a document and get back an unlisted URL.
update_siteReplace the content behind an existing URL, in place.
get_siteRead one site's settings, counters and share URL.
list_sitesList everything the calling key owns.
delete_siteHard-delete the record and the stored bytes.
set_passwordPut a passphrase in front of the page, or clear it.
set_expiryMove the expiry, or pin the link open forever.
set_email_gateRestrict opens to one work-email domain.
set_agentationTurn the on-page toolbar (notes, reactions, feedback) on or off.
list_feedbackRead what viewers left, newest first.
resolve_feedbackMark one piece of feedback handled.
link_walletAttach 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.

Keep reading