Model Context Protocol (MCP)

Model Context Protocol (MCP) is an open protocol that standardizes how applications provide tools and context to LLMs. LangChain agents can use tools defined on MCP servers using the @langchain/mcp-adapters library.

Quickstart

Install the @langchain/mcp-adapters library:

npm install @langchain/mcp-adapters

pnpm add @langchain/mcp-adapters

yarn add @langchain/mcp-adapters

bun add @langchain/mcp-adapters

@langchain/mcp-adapters enables agents to use tools defined across one or more MCP servers.

MultiServerMCPClient is stateless by default. Each tool invocation creates a fresh MCP ClientSession, executes the tool, and then cleans up.

Accessing multiple MCP servers

import { MultiServerMCPClient } from "@langchain/mcp-adapters";  
import { ChatAnthropic } from "@langchain/anthropic";
import { createAgent } from "langchain";

const client = new MultiServerMCPClient({  
    math: {
        transport: "stdio",  // Local subprocess communication
        command: "node",
        // Replace with absolute path to your math_server.js file
        args: ["/path/to/math_server.js"],
    },
    weather: {
        transport: "http",  // HTTP-based remote server
        // Ensure you start your weather server on port 8000
        url: "http://localhost:8000/mcp",
    },
});

const tools = await client.getTools();  
const agent = createAgent({
    model: "claude-sonnet-5",
    tools,  
});

const mathResponse = await agent.invoke({
    messages: [{ role: "user", content: "what's (3 + 5) x 12?" }],
});

const weatherResponse = await agent.invoke({
    messages: [{ role: "user", content: "what is the weather in nyc?" }],
});

Trace MCP tool calls alongside your agent’s reasoning steps with LangSmith. Follow the tracing quickstart to get set up.

Example: Query LangChain docs

The LangChain docs MCP server is a public HTTP endpoint at https://docs.langchain.com/mcp. Connect an agent to it to search and read documentation without writing custom tools.

The docs MCP server is public and does not require an API key. For IDE and coding-agent setup (Claude Code, Cursor, and others), see Use docs programmatically.

import { MultiServerMCPClient } from "@langchain/mcp-adapters";  
import { createAgent } from "langchain";

const client = new MultiServerMCPClient({
    docs: {
        transport: "http",
        url: "https://docs.langchain.com/mcp",  
    },
});

const tools = await client.getTools();
const agent = createAgent({
    model: "claude-sonnet-5",
    tools,
});

const response = await agent.invoke({
    messages: [
        {
            role: "user",
            content: "How do I add short-term memory to a LangChain agent?",
        },
    ],
});

The server exposes these tools:

Tool	Description
`search_docs_by_lang_chain`	Search docs for relevant guides, how-tos, and examples.
`query_docs_filesystem_docs_by_lang_chain`	Read or search docs through a virtual filesystem (`rg`, `head`, `cat`, and related commands).
`submit_feedback`	Report a problem with a documentation page.

Custom servers

To create your own MCP servers, you can use the @modelcontextprotocol/sdk library. This library provides a simple way to define tools and run them as servers.

npm install @modelcontextprotocol/sdk

pnpm add @modelcontextprotocol/sdk

yarn add @modelcontextprotocol/sdk

bun add @modelcontextprotocol/sdk

To test your agent with MCP tool servers, use the following examples:

Math server (stdio transport)

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

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

server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
        tools: [
        {
            name: "add",
            description: "Add two numbers",
            inputSchema: {
                type: "object",
                properties: {
                    a: {
                        type: "number",
                        description: "First number",
                    },
                    b: {
                        type: "number",
                        description: "Second number",
                    },
                },
                required: ["a", "b"],
            },
        },
        {
            name: "multiply",
            description: "Multiply two numbers",
            inputSchema: {
                type: "object",
                properties: {
                    a: {
                        type: "number",
                        description: "First number",
                    },
                    b: {
                        type: "number",
                        description: "Second number",
                    },
                },
                required: ["a", "b"],
            },
        },
        ],
    };
});

server.setRequestHandler(CallToolRequestSchema, async (request) => {
    switch (request.params.name) {
        case "add": {
            const { a, b } = request.params.arguments as { a: number; b: number };
            return {
                content: [
                {
                    type: "text",
                    text: String(a + b),
                },
                ],
            };
        }
        case "multiply": {
            const { a, b } = request.params.arguments as { a: number; b: number };
            return {
                content: [
                {
                    type: "text",
                    text: String(a * b),
                },
                ],
            };
        }
        default:
            throw new Error(`Unknown tool: ${request.params.name}`);
    }
});

