How I built the Appwrite MCP server (and decided to hide most of its capabilities)

<p>When Anthropic introduced the Model Context Protocol on November 25, 2024, it got everyone's eyes on it, including Christy, who was Appwrite's Engineering Lead back then. I had just started my role as an "Engineering Intern" and had no idea what a whole new protocol meant, or why it was such a big deal.</p> <p>Looking at the surface, I wasn't entirely wrong. MCP is JSON-RPC with a schema and a handshake stapled on. What took us sixteen months was everything stapled around it.</p> <p><a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F03ukr9g7u27dg1gmcfcy.png" class="article-body-image-wrapper"><img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F03ukr9g7u27dg1gmcfcy.png" alt="Timeline: Nov 2024 MCP launches, Feb 2025 stdio ships, Mar 2025 Streamable HTTP, Apr 2026 981 tools become 4, Jun 2026 hosted merges, Jul 2026 shipped" width="800" height="100"></a></p> <p><em>Streamable HTTP did not exist when MCP launched. It replaced HTTP+SSE in the 2025-03-26 revision.</em></p> <h2> The stdio years </h2> <p>Christy had a working stdio server in the repo by February 26, 2025. We already had API keys, so the wiring was simple:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight shell"><code>claude mcp add appwrite <span class="se">\</span> <span class="nt">--env</span> <span class="nv">APPWRITE_PROJECT_ID</span><span class="o">=</span><YOUR_PROJECT_ID> <span class="se">\</span> <span class="nt">--env</span> <span class="nv">APPWRITE_API_KEY</span><span class="o">=</span><YOUR_API_KEY> <span class="se">\</span> <span class="nt">--env</span> <span class="nv">APPWRITE_ENDPOINT</span><span class="o">=</span>https://cloud.appwrite.io/v1 <span class="se">\</span> <span class="nt">--</span> uvx mcp-server-appwrite </code></pre> </div> <p>An API key is scoped to exactly one project by design, so the ceiling was baked into the credential. Switching projects meant editing your editor config. Creating a project was impossible. So was anything at the organization level.</p> <p>The credential is the whole difference between the two transports, and everything hard about the hosted version follows from swapping it for a token that belongs to the user instead of the project.</p> <h2> Authorization ate the schedule </h2> <p>By the spec, authorization is genuinely optional:</p> <blockquote> <p>Authorization is OPTIONAL for MCP implementations. [...] Implementations using an HTTP-based transport SHOULD conform to this specification.</p> </blockquote> <p>For a service where one tool call can drop a database, we weren't comfortable treating it as optional. If you use Auth0 or WorkOS, this is a config screen. Appwrite keeps everything in-house, so Matej built the authorization server itself, and I built the resource server plus whatever Cloud was still missing before real clients would work.</p> <p><a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fdhn3rqujm9am5nolkzx6.png" class="article-body-image-wrapper"><img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fdhn3rqujm9am5nolkzx6.png" alt="Sequence diagram of the OAuth 2.1 handshake between the MCP client, mcp.appwrite.io and Appwrite Cloud" width="799" height="851"></a></p> <p><em>Steps 2 through 6 are the part that makes "just paste this URL" work. Nothing is pre-provisioned.</em></p> <p>Three RFCs carry that flow. Protected Resource Metadata (RFC 9728) is the only real MUST in the whole authorizat