Build an AI Agent with MCP and TypeScript in 2026

The Model Context Protocol crossed 97 million monthly SDK downloads in 2026. Most tutorials cover the server side — registering tools and exposing them via MCP. This guide covers the other half: building an agent that connects to those servers, discovers available tools at runtime, and routes Claude's tool_use requests through the MCP client API.

You will end up with a TypeScript program that:

Spawns an MCP server process (stdio transport)
Calls listTools() to discover available tools
Sends a user prompt to Claude with those tools attached
Detects Claude's tool_use response blocks
Routes each tool call through callTool() on the MCP client
Returns tool results back to Claude for a final response

Prerequisites

Node.js 20 or later
An Anthropic API key (ANTHROPIC_API_KEY in your environment)
Any existing MCP server (this guide uses a minimal example server, but the pattern works with any)

Project Setup

mkdir mcp-agent && cd mcp-agent
npm init -y

Update package.json to use ES modules:

{
  "type": "module",
  "scripts": {
    "build": "tsc",
    "start": "node dist/agent.js"
  }
}

Install dependencies:

npm install @modelcontextprotocol/sdk @anthropic-ai/sdk
npm install -D typescript @types/node

Versions confirmed from npm registry on 2026-05-05:

@modelcontextprotocol/sdk: 1.29.0
@anthropic-ai/sdk: 0.93.0

Create tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "outDir": "dist",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["src"]
}

The MCP Client Basics

The TypeScript SDK separates server and client into distinct entry points:

// Server-side (what tool providers import)
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

// Client-side (what agents import)
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

The client-side transport connects to a server by spawning it as a subprocess over stdio. This means your agent starts the server, communicates over stdin/stdout, and the server process terminates when the agent exits.

Building the Agent: src/agent.ts

import Anthropic from "@anthropic-ai/sdk";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const anthropic = new Anthropic();

async function runAgent(userMessage: string, serverCommand: string, serverArgs: string[]) {
  // Step 1: Connect to the MCP server
  const transport = new StdioClientTransport({
    command: serverCommand,
    args: serverArgs,
  });

  const mcp = new Client({ name: "mcp-agent", version: "1.0.0" });
  await mcp.connect(transport);

  // Step 2: Discover available tools
  const { tools } = await mcp.listTools();

  // Convert MCP tool schemas to Anthropic's tool format
  const anthropicTools: Anthropic.Tool[] = tools.map((t) => ({
    name: t.name,
    description: t.description ?? "",
    input_schema: t.inputSchema as Anthropic.Tool["input_schema"],
  }));

  console.log(`Connected. ${tools.length} tool(s) available: ${tools.map((t) => t.name).join(", ")}`);

  // Step 3: Initial call to Claude
  const messages: Anthropic.MessageParam[] = [
    { role: "user", content: userMessage },
  ];

  let response = await anthropic.messages.create({
    model: "claude-sonnet-4-6",
    max_tokens: 4096,
    tools: anthropicTools,
    messages,
  });

  // Step 4: Agentic loop — keep going until Claude stops using tools
  while (response.stop_reason === "tool_use") {
    const toolUseBlocks = response.content.filter(
      (block): block is Anthropic.ToolUseBlock => block.type === "tool_use"
    );

    // Build tool results by routing each tool_use through MCP callTool
    const toolResults: Anthropic.ToolResultBlockParam[] = [];

    for (const toolUse of toolUseBlocks) {
      console.log(`Calling tool: ${toolUse.name}`, toolUse.input);

      // Step 5: Execute the tool via MCP
      const result = await mcp.callTool({
        name: toolUse.name,
        arguments: toolUse.input as Record<string, unknown>,
      });

      const resultText = result.content
        .filter((c): c is { type: "text"; text: string } => c.type === "text")
        .map((c) => c.text)
        .join("\n");

      toolResults.push({
        type: "tool_result",
        tool_use_id: toolUse.id,
        content: resultText,
      });
    }

    // Step 6: Send tool results back to Claude
    messages.push({ role: "assistant", content: response.content });
    messages.push({ role: "user", content: toolResults });

    response = await anthropic.messages.create({
      model: "claude-sonnet-4-6",
      max_tokens: 4096,
      tools: anthropicTools,
      messages,
    });
  }

  await mcp.close();

  // Extract final text response
  const finalText = response.content
    .filter((block): block is Anthropic.TextBlock => block.type === "text")
    .map((block) => block.text)
    .join("\n");

  return finalText;
}

