How the MCP server works

/mcp is a real Model Context Protocol endpoint, not just a JSON API. It implements the stateless, JSON-response subset of MCP’s Streamable HTTP transport.

Server composition

createReadWikiMcpServer(request) in src/lib/mcp.ts does the following per request:

1. Loads every Markdown doc via getDocs()
2. Resolves the public origin from request headers (honouring x-forwarded-* for reverse proxies)
3. Registers:
   • Resources: documentation-index, documentation-full, plus one per page
   • Tool: search_docs(query, lang?, limit?) — keyword scoring search
   • Prompt: answer_with_readwiki(question, lang?, maxResources?) — grounds answers in retrieval results

Transport layer

src/pages/mcp.ts uses WebStandardStreamableHTTPServerTransport with:

• sessionIdGenerator: undefined — no sessions
• enableJsonResponse: true — plain JSON instead of SSE streaming

Every POST constructs a new McpServer + transport and tears it down afterward. Simple and stateless; the trade-off is repeated registration cost under high QPS.

Client setup

Any MCP-Streamable-HTTP-compatible client can connect:

{
  "mcpServers": {
    "readwiki": {
      "url": "https://read.wiki/mcp"
    }
  }
}

Clients that can only fetch URLs should fall back to /llms.txt.