async function main() {
    const transport = new StdioServerTransport();
    await server.connect(transport);
    console.error("Math MCP server running on stdio");
}

main();

Weather server (SSE transport)

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
import {
    CallToolRequestSchema,
    ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
import express from "express";

const app = express();
app.use(express.json());

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

server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
        tools: [
        {
            name: "get_weather",
            description: "Get weather for location",
            inputSchema: {
            type: "object",
            properties: {
                location: {
                type: "string",
                description: "Location to get weather for",
                },
            },
            required: ["location"],
            },
        },
        ],
    };
});

server.setRequestHandler(CallToolRequestSchema, async (request) => {
    switch (request.params.name) {
        case "get_weather": {
            const { location } = request.params.arguments as { location: string };
            return {
                content: [
                    {
                        type: "text",
                        text: `It's always sunny in ${location}`,
                    },
                ],
            };
        }
        default:
            throw new Error(`Unknown tool: ${request.params.name}`);
    }
});

app.post("/mcp", async (req, res) => {
    const transport = new SSEServerTransport("/mcp", res);
    await server.connect(transport);
});

const PORT = process.env.PORT || 8000;
app.listen(PORT, () => {
    console.log(`Weather MCP server running on port ${PORT}`);
});

Transports

MCP supports different transport mechanisms for client-server communication.

HTTP

