v0.5.2 release - Contributors, Sponsors and Enquiries are most welcome 😌

MCP Integration Overview

Model Context Protocol (MCP) is an open standard that enables seamless integration between LLM applications and external tools. AgentSea provides first-class MCP support.

What is MCP?

Model Context Protocol (MCP) is an open standard developed by Anthropic that provides a universal way for AI applications to connect to external data sources and tools. Think of it as USB-C for AI—a single protocol that works with any compatible tool or service.

💡 Key Benefits

  • Connect to any MCP-compatible tool or service
  • Automatic tool discovery and registration
  • Standardized tool calling interface
  • Support for both local and remote servers
  • Access to resources, prompts, and tools

How MCP Works in AgentSea

AgentSea handles all the complexity of MCP integration:

  1. Connect to MCP Servers: Specify server command and transport type
  2. Automatic Tool Discovery: AgentSea fetches available tools from the server
  3. Schema Conversion: JSON Schema from MCP is converted to Zod schemas
  4. Tool Registration: MCP tools are automatically registered with your agents
  5. Transparent Execution: Agents can call MCP tools just like built-in tools

Quick Start

Here's a minimal example of using MCP with AgentSea :

typescript
import {
  Agent,
  AnthropicProvider,
  ToolRegistry,
  MCPRegistry,
} from '@lov3kaizen/agentsea-core';

// 1. Create MCP registry
const mcpRegistry = new MCPRegistry();

// 2. Connect to MCP server
await mcpRegistry.addServer({
  name: 'filesystem',
  command: 'npx',
  args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
  transport: 'stdio',
});

// 3. Get MCP tools (automatically converted)
const mcpTools = mcpRegistry.getTools();

// 4. Create agent with MCP tools
const toolRegistry = new ToolRegistry();
toolRegistry.registerMany(mcpTools);

const agent = new Agent(
  {
    name: 'mcp-agent',
    model: 'claude-sonnet-4-20250514',
    provider: 'anthropic',
    tools: mcpTools,
  },
  new AnthropicProvider(),
  toolRegistry,
);

// 5. Agent can now use MCP tools
const response = await agent.execute(
  'List all files in /tmp',
  context,
);

// Cleanup
await mcpRegistry.disconnectAll();

MCP Architecture

Understanding the MCP architecture in AgentSea :

🔌

MCPRegistry

Manages connections to multiple MCP servers

💬

MCPClient

Communicates with individual MCP servers

🚀

MCPTransport

Handles STDIO or SSE communication

🔧

ToolAdapter

Converts MCP tools to AgentSea format

Transport Types

AgentSea supports two MCP transport types:

STDIO Transport

For local MCP servers that communicate via standard input/output:

typescript
await mcpRegistry.addServer({
  name: 'local-server',
  command: 'node',
  args: ['./my-mcp-server.js'],
  transport: 'stdio',
  env: {
    API_KEY: process.env.API_KEY,
  },
});

SSE Transport

For HTTP-based MCP servers using Server-Sent Events:

typescript
await mcpRegistry.addServer({
  name: 'remote-server',
  url: 'https://mcp.example.com/sse',
  transport: 'sse',
  headers: {
    'Authorization': `Bearer ${process.env.API_TOKEN}`,
  },
});

Multiple MCP Servers

Connect to multiple MCP servers simultaneously:

typescript
const mcpRegistry = new MCPRegistry();

// Connect to filesystem server
await mcpRegistry.addServer({
  name: 'filesystem',
  command: 'npx',
  args: ['-y', '@modelcontextprotocol/server-filesystem', '/home/user'],
  transport: 'stdio',
});

// Connect to GitHub server
await mcpRegistry.addServer({
  name: 'github',
  command: 'npx',
  args: ['-y', '@modelcontextprotocol/server-github'],
  transport: 'stdio',
  env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN },
});

// Connect to custom HTTP server
await mcpRegistry.addServer({
  name: 'custom',
  url: 'https://api.example.com/mcp',
  transport: 'sse',
});

// Get tools from all servers
// Tools are prefixed: filesystem:read_file, github:create_issue, etc.
const allTools = mcpRegistry.getTools();

// Or get tools from specific server
const githubTools = mcpRegistry.getServerTools('github');

MCP Resources

Some MCP servers provide resources (data, templates, etc.):

typescript
const client = mcpRegistry.getClient('filesystem');

// List available resources
const resources = await client.listResources();
console.log(resources);
// [{ uri: 'file:///home/user/data.json', name: 'User Data', ... }]

// Read resource content
const content = await client.readResource('file:///home/user/data.json');
console.log(content);

MCP Prompts

MCP servers can provide pre-configured prompts:

typescript
const client = mcpRegistry.getClient('github');

// List available prompts
const prompts = await client.listPrompts();
console.log(prompts);
// [{ name: 'review_pr', description: 'Review a pull request', ... }]

// Get prompt
const prompt = await client.getPrompt('review_pr', {
  repo: 'owner/repo',
  prNumber: '123',
});

// Use prompt with agent
const response = await agent.execute(prompt.messages[0].content, context);

Error Handling

Handle MCP connection errors gracefully:

typescript
try {
  await mcpRegistry.addServer({
    name: 'my-server',
    command: 'npx',
    args: ['-y', '@example/mcp-server'],
    transport: 'stdio',
  });

  const tools = mcpRegistry.getTools();
  console.log(`Loaded ${tools.length} tools`);
} catch (error) {
  if (error.code === 'ENOENT') {
    console.error('MCP server command not found');
  } else if (error.message.includes('timeout')) {
    console.error('MCP server connection timeout');
  } else {
    console.error('Failed to connect to MCP server:', error);
  }

  // Fall back to built-in tools
  const fallbackTools = [calculatorTool, httpRequestTool];
  toolRegistry.registerMany(fallbackTools);
}

Lifecycle Management

Manage MCP server connections throughout your application lifecycle:

typescript
// Startup
const mcpRegistry = new MCPRegistry();
await mcpRegistry.addServer(config1);
await mcpRegistry.addServer(config2);

// Check connection status
const client = mcpRegistry.getClient('my-server');
const isConnected = client.isConnected();

// Reload tools from a server
await mcpRegistry.reloadServerTools('my-server');

// Remove specific server
await mcpRegistry.removeServer('my-server');

// Shutdown - disconnect all servers
await mcpRegistry.disconnectAll();

Popular MCP Servers

Some popular MCP servers you can use:

  • @modelcontextprotocol/server-filesystem: File system operations
  • @modelcontextprotocol/server-github: GitHub API integration
  • @modelcontextprotocol/server-postgres: PostgreSQL database access
  • @modelcontextprotocol/server-slack: Slack messaging
  • @modelcontextprotocol/server-puppeteer: Browser automation

Best Practices

  • Connection Management: Always disconnect from MCP servers during shutdown
  • Error Handling: Implement fallback tools in case MCP servers are unavailable
  • Tool Naming: Use server prefixes to avoid tool name conflicts
  • Security: Pass sensitive credentials via environment variables
  • Timeouts: Set appropriate timeouts for MCP server operations
  • Testing: Test with MCP servers unavailable to ensure graceful degradation

Next Steps