MCP in Practice (Level III)

You have M AI applications and N systems worth connecting them to. Without a standard that is M × N integrations, each written against a proprietary plugin interface, each rewritten when either side changes. With one, it is M + N.

That is the entire pitch, and it is the same pitch as the Language Server Protocol — which is the right analogy to hold in your head. LSP didn't make editors smarter; it made "add Rust support" a thing you do once instead of once per editor. MCP does that for context and actions.

What it deliberately does not do: it does not tell the model what to do, does not run the model, does not decide permissions, and does not make a badly-designed API pleasant. It standardizes the wire, so the interesting problems are the ones left over.

It is worth being precise about that list, because most disappointment with MCP comes from expecting one of these:

Read the right-hand column again. Everything that decides whether your integration is good or dangerous is in it. The protocol is the easy part, and it is solved; this course spends most of its time on the column the specification does not cover.

Three roles, and confusing them makes every other document unreadable.

The host is the application the user is actually using — an IDE, a desktop assistant, an agent framework. It talks to the model, owns the UI, and enforces permission.

A client lives inside the host and maintains one connection to one server. Ten servers means ten clients inside the host. The one-to-one pairing is deliberate: it keeps each server's capabilities and session state isolated from every other's.

A server exposes capabilities — a wrapper around Postgres, GitHub, your internal deploy system, the filesystem. It is usually small, usually stateless, and it can run as a local subprocess or a remote HTTP service.

The chain to keep straight: the model decides it wants a tool, the host approves it, the client sends the request, the server does the work. The model never touches the server, which is exactly why the design is safe enough to be useful.

That chain has a consequence people miss until it bites them: the server has no idea what the model was asked. It receives tools/call with a name and arguments, and nothing else. It does not see the conversation, the system prompt, or the user's intent. Every decision your server makes — is this allowed, is this sensible, should this be rate limited — has to be made from the arguments and the authenticated identity alone.

That is a feature, not a limitation. It is what makes a server auditable: the complete record of what an integration did is a list of tool calls with their arguments, and it does not require reasoning about a conversation to interpret. But it means "the model wouldn't ask for something unreasonable" is not a security argument your server can rely on, because your server cannot tell reasonable requests from unreasonable ones and neither can the protocol.

Here is a complete server. Not a fragment — the whole file, the package manifest, the build command and the exact JSON a colleague pastes to connect it.

src/index.ts

#!/usr/bin/env node
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const API = process.env.DEPLOY_API_URL ?? "https://deploys.internal";

const server = new McpServer({ name: "deploys", version: "1.0.0" });

server.registerTool(
  "get_deploy_status",
  {
    title: "Deploy status",
    description:
      "Current deploy status for a service: version live, when it shipped, who " +
      "shipped it, and health. Call this whenever someone asks whether something " +
      "shipped, what version is live, why a deploy failed, or what changed recently.",
    inputSchema: {
      service: z
        .enum(["checkout", "payments", "search", "auth"])
        .describe("Which service to report on."),
    },
    annotations: { readOnlyHint: true, openWorldHint: false },
  },
  async ({ service }) => {
    const res = await fetch(`${API}/v1/deploys/${service}/current`);

    if (res.status === 404) {
      return {
        isError: true,
        content: [{ type: "text", text: `No service named '${service}'.` }],
      };
    }
    if (!res.ok) {
      return {
        isError: true,
        content: [{
          type: "text",
          text: `Deploy API returned ${res.status}. It may be degraded; ` +
                `report the gap rather than guessing at the deploy state.`,
        }],
      };
    }

    const d = await res.json();
    return {
      content: [{
        type: "text",
        text:
          `${service} ${d.version}\n` +
          `live since ${d.deployed_at} (${d.deployed_by})\n` +
          `health: ${d.health}\n` +
          `commits: ${d.commit_range}`,
      }],
    };
  },
);

