MCP-god

Model Context Protocol

Build a custom MCP server
and watch the data move.

Host, client, server. Tools, resources, prompts. One protocol, animated end to end, so the mental model sticks.

Start with the flow Jump to code
3roles
6primitives
2transports
1JSON-RPC wire

01 · Data flow

Who talks to whom

The LLM never touches your server. The host decides, the client relays, the server answers. Packets below are live.

HOST Claude Code · Cursor · your agent LLM loop permissions · UI CLIENT 1 per server · in the host initialize · correlate ids SERVER your code tools · resources prompts intent result JSON-RPC stdio / HTTP { "jsonrpc": "2.0", "id": 1, "method": "initialize" }
request response notification

02 · Lifecycle

One session, step by step

Every MCP session follows the same handshake. Click a step or let it auto-play.

    Client
    Server

    03 · Build it

    A custom server in five moves

    Python with FastMCP on the left, TypeScript SDK on the right. Same shape, same protocol.

      server.py

      04 · Primitives

      Six things MCP can express

      Three the server offers, three the client offers back. Hover to see who controls each.

      ⚙

      Tools

      Model-controlled functions with a JSON Schema. The POST of MCP.

      server → model
      ▤

      Resources

      App-controlled read-only data at a URI. The GET of MCP.

      server → app
      ✎

      Prompts

      User-controlled templates. Slash commands with arguments.

      server → user
      ✦

      Sampling

      Server borrows the host's LLM. No API key needed on the server.

      server ← host
      ⌂

      Roots

      Host tells the server which folders are in scope. Its sandbox.

      server ← host
      ?

      Elicitation

      Server asks the user a structured question mid-call.

      server ← user

      05 · Transports

      Two ways to move bytes

      stdio

      Host spawns your process. stdin in, stdout out, stderr for logs. Local only, zero auth, fastest to build.

      Streamable HTTP

      One /mcp endpoint. POST per message, SSE upgrade for streaming, Mcp-Session-Id for state, OAuth 2.1 for auth.

      Now go read the deep dives.

      Seven markdown guides and two runnable starter servers live in the repo.

      Open MCP-god on GitHub