Model Context Protocol (MCP): Build and Use MCP Servers in TypeScript

import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
 
const notes = new Map<string, { title: string; body: string; tags: string[] }>([
  ["1", { title: "Deploy checklist", body: "Run migrations, then deploy the web app, then the workers.", tags: ["ops"] }],
  ["2", { title: "Pricing decision", body: "Starter stays at $29 until Q1; review churn monthly.", tags: ["pricing"] }],
]);
 
const server = new McpServer({ name: "notes", version: "1.0.0" });
 
server.registerTool(
  "search_notes",
  {
    title: "Search notes",
    description: "Search notes by keyword in titles and bodies. Returns note IDs and titles; read a note with get_note.",
    inputSchema: { query: z.string().min(2).describe("Keyword, such as 'deploy'") },
    outputSchema: { results: z.array(z.object({ id: z.string(), title: z.string() })) },
    annotations: { readOnlyHint: true },
  },
  async ({ query }) => {
    const q = query.toLowerCase();
    const results = [...notes]
      .filter(([, n]) => `${n.title} ${n.body}`.toLowerCase().includes(q))
      .map(([id, n]) => ({ id, title: n.title }));
    return {
      content: [{ type: "text", text: JSON.stringify(results) }],
      structuredContent: { results },
    };
  },
);
 
server.registerTool(
  "get_note",
  {
    title: "Get note",
    description: "Read the full text of one note by ID.",
    inputSchema: { id: z.string() },
    annotations: { readOnlyHint: true },
  },
  async ({ id }) => {
    const note = notes.get(id);
    if (!note) return { content: [{ type: "text", text: `No note with id ${id}` }], isError: true };
    return { content: [{ type: "text", text: `# ${note.title}\n\n${note.body}` }] };
  },
);
 
server.registerTool(
  "add_note",
  {
    title: "Add note",
    description: "Create a new note. Use only when the user asks to save something.",
    inputSchema: { title: z.string().min(1).max(120), body: z.string().max(10_000), tags: z.array(z.string()).default([]) },
    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
  },
  async ({ title, body, tags }) => {
    const id = String(notes.size + 1);
    notes.set(id, { title, body, tags });
    return { content: [{ type: "text", text: `Created note ${id}` }] };
  },
);
 
// A resource template: hosts can attach notes://<id> as context.
server.registerResource(
  "note",
  new ResourceTemplate("notes://{id}", { list: undefined }),
  { title: "Note", description: "A single note as Markdown", mimeType: "text/markdown" },
  async (uri, { id }) => {
    const note = notes.get(String(id));
    if (!note) throw new Error(`No note with id ${String(id)}`);
    return { contents: [{ uri: uri.href, mimeType: "text/markdown", text: `# ${note.title}\n\n${note.body}` }] };
  },
);
 
// A prompt template the user can pick, for example as a slash command.
server.registerPrompt(
  "summarize_notes",
  {
    title: "Summarize notes about a topic",
    description: "Find and summarize all notes about a topic",
    argsSchema: { topic: z.string() },
  },
  ({ topic }) => ({
    messages: [{ role: "user", content: { type: "text", text: `Search my notes about "${topic}", read the relevant ones, and summarize them in five bullet points.` } }],
  }),
);
 
// stdout carries the protocol: log to stderr only.
await server.connect(new StdioServerTransport());
console.error("notes MCP server running on stdio");

claude mcp add notes -- node /absolute/path/to/notes-server.ts
claude mcp list

{
  "mcpServers": {
    "notes": { "command": "node", "args": ["./mcp/notes-server.ts"] }
  }
}

import Anthropic from "@anthropic-ai/sdk";
import { mcpTools, type MCPClientLike } from "@anthropic-ai/sdk/helpers/beta/mcp";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 
const mcp = new Client({ name: "my-agent", version: "1.0.0" });
await mcp.connect(new StdioClientTransport({ command: "node", args: ["notes-server.ts"] }));
 
// The MCP SDK's callTool type also allows a legacy { toolResult } shape from very old servers.
// Narrow it to the current shape the Anthropic helper expects.
const isCurrent = (r: unknown): r is CallToolResult => Array.isArray((r as { content?: unknown } | null)?.content);
const caller: MCPClientLike = {
  async callTool(params) {
    const result = await mcp.callTool(params);
    if (!isCurrent(result)) throw new Error("Unsupported legacy tool result");
    return result;
  },
};
 
try {
  const { tools } = await mcp.listTools();
  console.log("tools:", tools.map((t) => t.name).join(", "));
 
  // Expose only read-only tools to this agent: least privilege.
  const readOnly = tools.filter((t) => t.annotations?.readOnlyHint === true);
 
  const anthropic = new Anthropic();
  const final = await anthropic.beta.messages.toolRunner({
    model: "claude-opus-5-5",
    max_tokens: 4096,
    max_iterations: 6,
    tools: mcpTools(readOnly, caller),
    messages: [{ role: "user", content: "What is our deploy order? Check my notes." }],
  });
  console.log(final.content.flatMap((b) => (b.type === "text" ? [b.text] : [])).join(""));
} finally {
  await mcp.close(); // also stops the server subprocess
}