{
  "access": "public",
  "type": "reference",
  "format": "markdown",
  "title": "JSON-RPC API",
  "chunked": true,
  "url": "https://library.datagrout.ai/jsonrpc",
  "summary": "**Standard HTTP alternative to MCP's SSE transport**",
  "content_markdown": "# JSON-RPC Transport\n\n**Standard HTTP alternative to MCP's SSE transport**\n\nDataGrout 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.\n\n---\n\n## Endpoint\n\n```\nPOST https://gateway.datagrout.ai/servers/{server_uuid}/rpc\n```\n\nReplace `{server_uuid}` with your server's UUID, found on the server detail page.\n\n---\n\n## Authentication\n\nPass the same credentials you'd use for MCP:\n\n```bash\n# Bearer token\ncurl -X POST https://gateway.datagrout.ai/servers/YOUR_UUID/rpc \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"jsonrpc\": \"2.0\", \"method\": \"tools/list\", \"params\": {}, \"id\": 1}'\n```\n\nmTLS and OAuth 2.1 are also supported. See [Authentication](authentication) for details.\n\n---\n\n## Request Format\n\nAll requests follow JSON-RPC 2.0:\n\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"method\": \"METHOD_NAME\",\n  \"params\": {},\n  \"id\": 1\n}\n```\n\n---\n\n## Methods\n\n### tools/list\n\nList all available tools on the server:\n\n```bash\ncurl -X POST https://gateway.datagrout.ai/servers/YOUR_UUID/rpc \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"jsonrpc\": \"2.0\", \"method\": \"tools/list\", \"params\": {}, \"id\": 1}'\n```\n\nResponse:\n\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"result\": {\n    \"tools\": [\n      {\n        \"name\": \"salesforce@1/get_leads@1\",\n        \"description\": \"Retrieve leads from Salesforce CRM\",\n        \"inputSchema\": { ... }\n      }\n    ]\n  },\n  \"id\": 1\n}\n```\n\n### tools/call\n\nExecute a specific tool:\n\n```bash\ncurl -X POST https://gateway.datagrout.ai/servers/YOUR_UUID/rpc \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"jsonrpc\": \"2.0\",\n    \"method\": \"tools/call\",\n    \"params\": {\n      \"name\": \"salesforce@1/get_leads@1\",\n      \"arguments\": {\"limit\": 10}\n    },\n    \"id\": 2\n  }'\n```\n\nResponse:\n\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"result\": {\n    \"content\": [\n      {\n        \"type\": \"text\",\n        \"text\": \"{\\\"leads\\\": [{\\\"Id\\\": \\\"00Q...\\\", \\\"Name\\\": \\\"John Doe\\\"}]}\"\n      }\n    ],\n    \"_meta\": {\n      \"receipt_id\": \"rcp_abc123\",\n      \"credits\": 1.0,\n      \"duration_ms\": 145\n    }\n  },\n  \"id\": 2\n}\n```\n\nYou can call any tool this way, including DataGrout's own discovery and planning tools:\n\n```bash\ncurl -X POST https://gateway.datagrout.ai/servers/YOUR_UUID/rpc \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"jsonrpc\": \"2.0\",\n    \"method\": \"tools/call\",\n    \"params\": {\n      \"name\": \"data-grout@1/discovery.discover@1\",\n      \"arguments\": {\"goal\": \"get leads from CRM\"}\n    },\n    \"id\": 3\n  }'\n```\n\n---\n\n## Error Codes\n\nStandard JSON-RPC 2.0 errors:\n\n| Code | Meaning |\n|------|---------|\n| `-32700` | Parse error (invalid JSON) |\n| `-32600` | Invalid request (missing fields) |\n| `-32601` | Method not found |\n| `-32602` | Invalid params |\n| `-32603` | Internal error |\n\nDataGrout-specific errors:\n\n| Code | Meaning |\n|------|---------|\n| `-32000` | Tool not found |\n| `-32001` | Authentication failed |\n| `-32002` | Insufficient credits |\n| `-32003` | Rate limited |\n| `-32004` | Tool execution failed (upstream error) |\n\n---\n\n## MCP vs JSON-RPC\n\n| | MCP (SSE) | JSON-RPC (HTTP POST) |\n|---|-----------|----------------------|\n| **Transport** | Server-Sent Events | Standard HTTP |\n| **Streaming** | Yes | No |\n| **Client complexity** | Medium (SSE handling) | Low (any HTTP client) |\n| **Best for** | Interactive agents, long workflows | Scripts, cron, serverless, legacy apps |\n\nBoth endpoints support the same methods (`tools/list`, `tools/call`) and accept the same authentication. The Conduit SDK supports both transports.\n\n---\n\n## Legacy Systems\n\nThe 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.\n\n---\n\n## Conduit SDK\n\nFor programmatic use, the Conduit SDK is preferred over raw HTTP. It handles authentication, retries, cost tracking, and transport selection:\n\n```python\nfrom datagrout_conduit import ClientBuilder\n\nclient = ClientBuilder() \\\n    .url(\"https://gateway.datagrout.ai/servers/YOUR_UUID/mcp\") \\\n    .auth_bearer(\"YOUR_TOKEN\") \\\n    .build()\n\ntools = client.list_tools()\nresult = client.call_tool(\"salesforce@1/get_leads@1\", {\"limit\": 10})\n```\n\nSee [Conduit SDK](conduit-sdk) for full documentation.\n\n---\n\n## Related\n\n- [Authentication](authentication) -- All supported auth methods\n- [Tools Reference](tools-reference) -- Available tools\n- [Quick Start](quick-start) -- Get started with your first call\n"
}