// stdout is the protocol. Every log line goes to stderr.
const transport = new StdioServerTransport();
await server.connect(transport);
console.error("deploys mcp server ready on stdio");

package.json

{
  "name": "deploys-mcp",
  "version": "1.0.0",
  "type": "module",
  "bin": { "deploys-mcp": "./build/index.js" },
  "files": ["build"],
  "scripts": {
    "build": "tsc && chmod +x build/index.js",
    "dev": "npm run build && node build/index.js"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.0.0",
    "zod": "^3.23.8"
  },
  "devDependencies": {
    "@types/node": "^22.0.0",
    "typescript": "^5.5.0"
  }
}

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "build",
    "rootDir": "src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"]
}

Then:

npm install
npm run build

And the config a colleague pastes into their client's mcpServers block — this is the artifact that matters, because it is what "ship it" means:

{
  "mcpServers": {
    "deploys": {
      "command": "node",
      "args": ["/absolute/path/to/deploys-mcp/build/index.js"],
      "env": { "DEPLOY_API_URL": "https://deploys.internal" }
    }
  }
}

In Claude Code the same thing is one line, and it can be committed to the repository so everyone who clones gets it:

claude mcp add deploys --scope project -- node /absolute/path/to/deploys-mcp/build/index.js

The Python equivalent, because both SDKs are mature and a course that names both should show both. pip install "mcp[cli]", then server.py:

import os
import httpx
from typing import Literal
from mcp.server.fastmcp import FastMCP
from mcp.server.fastmcp.exceptions import ToolError

API = os.environ.get("DEPLOY_API_URL", "https://deploys.internal")

mcp = FastMCP("deploys")


@mcp.tool()
async def get_deploy_status(
    service: Literal["checkout", "payments", "search", "auth"],
) -> str:
    """Current deploy status for a service: version live, when it shipped, who
    shipped it, and health. Call this whenever someone asks whether something
    shipped, what version is live, why a deploy failed, or what changed recently.

    Args:
        service: Which service to report on.
    """
    async with httpx.AsyncClient() as client:
        res = await client.get(f"{API}/v1/deploys/{service}/current")

    # Raising marks the result isError:true, exactly like the TypeScript branch
    # above. Returning the message as a plain string would report a failure to the
    # model as a success — the single easiest way to get an agent to build on a
    # result that does not exist.
    if res.status_code == 404:
        raise ToolError(f"No service named '{service}'.")
    if res.status_code >= 400:
        raise ToolError(
            f"Deploy API returned {res.status_code}. It may be degraded; "
            "report the gap rather than guessing at the deploy state."
        )

    d = res.json()
    return (
        f"{service} {d['version']}\n"
        f"live since {d['deployed_at']} ({d['deployed_by']})\n"
        f"health: {d['health']}\n"
        f"commits: {d['commit_range']}"
    )


if __name__ == "__main__":
    mcp.run()          # stdio by default

Note what the Python SDK infers for you: the tool name from the function name, the input schema from the type annotations (Literal becomes an enum), and the description from the docstring. That is convenient and it is a trap — the docstring is now your tool description, which means it has to be written for a model rather than for a developer reading the source. Write the trigger condition into it, as above.

The second trap is the one the error branches above avoid. In TypeScript you return isError: true explicitly; in Python the natural-looking thing is to return a string saying what went wrong, and a returned string is a success. The model receives "No service named 'checkuot'" as a normal result and may well treat it as the answer. Raise instead, and the SDK marks the result as an error. Two implementations of the same server have to fail the same way, or the one that does not will be the one in production.

Its config entry:

{
  "mcpServers": {
    "deploys": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/server.py"],
      "env": { "DEPLOY_API_URL": "https://deploys.internal" }
    }
  }
}

The protocol machinery — initialization, capability advertisement, tools/list, schema validation, framing — is handled by the SDK in both languages. What deserves your attention is everything in that description string and everything in the formatting of the result. The plumbing is solved. The interface is not.