DEV Community

Jangwook Kim
Jangwook Kim

Posted on • Originally published at effloow.com

Build an AI Agent with MCP and TypeScript in 2026

#mcp #typescript #aiagents #claude

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:

  1. Spawns an MCP server process (stdio transport)
  2. Calls listTools() to discover available tools
  3. Sends a user prompt to Claude with those tools attached
  4. Detects Claude's tool_use response blocks
  5. Routes each tool call through callTool() on the MCP client
  6. 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
Enter fullscreen mode Exit fullscreen mode

Update package.json to use ES modules:

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

Install dependencies:

npm install @modelcontextprotocol/sdk @anthropic-ai/sdk
npm install -D typescript @types/node
Enter fullscreen mode Exit fullscreen mode

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"]
}
Enter fullscreen mode Exit fullscreen mode

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";
Enter fullscreen mode Exit fullscreen mode

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);
Enter fullscreen mode Exit fullscreen mode

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);
Enter fullscreen mode Exit fullscreen mode

Build and Run 

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

Expected output:

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

Agent response:
 42 plus 17 equals 59.
Enter fullscreen mode Exit fullscreen mode

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:

  1. Claude returns stop_reason: "tool_use" with one or more tool_use content blocks
  2. The agent executes each tool via mcp.callTool()
  3. Results are appended to the message history as tool_result blocks
  4. Claude receives the updated history and decides whether to call more tools or return a final answer
  5. 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
Enter fullscreen mode Exit fullscreen mode

GitHub tools:

npx @modelcontextprotocol/server-github
Enter fullscreen mode Exit fullscreen mode

Database (Postgres):

npx @modelcontextprotocol/server-postgres postgresql://localhost/mydb
Enter fullscreen mode Exit fullscreen mode

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()]
);
Enter fullscreen mode Exit fullscreen mode

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")
);
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)