// Entry point
const result = await runAgent(
  process.argv[2] ?? "What tools do you have available?",
  "node",
  ["./dist/server.js"]
);
console.log("\nAgent response:\n", result);

The Minimal Server (for testing)

You need an MCP server to connect to. Here is the smallest possible server that exposes one tool — a simple calculator. Save it as src/server.ts:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

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

server.tool(
  "add",
  "Add two numbers together",
  { a: z.number().describe("First number"), b: z.number().describe("Second number") },
  async ({ a, b }) => ({
    content: [{ type: "text", text: String(a + b) }],
  })
);

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

Build and Run

npm run build
node dist/agent.js "What is 42 plus 17?"

Expected output:

Connected. 1 tool(s) available: add
Calling tool: add { a: 42, b: 17 }

Agent response:
 42 plus 17 equals 59.

How the Agentic Loop Works

The loop structure matters. Claude will sometimes call multiple tools in sequence before it has enough information to give a final answer. The while (response.stop_reason === "tool_use") loop handles this:

Claude returns stop_reason: "tool_use" with one or more tool_use content blocks
The agent executes each tool via mcp.callTool()
Results are appended to the message history as tool_result blocks
Claude receives the updated history and decides whether to call more tools or return a final answer
When stop_reason becomes "end_turn", the loop exits

Using Real MCP Servers

The same agent code connects to any MCP server — just change the command. Here are some popular servers from the ecosystem:

Filesystem access:

npx @modelcontextprotocol/server-filesystem /path/to/allowed/directory

GitHub tools:

npx @modelcontextprotocol/server-github

Database (Postgres):

npx @modelcontextprotocol/server-postgres postgresql://localhost/mydb

Update the agent call with the appropriate command and args:

const result = await runAgent(
  "List the markdown files in the current directory",
  "npx",
  ["@modelcontextprotocol/server-filesystem", process.cwd()]
);

Connecting to Remote MCP Servers (Streamable HTTP)

The stdio transport spawns a local process. For remote or cloud-hosted MCP servers, use the HTTP transport instead:

import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://your-mcp-server.example.com/mcp")
);

The rest of the agent code is identical — the Client API is transport-agnostic.

Inspecting Tools Before Writing Code

The MCP Inspector makes it easy to explore any server's tool catalog before writing agent code:

npx @modelcontextprotocol/inspector node ./dist/server.js

The Inspector opens a browser UI showing all registered tools, their schemas, and a form for testing each tool manually.

What to Build Next

The agent above is stateless — it handles one prompt and exits. Extending it to a conversational agent means keeping the messages array alive across turns and re-using the MCP connection. From there, you can add:

Tool filtering: Pass only the subset of MCP tools relevant to the current task
Multi-server support: Connect to several MCP servers and merge their tool lists
Streaming responses: Switch to anthropic.messages.stream() for real-time output
Persistence: Save conversation history to a file or database between sessions

The MCP client pattern keeps the agent code thin. The tools live in servers that can be updated, replaced, or swapped without touching the agent logic.

SDK versions verified from npm registry on 2026-05-05: @modelcontextprotocol/sdk@1.29.0, @anthropic-ai/sdk@0.93.0. Code patterns verified against official MCP TypeScript SDK documentation and Anthropic platform docs.

推荐订阅源

DEV Community