MCP Protocol API

The MCP Protocol API provides JSON-RPC 2.0 endpoints for MCP clients to interact with aggregated tools.

Endpoints

POST /v1/mcp/:projectSlug/request

JSON-RPC 2.0 endpoint for MCP protocol requests.

Path Parameters:

projectSlug (string) - Project identifier

Headers:

Content-Type: application/json
Authorization: Bearer <api-key> (if project requires auth)

GET/POST /v1/mcp/:projectSlug/sse

SSE (Server-Sent Events) bridge for streaming tool calls.

Headers:

Accept: text/event-stream
Authorization: Bearer <api-key> (if project requires auth)

MCP Methods

initialize

Establishes a session and negotiates protocol version/capabilities.

Request:

{
  "jsonrpc": "2.0",
  "id": "0",
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {},
    "clientInfo": { "name": "client", "version": "1.0.0" }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": "0",
  "result": {
    "protocolVersion": "2025-03-26",
    "capabilities": {},
    "serverInfo": { "name": "RouterMCP", "version": "1.0.0" }
  }
}

tools/list

List all enabled tools from all configured servers.

Request:

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

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "github.create_issue",
        "description": "Create a new issue",
        "inputSchema": {
          "type": "object",
          "properties": {
            "title": { "type": "string" },
            "body": { "type": "string" }
          },
          "required": ["title"]
        }
      }
    ]
  }
}

Tools are namespaced as {serverAlias}.{toolName} to prevent conflicts.

tools/call

Execute a tool on the appropriate upstream server.

Request:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "github.create_issue",
    "arguments": {
      "title": "Bug report",
      "body": "Issue description"
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Issue created: #123"
      }
    ]
  }
}

routermcp.searchMcpForTask

Meta-tool for ranking enabled tools by task description.

Request:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "routermcp.searchMcpForTask",
    "arguments": {
      "taskDescription": "create a GitHub issue for a bug",
      "topK": 5
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Top tools for task:\n1. github.create_issue (score: 0.89)\n2. github.update_issue (score: 0.45)"
      }
    ]
  }
}

SSE Streaming

The SSE endpoint returns events in this format:

Content-Type: text/event-stream

data: {"type":"progress","message":"Starting..."}

data: {"type":"result","result":{"success":true}}

data: [DONE]

Code Examples

JavaScript

async function callTool(projectSlug, apiKey, toolName, args) {
  const response = await fetch(
    `https://gateway.routermcp.com/v1/mcp/${projectSlug}/request`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${apiKey}`
      },
      body: JSON.stringify({
        jsonrpc: '2.0',
        id: Date.now(),
        method: 'tools/call',
        params: { name: toolName, arguments: args }
      })
    }
  );
  
  const data = await response.json();
  if (data.error) throw new Error(data.error.message);
  return data.result;
}

Python

import requests

def call_tool(project_slug, api_key, tool_name, args):
    response = requests.post(
        f'https://gateway.routermcp.com/v1/mcp/{project_slug}/request',
        headers={
            'Content-Type': 'application/json',
            'Authorization': f'Bearer {api_key}'
        },
        json={
            'jsonrpc': '2.0',
            'id': 1,
            'method': 'tools/call',
            'params': {'name': tool_name, 'arguments': args}
        }
    )
    data = response.json()
    if 'error' in data:
        raise Exception(data['error']['message'])
    return data['result']

cURL

curl -X POST 'https://gateway.routermcp.com/v1/mcp/my-project/request' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer rmc_your_api_key' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

MCP Protocol API

On this page