MCP Integration

Integrate MCP (Model Context Protocol) servers with AxCrew to connect your agents to external APIs and services

Integrate MCP (Model Context Protocol) servers with AxCrew to connect your agents to external APIs and services.

What is MCP?

AxLLM and AxCrew both support the Model Context Protocol (MCP), which allows agents to interact with external systems (APIs, websites, databases, etc.) via specialized MCP servers. MCP servers expose functions that agents can call as tools.

How MCP Works in AxCrew

You configure one or more MCP servers in your agent config using the mcpServers field
When the agent is initialized, AxCrew launches/connects to the MCP server(s)
The agent can call functions exposed by the MCP server as part of its toolset

Supported Transport Types

AxCrew supports three MCP transport types:

1. STDIO Transport (most common)

For MCP servers that communicate via standard input/output:

{
  "mcpServers": {
    "google-maps": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-google-maps"],
      "env": {
        "GOOGLE_MAPS_API_KEY": "your_api_key"
      }
    }
  }
}

2. HTTP SSE Transport

For MCP servers accessible via HTTP with Server-Sent Events:

{
  "mcpServers": {
    "api-server": {
      "sseUrl": "https://api.example.com/mcp/sse"
    }
  }
}

3. Streamable HTTP Transport

For MCP servers that support streamable HTTP communication:

{
  "mcpServers": {
    "stream-processor": {
      "mcpEndpoint": "http://localhost:3002/stream",
      "options": {
        "authorization": "Bearer your_token",
        "headers": { 
          "X-Custom-Header": "custom-value"
        }
      }
    }
  }
}

Complete Agent Configuration Example

import { AxCrew } from '@amitdeshmukh/ax-crew';
 
const config = {
  crew: [
    {
      name: "MapsAgent",
      description: "Handles location-based queries",
      signature: 'userQuery:string -> answer:string',
      provider: "openai",
      providerKeyName: "OPENAI_API_KEY",
      ai: {
        model: "gpt-4",
        temperature: 0,
      },
      options: {
        debug: true,
        maxTokens: 2000,
      },
      mcpServers: {
        "google-maps": {
          command: "npx",
          args: ["-y", "@modelcontextprotocol/server-google-maps"],
          env: {
            GOOGLE_MAPS_API_KEY: process.env.GOOGLE_MAPS_API_KEY,
          },
        },
      },
    },
    {
      name: "ManagerAgent",
      description: "Completes user tasks",
      signature: 'question:string -> answer:string',
      provider: "openai",
      providerKeyName: "OPENAI_API_KEY",
      ai: {
        model: "gpt-4o-mini",
        temperature: 0,
      },
      agents: ["MapsAgent"],
    },
  ],
};
 
const crew = new AxCrew(config);
await crew.addAllAgents();
 
const managerAgent = crew.agents.get("ManagerAgent");
const userQuery = "Are there cool bars near the Eiffel Tower within 5 min walk?";
const { answer } = await managerAgent.forward({ question: userQuery });
console.log("Answer:", answer);

Mixed Transport Configuration

You can use multiple transport types within the same agent:

{
  "mcpServers": {
    "local-files": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
    },
    "web-search": {
      "sseUrl": "http://localhost:3001/sse"
    },
    "data-stream": {
      "mcpEndpoint": "http://localhost:3002/stream"
    }
  }
}

Popular MCP Server Examples

Filesystem Server (STDIO):

"filesystem": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"]
}

Brave Search Server (STDIO):

"brave-search": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-brave-search"],
  "env": {
    "BRAVE_API_KEY": "your-brave-api-key"
  }
}

GitHub Server (STDIO):

"github": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "your-github-token"
  }
}

PostgreSQL Server (STDIO):

"postgres": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-postgres"],
  "env": {
    "POSTGRES_CONNECTION_STRING": "postgresql://user:pass@localhost/db"
  }
}

Best Practices

API Keys: Always use the env field to pass API keys, never hardcode them
Multiple Servers: You can specify multiple MCP servers in the mcpServers object
Debugging: Use "options": { "debug": true } for verbose logs
Security: Limit what your MCP server can access, validate all inputs
Path Security: For filesystem servers, always specify allowed paths