How do I author my own MCP server?

TypeScript or Python — both are first-class

The MCP spec is language-neutral; the two reference SDKs are:

• TypeScript: @modelcontextprotocol/sdk. Tiny dependency footprint, runs under Node, easy to ship as an npx command. Best when the service you're wrapping is JavaScript-friendly (a Node API, a JSON service).
• Python: mcp on PyPI. Best when the service is Python-friendly (a Django admin, a pandas pipeline, ML tooling).

Pick whichever your team writes more comfortably; the protocol is identical. The examples below use TypeScript.

Minimum viable server

mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm i @modelcontextprotocol/sdk zod

Then create server.ts:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
import { z } from "zod";

const server = new Server(
  { name: "my-internal-tools", version: "0.1.0" },
  { capabilities: { tools: {} } }
);

// Define your tools' input schemas
const LookupUserArgs = z.object({
  email: z.string().email(),
});

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "lookup_user",
      description: "Look up a user by email in the internal database. Returns the user's id, name, plan, and signup date.",
      inputSchema: {
        type: "object",
        properties: {
          email: { type: "string", format: "email", description: "The user's email address" },
        },
        required: ["email"],
      },
    },
  ],
}));

server.setRequestHandler(CallToolRequestSchema, async (req) => {
  if (req.params.name === "lookup_user") {
    const { email } = LookupUserArgs.parse(req.params.arguments);
    const user = await fetchUserFromOurDB(email);
    return { content: [{ type: "text", text: JSON.stringify(user) }] };
  }
  throw new Error(`Unknown tool: ${req.params.name}`);
});

const transport = new StdioServerTransport();
await server.connect(transport);

That's a working MCP server. It exposes one tool, validates its arguments, calls an underlying function, returns a structured result.

The description is your prompt to the model

When the agent reads its tool list, the description is what it uses to decide when to call your tool. A vague description ("user lookup") gets called wrong; a specific one ("Look up a user by email; returns id, name, plan, and signup date") gets called correctly.

Imperative voice, name the exact inputs, mention what's returned. If there are restrictions or gotchas, put them in the description — not in a runtime error that the agent will see only after it's already tried wrong. "Returns 404 if the user doesn't exist; check first by calling list_users with a partial match."

The agent should never see the secret

The whole point of MCP versus "ask the agent to curl an API" is that the credential stays in the server. When you call your internal DB, the connection string lives in process.env.INTERNAL_DB_URL, set in the MCP server's environment, not in any prompt the agent sees.

This is also how you scope access: a server that holds a read-only DB role can expose lookup_user but not delete_user. The agent has no way to escalate; the credential simply doesn't grant it.

Stdio is easy to drive from a script

An MCP server over stdio reads JSON-RPC from stdin and writes to stdout. You can drive it from any test harness:

# A tiny smoke test
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node server.js

If the server lists its tools correctly, the schema is right. Wire up the official MCP inspector (npx @modelcontextprotocol/inspector) for a richer dev loop — it gives you a UI for calling each tool, inspecting responses, and watching the JSON-RPC traffic.

Same config as any other MCP server

In .claude/mcp.json (project) or ~/.claude/mcp.json (user):

{
  "mcpServers": {
    "internal": {
      "command": "node",
      "args": ["/Users/you/code/my-mcp-server/server.js"],
      "env": {
        "INTERNAL_DB_URL": "postgres://..."
      }
    }
  }
}

Tools appear as mcp__internal__lookup_user. First call per session prompts for permission. From there, the agent uses it like any built-in tool.