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

MCP Servers

Explore popular MCP servers and learn how to integrate them with your AgentSea agents.

Official MCP Servers

Anthropic provides several official MCP servers that are production-ready and well-maintained.

📁 Filesystem Server

Provides file system operations including reading, writing, and listing files.

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

Example Usage:

Ask the agent to "read the contents of config.json" or "list all files in the directory"

🐙 GitHub Server

Interact with GitHub repositories, issues, pull requests, and more.

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

Example Usage:

Ask the agent to "create an issue in my repo" or "list recent pull requests"

Required Environment Variables:

  • GITHUB_TOKEN

🐘 PostgreSQL Server

Execute SQL queries and manage PostgreSQL databases.

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

Example Usage:

Ask the agent to "query the users table" or "get the count of active orders"

Required Environment Variables:

  • DATABASE_URL

💬 Slack Server

Send messages, read channels, and manage Slack workspaces.

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

Example Usage:

Ask the agent to "send a message to #general" or "list recent messages"

Required Environment Variables:

  • SLACK_BOT_TOKEN

🌐 Puppeteer Server

Browser automation for web scraping, testing, and screenshots.

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

Example Usage:

Ask the agent to "take a screenshot of example.com" or "scrape product prices from this page"

🔍 Google Drive Server

Access and manage files in Google Drive.

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

Example Usage:

Ask the agent to "list my recent Google Drive files" or "download the Q4 report"

Required Environment Variables:

  • GOOGLE_CREDENTIALS

Creating Custom MCP Servers

You can create your own MCP servers to expose custom functionality:

typescript
// my-mcp-server.js
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

// Create MCP server
const server = new Server(
  {
    name: 'my-custom-server',
    version: '1.0.0',
  },
  {
    capabilities: {
      tools: {},
    },
  },
);

// Register tools
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: 'weather_lookup',
        description: 'Get current weather for a location',
        inputSchema: {
          type: 'object',
          properties: {
            location: {
              type: 'string',
              description: 'City name or zip code',
            },
          },
          required: ['location'],
        },
      },
    ],
  };
});

// Handle tool calls
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === 'weather_lookup') {
    const { location } = request.params.arguments;

    // Your implementation
    const weatherData = await fetchWeather(location);

    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(weatherData),
        },
      ],
    };
  }

  throw new Error(`Unknown tool: ${request.params.name}`);
});

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

Using Custom MCP Servers

Once created, use your custom server with AgentSea :

typescript
import { MCPRegistry } from '@lov3kaizen/agentsea-core';

const mcpRegistry = new MCPRegistry();

// Connect to your custom server
await mcpRegistry.addServer({
  name: 'weather',
  command: 'node',
  args: ['./my-mcp-server.js'],
  transport: 'stdio',
});

// Use the tools
const tools = mcpRegistry.getTools();
// Now includes: weather:weather_lookup

MCP Server Best Practices

Performance

  • Cache frequently accessed data
  • Implement rate limiting for external API calls
  • Use streaming for large responses
  • Set appropriate timeouts

Security

  • Validate all inputs before processing
  • Use environment variables for credentials
  • Implement proper error handling
  • Sanitize file paths and URLs
  • Limit file system access to specific directories

Reliability

  • Implement graceful error handling
  • Provide detailed error messages
  • Add retry logic for transient failures
  • Log all operations for debugging

Documentation

  • Write clear tool descriptions
  • Document all parameters and return types
  • Provide usage examples
  • Include setup instructions

Testing MCP Servers

Test your MCP servers before integration:

typescript
// test-mcp-server.ts
import { MCPClient } from '@lov3kaizen/agentsea-core';
import { StdioTransport } from '@lov3kaizen/agentsea-core/mcp';

async function testMCPServer() {
  const client = new MCPClient(
    new StdioTransport({
      command: 'node',
      args: ['./my-mcp-server.js'],
    }),
  );

  try {
    // Connect
    await client.connect();
    console.log('✓ Connected to server');

    // List tools
    const tools = await client.listTools();
    console.log('✓ Tools:', tools.map(t => t.name));

    // Call tool
    const result = await client.callTool('weather_lookup', {
      location: 'San Francisco',
    });
    console.log('✓ Tool result:', result);

    // Disconnect
    await client.disconnect();
    console.log('✓ Disconnected');
  } catch (error) {
    console.error('✗ Test failed:', error);
  }
}

testMCPServer();

Debugging MCP Connections

Enable debug logging to troubleshoot MCP connections:

typescript
import { MCPRegistry, Logger } from '@lov3kaizen/agentsea-core';

// Enable debug logging
const logger = new Logger({ level: 'debug' });

const mcpRegistry = new MCPRegistry();

// Listen to MCP events
mcpRegistry.on('server:connected', (serverName) => {
  logger.info(`MCP server '${serverName}' connected`);
});

mcpRegistry.on('server:disconnected', (serverName) => {
  logger.warn(`MCP server '${serverName}' disconnected`);
});

mcpRegistry.on('server:error', (serverName, error) => {
  logger.error(`MCP server '${serverName}' error`, error);
});

// Add server with debugging
await mcpRegistry.addServer({
  name: 'my-server',
  command: 'node',
  args: ['./server.js'],
  transport: 'stdio',
});

MCP Server Registry

Discover more MCP servers in the community registry:

Next Steps