POST /mcp
The Model Context Protocol endpoint: every grid call as a tool, over stateless Streamable HTTP.
Syntax
POST https://grid-lab.zyxio.xyz/mcp
x-api-key: <key>
content-type: application/json
accept: application/json, text/event-stream
{"jsonrpc": "2.0", "id": 1, "method": "<method>", "params": {...}}Request
| Name | Where | Required | Meaning |
|---|---|---|---|
x-api-key | header | yes, or Authorization | Your API key, or Authorization: Bearer <token> from Zyxio sign-in. |
accept | header | yes | Both application/json and text/event-stream, as MCP's Streamable HTTP transport requires. |
| body | body | yes | One JSON-RPC message: initialize, tools/list, tools/call and the rest of MCP. |
The server keeps no MCP session: send no mcp-session-id, and expect each request to stand alone. An MCP client library does all of this for you; see MCP for the client set-up and the tool list.
Response
200 OK with the JSON-RPC answer. A tools/call answer carries the underlying call's JSON body as text; an underlying status of 400 or higher sets isError: true.
Errors
| Status | Body | When | What to do |
|---|---|---|---|
401 | {"error": "unauthorized"}, with WWW-Authenticate: Bearer resource_metadata="https://grid-lab.zyxio.xyz/.well-known/oauth-protected-resource/mcp" | No credential, or one that is not valid. The header tells an MCP client where to start signing in. | Send a key, or let the client sign in with Zyxio. |
503 | {"error": "accounting_unavailable"} | Your key or Zyxio sign-in could not be checked because the account database did not answer in time. Nothing was done. | Retry shortly; the same request is safe to resend. |
403 | {"error": "forbidden"} | A valid Zyxio sign-in token whose identity has no account here, or whose account is suspended. | Accept your invitation first, or use a key. |
405 | {"jsonrpc": "2.0", "error": {"code": -32000, "message": "Method not allowed."}, "id": null} | GET /mcp or DELETE /mcp: there is no server push and no session to end. | Use POST. |
406 | {"jsonrpc": "2.0", "error": {"code": -32000, "message": "Not Acceptable: Client must accept both application/json and text/event-stream"}, "id": null} | The accept header lacks one of the two types. | Send both. |
A tool's own refusals, such as 402 insufficient_credit, arrive inside a 200 answer as a tool error.
Example
curl -s https://grid-lab.zyxio.xyz/mcp \
-H "x-api-key: $BROWSERGRID_API_KEY" \
-H "content-type: application/json" \
-H "accept: application/json, text/event-stream" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "grid_status", "arguments": {}}}'Billing
The endpoint itself is free and reserves nothing. Each tool is billed exactly as the call it makes, once: submit_batch as POST /batches, lease_session as POST /sessions, submit_compute_job as POST /jobs, and retry_job as POST /jobs/{jobId}/retry, which reserves credit again for an analytical job's new attempt; every other tool is a free read or a release.