The http transport (also referred to as streamable-http) uses HTTP requests for client-server communication. See the MCP HTTP transport specification for more details. Use a local URL for servers you run yourself, or a hosted URL such as the LangChain docs MCP server (https://docs.langchain.com/mcp), which is public and does not require an API key.

import { MultiServerMCPClient } from "@langchain/mcp-adapters";
import { createAgent } from "langchain";

const client = new MultiServerMCPClient({
    mcp: {
        transport: "http",
        // url: "http://localhost:8000/mcp", // Local server
        url: "https://docs.langchain.com/mcp", // Hosted server
    },
});

const tools = await client.getTools();
const agent = createAgent({ model: "openai:gpt-5.4", tools });
const response = await agent.invoke({
    messages: [
        {
            role: "user",
            content: "How do I connect LangChain to an MCP server over HTTP?",
        },
    ],
});

Passing headers

When connecting to MCP servers over HTTP, you can include custom headers (for example, for authentication or tracing) using the headers field in the connection configuration. This example uses the LangChain docs MCP server; replace the header values for a server that requires authentication:

Passing headers with MultiServerMCPClient

import { MultiServerMCPClient } from "@langchain/mcp-adapters";
import { createAgent } from "langchain";

const client = new MultiServerMCPClient({
    mcp: {
        transport: "http",
        url: "https://docs.langchain.com/mcp",
        headers: {  
            Authorization: "Bearer YOUR_TOKEN",  
            "X-Custom-Header": "custom-value",  
        },  
    },
});

const tools = await client.getTools();
const agent = createAgent({ model: "openai:gpt-5.4", tools });
const response = await agent.invoke({
    messages: [
        {
            role: "user",
            content: "How do I connect LangChain to an MCP server over HTTP?",
        },
    ],
});

Authentication

The @langchain/mcp-adapters library uses the official MCP TypeScript SDK under the hood, which allows you to provide a custom authentication mechanism by implementing the OAuthClientProvider interface.

import { MultiServerMCPClient } from "@langchain/mcp-adapters";

const client = new MultiServerMCPClient({
    weather: {
        transport: "http",
        url: "http://localhost:8000/mcp",
        authProvider: authProvider, 
    },
});

stdio

Client launches server as a subprocess and communicates via standard input/output. Best for local tools and simple setups.

const client = new MultiServerMCPClient({
    math: {
        transport: "stdio",
        command: "node",
        args: ["/path/to/math_server.js"],
    },
});

Core features

Tools

Tools allow MCP servers to expose executable functions that LLMs can invoke to perform actions—such as querying databases, calling APIs, or interacting with external systems. LangChain converts MCP tools into LangChain tools, making them directly usable in any LangChain agent or workflow.

Loading tools

Use client.getTools() to retrieve tools from MCP servers and pass them to your agent:

import { MultiServerMCPClient } from "@langchain/mcp-adapters";
import { createAgent } from "langchain";

const client = new MultiServerMCPClient({...});
const tools = await client.getTools();  
const agent = createAgent({ model: "claude-sonnet-5", tools });

When an MCP tool execution fails (CallToolResult with isError: true), @langchain/mcp-adapters raises a ToolException. Wrap tool calls in a try/catch to handle these errors. Unlike the Python adapter, the TypeScript adapter does not return the error to the model as a failed tool message.

Structured content

MCP tools can return structured content alongside the human-readable text response. This is useful when a tool needs to return machine-parseable data (like JSON) in addition to text that gets shown to the model. When an MCP tool returns structuredContent, the adapter adds an mcp_structured_content entry to the tool message artifact array. You can also use tool interceptors to process or transform structured content automatically. Extracting structured content from artifact After invoking your agent, you can access the structured content from tool messages in the response:

import { MultiServerMCPClient } from "@langchain/mcp-adapters";
import { createAgent } from "langchain";

const client = new MultiServerMCPClient({...});
const tools = await client.getTools();
const agent = createAgent({ model: "claude-sonnet-5", tools });

const result = await agent.invoke({
    messages: [{ role: "user", content: "Get data from the server" }],
});

for (const message of result.messages) {
    if (message.type !== "tool" || !message.artifact) continue;
    for (const item of message.artifact) {
        if (item?.type === "mcp_structured_content") {
            console.log(item.data);
        }
    }
}

Multimodal tool content

MCP tools can return multimodal content (images, text, etc.) in their responses. When an MCP server returns content with multiple parts (e.g., text and images), the adapter converts them to LangChain’s standard content blocks. You can access the standardized representation via the contentBlocks property on the ToolMessage:

import { createAgent } from "langchain";

async function accessMultimodalToolContent(): Promise<void> {
  const { MultiServerMCPClient } = await import("@langchain/mcp-adapters");
  const client = new MultiServerMCPClient({});
  const tools = await client.getTools();
  const agent = createAgent({ model: "google-genai:gemini-3.6-flash", tools });

  const result = await agent.invoke({
    messages: [
      { role: "user", content: "Take a screenshot of the current page" },
    ],
  });

  // Access multimodal content from tool messages
  for (const message of result.messages) {
    if (message.type === "tool") {
      // Raw content in provider-native format
      console.log(`Raw content: ${message.content}`);

      // Standardized content blocks
      for (const block of message.contentBlocks) {
        if (block.type === "text") {
          console.log(`Text: ${block.text}`); 
        } else if (block.type === "image") {
          console.log(`Image URL: ${block.url}`); 
          console.log(`Image base64: ${block.base64?.slice(0, 50)}...`); 
        }
      }
    }
  }
}

import { createAgent } from "langchain";

async function accessMultimodalToolContent(): Promise<void> {
  const { MultiServerMCPClient } = await import("@langchain/mcp-adapters");
  const client = new MultiServerMCPClient({});
  const tools = await client.getTools();
  const agent = createAgent({ model: "openai:gpt-5.5", tools });

  const result = await agent.invoke({
    messages: [
      { role: "user", content: "Take a screenshot of the current page" },
    ],
  });

  // Access multimodal content from tool messages
  for (const message of result.messages) {
    if (message.type === "tool") {
      // Raw content in provider-native format
      console.log(`Raw content: ${message.content}`);

      // Standardized content blocks
      for (const block of message.contentBlocks) {
        if (block.type === "text") {
          console.log(`Text: ${block.text}`); 
        } else if (block.type === "image") {
          console.log(`Image URL: ${block.url}`); 
          console.log(`Image base64: ${block.base64?.slice(0, 50)}...`); 
        }
      }
    }
  }
}

import { createAgent } from "langchain";

async function accessMultimodalToolContent(): Promise<void> {
  const { MultiServerMCPClient } = await import("@langchain/mcp-adapters");
  const client = new MultiServerMCPClient({});
  const tools = await client.getTools();
  const agent = createAgent({ model: "anthropic:claude-sonnet-4-6", tools });

  const result = await agent.invoke({
    messages: [
      { role: "user", content: "Take a screenshot of the current page" },
    ],
  });

  // Access multimodal content from tool messages
  for (const message of result.messages) {
    if (message.type === "tool") {
      // Raw content in provider-native format
      console.log(`Raw content: ${message.content}`);

      // Standardized content blocks
      for (const block of message.contentBlocks) {
        if (block.type === "text") {
          console.log(`Text: ${block.text}`); 
        } else if (block.type === "image") {
          console.log(`Image URL: ${block.url}`); 
          console.log(`Image base64: ${block.base64?.slice(0, 50)}...`); 
        }
      }
    }
  }
}

import { createAgent } from "langchain";

async function accessMultimodalToolContent(): Promise<void> {
  const { MultiServerMCPClient } = await import("@langchain/mcp-adapters");
  const client = new MultiServerMCPClient({});
  const tools = await client.getTools();
  const agent = createAgent({ model: "openrouter:openrouter:z-ai/glm-5.2", tools });

  const result = await agent.invoke({
    messages: [
      { role: "user", content: "Take a screenshot of the current page" },
    ],
  });

  // Access multimodal content from tool messages
  for (const message of result.messages) {
    if (message.type === "tool") {
      // Raw content in provider-native format
      console.log(`Raw content: ${message.content}`);

      // Standardized content blocks
      for (const block of message.contentBlocks) {
        if (block.type === "text") {
          console.log(`Text: ${block.text}`); 
        } else if (block.type === "image") {
          console.log(`Image URL: ${block.url}`); 
          console.log(`Image base64: ${block.base64?.slice(0, 50)}...`); 
        }
      }
    }
  }
}

import { createAgent } from "langchain";

async function accessMultimodalToolContent(): Promise<void> {
  const { MultiServerMCPClient } = await import("@langchain/mcp-adapters");
  const client = new MultiServerMCPClient({});
  const tools = await client.getTools();
  const agent = createAgent({ model: "fireworks:accounts/fireworks/models/glm-5p2", tools });

  const result = await agent.invoke({
    messages: [
      { role: "user", content: "Take a screenshot of the current page" },
    ],
  });

  // Access multimodal content from tool messages
  for (const message of result.messages) {
    if (message.type === "tool") {
      // Raw content in provider-native format
      console.log(`Raw content: ${message.content}`);

      // Standardized content blocks
      for (const block of message.contentBlocks) {
        if (block.type === "text") {
          console.log(`Text: ${block.text}`); 
        } else if (block.type === "image") {
          console.log(`Image URL: ${block.url}`); 
          console.log(`Image base64: ${block.base64?.slice(0, 50)}...`); 
        }
      }
    }
  }
}

import { createAgent } from "langchain";

async function accessMultimodalToolContent(): Promise<void> {
  const { MultiServerMCPClient } = await import("@langchain/mcp-adapters");
  const client = new MultiServerMCPClient({});
  const tools = await client.getTools();
  const agent = createAgent({ model: "baseten:zai-org/GLM-5.2", tools });

  const result = await agent.invoke({
    messages: [
      { role: "user", content: "Take a screenshot of the current page" },
    ],
  });

  // Access multimodal content from tool messages
  for (const message of result.messages) {
    if (message.type === "tool") {
      // Raw content in provider-native format
      console.log(`Raw content: ${message.content}`);

      // Standardized content blocks
      for (const block of message.contentBlocks) {
        if (block.type === "text") {
          console.log(`Text: ${block.text}`); 
        } else if (block.type === "image") {
          console.log(`Image URL: ${block.url}`); 
          console.log(`Image base64: ${block.base64?.slice(0, 50)}...`); 
        }
      }
    }
  }
}

import { createAgent } from "langchain";

async function accessMultimodalToolContent(): Promise<void> {
  const { MultiServerMCPClient } = await import("@langchain/mcp-adapters");
  const client = new MultiServerMCPClient({});
  const tools = await client.getTools();
  const agent = createAgent({ model: "ollama:north-mini-code-1.0", tools });

  const result = await agent.invoke({
    messages: [
      { role: "user", content: "Take a screenshot of the current page" },
    ],
  });

  // Access multimodal content from tool messages
  for (const message of result.messages) {
    if (message.type === "tool") {
      // Raw content in provider-native format
      console.log(`Raw content: ${message.content}`);

      // Standardized content blocks
      for (const block of message.contentBlocks) {
        if (block.type === "text") {
          console.log(`Text: ${block.text}`); 
        } else if (block.type === "image") {
          console.log(`Image URL: ${block.url}`); 
          console.log(`Image base64: ${block.base64?.slice(0, 50)}...`); 
        }
      }
    }
  }
}

This allows you to handle multimodal tool responses in a provider-agnostic way, regardless of how the underlying MCP server formats its content.

Resources

Resources allow MCP servers to expose data—such as files, database records, or API responses—that can be read by clients.

Loading resources

Use client.listResources() to discover resources and client.readResource() to read their contents:

import { MultiServerMCPClient } from "@langchain/mcp-adapters";

const client = new MultiServerMCPClient({...});

// List resources from a server
const resourcesByServer = await client.listResources("server_name");  
for (const resource of resourcesByServer["server_name"] ?? []) {
    console.log(`URI: ${resource.uri}, MIME type: ${resource.mimeType}`);
}

// Read a specific resource by URI
const contents = await client.readResource(  
    "server_name",
    "file:///path/to/file.txt",
);
for (const content of contents) {
    console.log(`URI: ${content.uri}, MIME type: ${content.mimeType}`);
    if (content.text) console.log(content.text);
}

Advanced features

Tool interceptors

MCP servers run as separate processes—they cannot access LangGraph runtime information like the store, context, or agent state. Use beforeToolCall and afterToolCall hooks on MultiServerMCPClient to modify tool arguments, headers, or results:

import { MultiServerMCPClient } from "@langchain/mcp-adapters";

const client = new MultiServerMCPClient({
    mcpServers: {
        math: {
            transport: "stdio",
            command: "npx",
            args: ["-y", "@modelcontextprotocol/server-math"],
        },
    },
    beforeToolCall: ({ serverName, name, args }) => {  
        const nextArgs = { ...(args as Record<string, unknown>), injected: true };
        return {
            args: nextArgs,
            headers: { "X-Request-ID": crypto.randomUUID() },
        };
    },
    afterToolCall: (res) => {  
        if (res.name === "someTool") {
            return { result: ["modified-output", []] };
        }
        return { result: res.result };
    },
});

const tools = await client.getTools();

beforeToolCall: Can return { args?, headers? }. Headers are supported for HTTP and SSE transports. Stdio connections do not support custom headers.
afterToolCall: Can return { result } where result is a [content, artifact] tuple, a ToolMessage, a LangGraph Command, or the original result.

Progress notifications

Subscribe to progress updates for long-running tool executions with onProgress:

import { MultiServerMCPClient } from "@langchain/mcp-adapters";

const client = new MultiServerMCPClient({
    mcpServers: {
        everything: {
            transport: "stdio",
            command: "npx",
            args: ["-y", "@modelcontextprotocol/server-everything"],
        },
    },
    onProgress: (progress, source) => {  
        const pct =
            progress.percentage ??
            (progress.progress != null && progress.total
                ? Math.round((progress.progress / progress.total) * 100)
                : undefined);
        if (pct == null) return;
        const origin =
            source.type === "tool" ? `${source.server}/${source.name}` : "unknown";
        console.log(`[progress:${origin}] ${pct}%`);
    },
});

const tools = await client.getTools();

Logging

The MCP protocol supports logging notifications from servers. Subscribe with onMessage:

import { MultiServerMCPClient } from "@langchain/mcp-adapters";

const client = new MultiServerMCPClient({
    mcpServers: {
        everything: {
            transport: "stdio",
            command: "npx",
            args: ["-y", "@modelcontextprotocol/server-everything"],
        },
    },
    onMessage: (log, source) => {  
        console.log(`[${source.server}] ${log.level}: ${log.data}`);
    },
});

const tools = await client.getTools();

You can also set the server logging level with client.setLoggingLevel("debug") or client.setLoggingLevel("server_name", "debug").

Additional resources

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Get started

Core components

Middleware

Frontend

Advanced usage

Agent development

Production

Quickstart

Custom servers

Transports

HTTP

Passing headers

Authentication

stdio

Core features

Tools

Loading tools

Structured content

Multimodal tool content

Resources

Loading resources

Advanced features

Tool interceptors

Progress notifications

Logging

Additional resources

​Quickstart

​Custom servers

​Transports

​HTTP

​Passing headers

​Authentication

​stdio

​Core features

​Tools

​Loading tools

​Structured content

​Multimodal tool content

​Resources

​Loading resources

​Advanced features

​Tool interceptors

​Progress notifications

​Logging

​Additional resources

Quickstart

Custom servers

Transports

HTTP

Passing headers

Authentication

stdio

Core features

Tools

Loading tools

Structured content

Multimodal tool content

Resources

Loading resources

Advanced features

Tool interceptors

Progress notifications

Logging

Additional resources