MCP Integration

Gremia uses the Model Context Protocol (MCP) for all tool interactions. MCP is a JSON-RPC 2.0 based protocol that standardizes how AI agents communicate with tool servers.

What is MCP?

MCP (Model Context Protocol) provides a uniform interface for AI models to interact with external tools and data sources. Instead of each tool having its own API format, MCP defines a standard protocol:

graph LR
    A[AI Agent] -->|JSON-RPC 2.0| B[MCP Server]
    B -->|stdio / SSE / HTTP| C[External Service]
    C -->|Response| B
    B -->|Response| A

Every tool call in Gremia follows this protocol, ensuring consistency regardless of the underlying service (Google Sheets, GitHub, Slack, filesystem, etc.).

Transport Types

MCP supports three transport mechanisms:

Transport	Communication	Use Case
stdio	stdin/stdout	Local processes (most common)
sse	Server-Sent Events	Remote servers with streaming
streamable-http	HTTP POST/GET	Remote servers without streaming

Gremia Shell currently supports stdio transport. The Shell spawns MCP servers as child processes and communicates via stdin/stdout.

JSON-RPC 2.0 Messages

All MCP communication follows the JSON-RPC 2.0 specification.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "read_range",
    "arguments": {
      "spreadsheet_id": "abc123",
      "range": "Sheet1!A1:D10"
    }
  }
}

Response (success)

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[[\"Name\",\"Sales\"],[\"Alice\",\"1000\"]]"
      }
    ]
  }
}

Response (error)

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Spreadsheet not found"
  }
}

MCP Lifecycle in Gremia

1. Server Spawn

When a manifest is loaded, the Shell spawns each MCP server defined in mcp_requirements:

{
  "server_id": "google-sheets",
  "name": "Google Sheets MCP",
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "@anthropic/mcp-google-sheets"],
  "env": {
    "GOOGLE_CREDENTIALS": "/path/to/credentials.json"
  },
  "tools_used": ["read_range", "write_range", "create_sheet"]
}

The Shell executes:

GOOGLE_CREDENTIALS=/path/to/credentials.json npx -y @anthropic/mcp-google-sheets

2. Initialize Handshake

After spawning, the Shell sends an initialize request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "gremia-shell",
      "version": "0.1.0"
    }
  }
}

The server responds with its capabilities:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": { "listChanged": true }
    },
    "serverInfo": {
      "name": "google-sheets-mcp",
      "version": "1.0.0"
    }
  }
}

3. Tool Discovery

The Shell queries available tools:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "read_range",
        "description": "Read data from a spreadsheet range",
        "inputSchema": {
          "type": "object",
          "properties": {
            "spreadsheet_id": { "type": "string" },
            "range": { "type": "string" }
          },
          "required": ["spreadsheet_id", "range"]
        }
      }
    ]
  }
}

4. Tool Execution

When an agent needs a tool, the Cloud sends a tool_call message through the WebSocket tunnel. The Shell routes it to the appropriate MCP server:

sequenceDiagram
    participant C as Cloud
    participant S as Shell
    participant M as MCP Server

    C->>S: tool_call (server_id, tool_name, arguments)
    S->>M: JSON-RPC tools/call (stdin)
    M-->>S: JSON-RPC result (stdout)
    S->>C: tool_result (output)

JSON-RPC call sent to MCP server:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "read_range",
    "arguments": {
      "spreadsheet_id": "abc123",
      "range": "Sales!A1:D100"
    }
  }
}

5. Server Shutdown

When the manifest is unloaded or the Shell closes, each MCP server process is terminated:

1. The Shell sends a SIGTERM (or kills the process on Windows)
2. The process handle and stdio channels are cleaned up
3. The server entry is marked as "stopped"

MCP in the Manifest

The mcp_requirements array in the manifest defines which servers the Shell should spawn:

{
  "mcp_requirements": [
    {
      "server_id": "filesystem",
      "name": "Filesystem MCP",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-filesystem", "/data"],
      "tools_used": ["read_file", "write_file", "list_directory"]
    },
    {
      "server_id": "github",
      "name": "GitHub MCP",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_..."
      },
      "tools_used": ["create_issue", "list_prs", "merge_pr"]
    }
  ]
}

Fields

Field	Type	Required	Description
server_id	string	Yes	Unique identifier for routing tool calls
name	string	Yes	Human-readable server name
transport	enum	Yes	stdio, sse, or streamable-http
command	string	For stdio	Command to spawn the process
args	string[]	No	Command-line arguments
env	object	No	Environment variables for the process
url	string	For SSE/HTTP	Remote server URL
tools_used	string[]	Yes	Tools this server provides

Tool References in Agents

Agents reference tools using the server_id:tool_name format:

{
  "id": "data-analyst",
  "name": "Data Analyst",
  "tools": [
    "google-sheets:read_range",
    "google-sheets:write_range",
    "filesystem:read_file"
  ]
}

The system validates that every referenced server_id exists in mcp_requirements.

Tool Approval

Tools can be configured to require human approval:

1. Agent definition has approvals_required: true
2. Cloud sends tool_call with requires_approval: true
3. Shell displays an approval dialog to the user
4. User approves or rejects
5. On approval, Shell executes and returns result
6. On rejection, Shell returns an error result

This is critical for sensitive operations (file writes, emails, API calls with side effects).

Error Handling

MCP server fails to start

The Shell logs the error and marks the server as "error". The agent can still try to use other tools.

Tool call fails

The Shell sends a tool_result with success: false and the error message. The agent can retry or use a fallback strategy.

Server crashes mid-execution

If the MCP server process exits unexpectedly:

1. The Shell detects the broken pipe
2. The server is marked as "stopped"
3. Any pending tool calls receive an error response
4. The server can be restarted from the Servers panel

Supported MCP Servers

Gremia's MCP registry includes entries for 30+ server types. Common examples:

Server	Tools	Use Case
@anthropic/mcp-filesystem	read, write, list	Local file operations
@anthropic/mcp-github	issues, PRs, repos	GitHub integration
@anthropic/mcp-google-sheets	read, write, create	Spreadsheet automation
@anthropic/mcp-slack	send, read, channels	Team communication
@anthropic/mcp-sqlite	query, execute	Local database
@anthropic/mcp-puppeteer	navigate, screenshot	Web automation

For a complete list, see the MCP registry in the orchestrator at services/orchestrator/app/knowledge/mcp_registry.py.