HTTP API

The MCP Gateway exposes an HTTP endpoint for AI clients to connect to. All communication follows the MCP specification (JSON-RPC 2.0).

Endpoint

Property	Value
URL	http://localhost:8989/mcp
Method	POST
Content-Type	application/json
Auth	None required for localhost (see Configuration)

Request Format

All requests follow JSON-RPC 2.0:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "context7_search",
    "arguments": {
      "query": "React useEffect"
    }
  },
  "id": 1
}

Context Parameter

Include workspace context to enable proper server scoping and credential resolution:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "supabase_query",
    "arguments": { "table": "users" },
    "_context": {
      "cwd": "/home/user/my-project"
    }
  },
  "id": 1
}

The _context.cwd field tells the gateway which workspace the request is from, enabling proper credential resolution for workspace-scoped servers.

Supported Methods

Method	Description
tools/list	List all available tools from configured servers
tools/call	Execute a tool on a backend server
resources/list	List available resources
resources/read	Read resource content
prompts/list	List available prompts
prompts/get	Get prompt with arguments
ping	Keepalive (returns empty object)

Response Format

Success

{
  "jsonrpc": "2.0",
  "result": {
    "tools": [
      {
        "name": "context7_search",
        "description": "Search library documentation",
        "inputSchema": { ... }
      }
    ]
  },
  "id": 1
}

Error

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32600,
    "message": "Server 'context7' not available"
  },
  "id": 1
}

Health & Status

Health Check

GET http://localhost:8989/health

{
  "status": "healthy",
  "version": "1.0.0",
  "uptime_seconds": 3600
}

Status

GET http://localhost:8989/status

{
  "gateway": {
    "version": "1.0.0",
    "uptime_seconds": 7200,
    "port": 8989
  },
  "servers": {
    "context7": { "status": "running", "memory_mb": 48 },
    "supabase": { "status": "running", "memory_mb": 52 },
    "github": { "status": "idle" }
  },
  "connections": {
    "active": 3,
    "total_requests": 1547
  }
}

Error Codes

Code	Meaning
-32700	Parse error (invalid JSON)
-32600	Invalid request
-32601	Method not found
-32602	Invalid params
-32603	Internal error
-32001	Server unavailable
-32002	Tool not found
-32003	Missing credentials

Examples

List Tools

curl -X POST http://localhost:8989/mcp   -H "Content-Type: application/json"   -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

Call a Tool

curl -X POST http://localhost:8989/mcp   -H "Content-Type: application/json"   -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "context7_search",
      "arguments": { "query": "useState hook" },
      "_context": { "cwd": "/home/user/my-app" }
    },
    "id": 2
  }'