MCP

Connect agents to external tool servers via the Model Context Protocol

Overview

MeepaGateway supports the Model Context Protocol (MCP), letting agents call tools hosted by external MCP servers. MCP tools appear alongside built-in tools — the LLM cannot tell the difference.

MCP servers are configured per-agent in .mcp.json inside the agent’s home directory (~/.meepagateway/agents/{agent_id}/.mcp.json). This is the same format used by Claude Desktop and Cursor.

MeepaGateway uses the rmcp crate for MCP communication.

---

Transports

Stdio

The gateway spawns the MCP server as a child process and communicates over stdin/stdout using JSON-RPC 2.0.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    }
  }
}

Streamable HTTP

The gateway connects to an already-running HTTP MCP server.

{
  "mcpServers": {
    "my-api": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

command and url are mutually exclusive — use one or the other per server.

---

.mcp.json Format

The file follows the standard MCP JSON format:

{
  "mcpServers": {
    "server-name": {
      "command": "executable",
      "args": ["arg1", "arg2"],
      "env": {
        "API_KEY": "your-key"
      },
      "disabled": false
    }
  }
}

Fields

command · string

Executable to launch for stdio transport. Mutually exclusive with url.

args · array

Arguments passed to the spawned command.

url · string

HTTP endpoint for streamable HTTP transport. Mutually exclusive with command.

env · object

Extra environment variables injected into the spawned process (stdio only).

disabled · boolean · default: "false"

Set to true to disable this server without removing it from the file.

---

Examples

Memory server (stdio)

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

GitHub (stdio)

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
      }
    }
  }
}

Multiple servers

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp/workspace"]
    },
    "search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "BSA..."
      }
    },
    "internal-api": {
      "url": "http://localhost:4000/mcp"
    }
  }
}

---

Managing MCP Servers

Via CLI

# Edit .mcp.json directly (opens editor)
meepagateway agent mcp meepa

Via Captain Dashboard

Navigate to Agents → → MCP to add, edit, disable, and remove MCP servers through the web UI.

Via API

# List MCP servers
curl -H "Authorization: Bearer $API_KEY" \
  http://localhost:63372/api/agents/meepa/mcp

# Add a server
curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "filesystem",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
  }' \
  http://localhost:63372/api/agents/meepa/mcp

---

How Tool Bridging Works

At agent startup:

1. McpManager reads .mcp.json and connects to each enabled server
2. For each server, list_tools() is called to discover available tools
3. Each discovered tool is wrapped in McpToolBridge — an adapter that implements the internal Tool trait
4. Bridged tools are registered in the agent’s ToolRegistry alongside built-in tools

When the LLM calls an MCP tool:

1. The gateway looks up the tool by name in the registry
2. McpToolBridge.execute() calls call_tool() on the McpClient
3. The result is returned to the LLM as a tool result message

Connection failures on startup are logged but do not prevent the agent from starting — only tools from the failed server are unavailable.

---

Architecture

Agent tool registry
  ├── built-in: shell, read_file, write_file, web_fetch, web_search
  ├── memory: memory_store, memory_search, memory_delete, memory_note, memory_read
  ├── soul: soul_read, soul_edit
  └── mcp (via McpToolBridge):
        ├── McpClient[filesystem] → stdio → npx server-filesystem
        └── McpClient[internal-api] → HTTP → localhost:4000/mcp

Component	Role
McpClient	Connects to one MCP server; handles handshake, list_tools, call_tool
McpManager	Manages multiple McpClient instances per agent
McpToolBridge	Adapts an MCP tool into the internal Tool trait