JSON-RPC Transport

Standard HTTP alternative to MCP’s SSE transport

DataGrout exposes a JSON-RPC 2.0 endpoint alongside MCP. Same tools, same authentication, but over stateless HTTP POST. Ideal for scripts, serverless functions, legacy systems, and anything that can make an HTTP request.

Endpoint

POST https://gateway.datagrout.ai/servers/{server_uuid}/rpc

Replace {server_uuid} with your server’s UUID, found on the server detail page.

Authentication

Pass the same credentials you’d use for MCP:

# Bearer token
curl -X POST https://gateway.datagrout.ai/servers/YOUR_UUID/rpc \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "params": {}, "id": 1}'

mTLS and OAuth 2.1 are also supported. See Authentication for details.

Request Format

All requests follow JSON-RPC 2.0:

{
  "jsonrpc": "2.0",
  "method": "METHOD_NAME",
  "params": {},
  "id": 1
}

Methods

tools/list

List all available tools on the server:

curl -X POST https://gateway.datagrout.ai/servers/YOUR_UUID/rpc \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "params": {}, "id": 1}'

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "tools": [
      {
        "name": "salesforce@1/get_leads@1",
        "description": "Retrieve leads from Salesforce CRM",
        "inputSchema": { ... }
      }
    ]
  },
  "id": 1
}

tools/call

Execute a specific tool:

curl -X POST https://gateway.datagrout.ai/servers/YOUR_UUID/rpc \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "salesforce@1/get_leads@1",
      "arguments": {"limit": 10}
    },
    "id": 2
  }'

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"leads\": [{\"Id\": \"00Q...\", \"Name\": \"John Doe\"}]}"
      }
    ],
    "_meta": {
      "receipt_id": "rcp_abc123",
      "credits": 1.0,
      "duration_ms": 145
    }
  },
  "id": 2
}

You can call any tool this way, including DataGrout’s own discovery and planning tools:

curl -X POST https://gateway.datagrout.ai/servers/YOUR_UUID/rpc \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "data-grout@1/discovery.discover@1",
      "arguments": {"goal": "get leads from CRM"}
    },
    "id": 3
  }'

Error Codes

Standard JSON-RPC 2.0 errors:

Code Meaning
-32700 Parse error (invalid JSON)
-32600 Invalid request (missing fields)
-32601 Method not found
-32602 Invalid params
-32603 Internal error

DataGrout-specific errors:

Code Meaning
-32000 Tool not found
-32001 Authentication failed
-32002 Insufficient credits
-32003 Rate limited
-32004 Tool execution failed (upstream error)

MCP vs JSON-RPC

MCP (SSE) JSON-RPC (HTTP POST)
Transport Server-Sent Events Standard HTTP
Streaming Yes No
Client complexity Medium (SSE handling) Low (any HTTP client)
Best for Interactive agents, long workflows Scripts, cron, serverless, legacy apps

Both endpoints support the same methods (tools/list, tools/call) and accept the same authentication. The Conduit SDK supports both transports.

Legacy Systems

The JSON-RPC endpoint is the easiest integration path for systems that can’t add MCP. Any language or runtime that can make an HTTP POST can use DataGrout – COBOL, VBA, shell scripts, cron jobs, AWS Lambda, or internal tools.

Conduit SDK

For programmatic use, the Conduit SDK is preferred over raw HTTP. It handles authentication, retries, cost tracking, and transport selection:

from datagrout_conduit import ClientBuilder

client = ClientBuilder() \
    .url("https://gateway.datagrout.ai/servers/YOUR_UUID/mcp") \
    .auth_bearer("YOUR_TOKEN") \
    .build()

tools = client.list_tools()
result = client.call_tool("salesforce@1/get_leads@1", {"limit": 10})

See Conduit SDK for full documentation.

Related