Skip to main content
Recipes

MCP

MCP (Model Context Protocol) lets agents access external tools and data sources through a standardized protocol.

Quick Setup​

import { openai } from "@ai-sdk/openai";
import { Agent, MCPConfiguration, VoltAgent } from "@voltagent/core";
import { honoServer } from "@voltagent/server-hono";

// Configure MCP server
const mcpConfig = new MCPConfiguration({
  servers: {
    exa: {
      type: "stdio",
      command: "npx",
      args: ["-y", "mcp-remote", "https://mcp.exa.ai/mcp?exaApiKey=YOUR_API_KEY"],
    },
  },
});

// Get tools from MCP server
const mcpTools = await mcpConfig.getTools();

const agent = new Agent({
  name: "MCP Agent",
  instructions: "You can search the web using Exa",
  model: openai("gpt-4o-mini"),
  tools: mcpTools,
});

new VoltAgent({
  agents: { agent },
  server: honoServer({ port: 3141 }),
});

MCP Server Types​

STDIO (Local Process)​

{
  type: "stdio",
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"],
}

HTTP (Remote Server)​

{
  type: "http",
  url: "https://your-mcp-server.com/sse",
}

Multiple MCP Servers​

const mcpConfig = new MCPConfiguration({
  servers: {
    filesystem: {
      type: "stdio",
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/data"],
    },
    search: {
      type: "http",
      url: "https://search-mcp.example.com/sse",
    },
  },
});

Exposing Agent as MCP Server​

import { MCPServer } from "@voltagent/core";

const mcpServer = new MCPServer({
  name: "my-agent-mcp",
  version: "1.0.0",
  protocols: { stdio: true, http: true, sse: true },
});

new VoltAgent({
  agents: { agent },
  mcpServers: { mcpServer },
  server: honoServer({ port: 3141 }),
});

Stateless HTTP deployments​

The default Streamable HTTP mode stores MCP sessions in memory. When the server runs across multiple instances without session affinity, or on a serverless platform, use stateless mode:

const mcpServer = new MCPServer({
  name: "my-agent-mcp",
  version: "1.0.0",
  protocols: { stdio: false, http: true, sse: false },
  httpTransportOptions: {
    serverless: true,
  },
});

Stateless mode creates a fresh server and transport for each request and does not return an mcp-session-id, so subsequent requests can reach any instance. JSON responses are used by default. Add serverlessStreaming: true for request-scoped SSE; session resumability and out-of-request notifications require stateful mode.

Full Examples​

See the complete examples:

Table of Contents