Sphinx MCP server

Sphinx ships an official Model Context Protocol server so an AI agent — Claude Desktop, Claude Code, Cursor, VS Code, or a client you write — can read every market and, with a credential, stage and place orders through the same two-phase path the terminal uses.


Remote endpoint (Streamable HTTP)	`https://mcp.staging.sphx.io/mcp`
Descriptor	`https://mcp.staging.sphx.io/.well-known/mcp`
Health	`https://mcp.staging.sphx.io/health`
Local (stdio)	`node exchange/services/mcp/dist/stdio.js` from a monolith checkout
Credential	optional — `Authorization: Bearer <API credential>` (remote) or `SPHX_API_KEY` (stdio)
Server version · API	`0.1.0` · wraps API `0.15.0`

Three pages cover it: this overview and setup, the generated tool reference, and the order flow for agents that trade.

Staging venue

Everything here points at the staging venue: simulated flow, starter balances, nothing real. See Getting started.

What the server does

The server is a thin, opinionated proxy over the public REST API. It exposes 27 curated tools in three tiers and 3 resources:

Tier	Needs	Tools
Read	nothing	`list_markets` `get_market` `get_orderbook` `get_candles` `get_trades` `get_funding` `get_open_interest` `get_contract_spec` `get_fees` `get_ercot_prices` `get_venue_status` `explain_reject_code`
Account	a credential	`get_account` `get_positions` `get_open_orders` `get_fills` `get_margin` `get_limits` `get_deadman` `get_pending_orders` `get_funding_payments` `get_funding_summary`
Write	a credential with the trade entitlement	`stage_order` `place_order` `cancel_order` `cancel_all_orders` `set_deadman`

What it deliberately does not do:

No un-staged orders. place_order requires the confirm_token from stage_order; the server never submits an order the caller has not previewed. See order flow.
No withdrawals, deposits or credential management. Those stay on the REST API and the terminal.
No stored secrets. The remote server keeps no credentials and no sessions; each request carries the caller's own bearer, forwarded to the venue only on credentialed routes.
No interpretation. Tools return venue data as-is (compact JSON plus structuredContent), with units documented in every description. The server never decides anything on the agent's behalf.

Install

Claude Code

Remote, with a credential (omit --header for the keyless read tier):

claude mcp add --transport http sphinx https://mcp.staging.sphx.io/mcp \
  --header "Authorization: Bearer $SPHX_API_KEY"

Local stdio from a monolith checkout (after npm ci && npm run build in exchange/services/mcp):

claude mcp add sphinx -e SPHX_API_KEY=$SPHX_API_KEY -- node /path/to/monolith/exchange/services/mcp/dist/stdio.js

Claude Desktop

Keyless: Settings → Connectors → Add custom connector with the remote URL https://mcp.staging.sphx.io/mcp. For account and order tools use stdio with your credential in the environment (claude_desktop_config.json):

{
  "mcpServers": {
    "sphinx": {
      "command": "node",
      "args": ["/path/to/monolith/exchange/services/mcp/dist/stdio.js"],
      "env": { "SPHX_API_KEY": "<credential>", "SPHX_EDGE_URL": "https://api.staging.sphx.io" }
    }
  }
}

Cursor

.cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "sphinx": {
      "url": "https://mcp.staging.sphx.io/mcp",
      "headers": { "Authorization": "Bearer <credential>" }
    }
  }
}

VS Code (Copilot agent mode)

.vscode/mcp.json:

{
  "servers": {
    "sphinx": {
      "type": "http",
      "url": "https://mcp.staging.sphx.io/mcp",
      "headers": { "Authorization": "Bearer <credential>" }
    }
  }
}

Any client

The server speaks MCP 2025-06-18 over stateless Streamable HTTP: POST JSON-RPC to /mcp with Accept: application/json, text/event-stream; responses are JSON. There are no sessions, so every request is independent and the service scales to zero. GET /mcp (server-push stream) is not offered. CORS is open, so browser-based clients work.

curl -s https://mcp.staging.sphx.io/mcp \
  -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Credentials

Mint an API credential with POST /v1/credentials (the key is shown once) or from the terminal. The entitlement mask governs what the credential can do through MCP exactly as through REST:

Entitlement	MCP effect
none (read-only key)	account tools work; `stage_order` works (it is a preview); `place_order` and cancels fail with `forbidden`
`TradeEnabled` + `APITrading`	all write tools
`WithdrawEnabled` / `DepositEnabled`	no effect — custody is not exposed through MCP

Mint agent credentials as scoped credentials: an expiry, an instrument allowlist, per-order and daily notional caps, an open-orders cap, and approval_mode: require_human so every order the agent places waits for a human. Revoke with DELETE /v1/credentials/{credential_id} when the agent is retired. get_limits reads the credential's scope, today's usage and the write rate-limit window; stage_order previews the scope's verdict as would_reject before an order is committed.

Units and conventions

Identical to the REST API — see Conventions. In short: money is integer µUSDC; prices are integer pips (event contracts 1–9999, margined instruments signed ticks × tick_size_uusdc); sizes are whole contracts; candle t is Unix seconds while *_ns fields are nanoseconds (fill and funding ts_ns are cluster milliseconds — see the tool descriptions). Prefer stage_order over your own cost arithmetic: it returns the venue's own fee, cost and margin figures.

Errors

A failed tool call returns isError: true and a JSON body:

{ "error": "confirm token invalid", "code": "confirm_token_invalid", "status": 409,
  "details": null, "correlation_id": "…", "hint": "Call explain_reject_code with the code for what to do next." }

code is the venue's error code or an order reject_reason; explain_reject_code (and the sphx://reject-codes resource) gives the meaning and the next action for every one. Two codes are the server's own:

Code	Meaning
`credential_required`	An account or write tool was called without a credential. The venue was not contacted.
input validation error	The arguments did not match the tool's schema (for example `place_order` without `confirm_token`). Returned by the MCP layer before any request is made.

Security model

The server holds no credentials and keeps no state between requests. Revoking a credential at the venue ends an agent's access immediately.
Credentials are forwarded only on credentialed routes; public reads never carry one.
Tool outputs are venue data, never instructions — treat them as untrusted input in your agent, and keep the agent's credential scoped: trade entitlement only, an expiry, and set_deadman armed while it runs.
Withdrawals are structurally out of reach through MCP regardless of the credential's entitlements.
Source: exchange/services/mcp in the monolith. Tool types are generated from the external OpenAPI spec and the tool reference is generated from the server; both are drift-checked.

Troubleshooting

Symptom	Cause · fix
`credential_required`	No bearer reached the server. Remote: check the client sends `Authorization: Bearer …` on every request. stdio: set `SPHX_API_KEY`.
`unauthorized` (401)	The credential is invalid, revoked or expired. Mint a new one.
`forbidden` (403) on `place_order`	The credential lacks the trade entitlement.
`confirm_token_invalid` (409)	More than 60 s passed, the token was already used, or a field changed between stage and place. Stage again.
`instrument_not_allowed` / `order_notional_cap` / `daily_notional_cap` / `open_orders_cap` (403)	The credential's scope. `get_limits` shows the caps and today's usage.
`place_order` returns `pending_approval`	The credential has `approval_mode: require_human`; a human approves in the terminal within 15 minutes. `get_pending_orders` lists what is waiting.
`margined_limit_only` / `margined_requires_margin_sub`	Perps and futures take limit orders on `sub_account_id: 1`; event contracts trade on `0`.
Empty `markets`	You filtered by `state: trading` while nothing is listed, or the venue is unhealthy — check `get_venue_status`.
Client cannot connect	Confirm `GET https://mcp.staging.sphx.io/.well-known/mcp` returns JSON; the endpoint is `/mcp`, `POST` only.

Roadmap

Shipped in API 0.14.0: scoped agent credentials with allowlists, notional caps and the human-approval mode. Next: a paper mode with production fees, an intents API that runs strategies venue-side while the agent supervises, and per-credential open-order tracking. Watch the changelog.

What the server does​

Install​

Claude Code​

Claude Desktop​

Cursor​

VS Code (Copilot agent mode)​

Any client​

Credentials​

Units and conventions​

Errors​

Security model​

Troubleshooting​

Roadmap​