deeprelay MCP server

This server connects Claude Code, Claude Desktop, Cursor, or any other MCP client straight to the deeprelay serverless inference API. The agent can browse models and their prices, run chat, embeddings, image and video generation inside a budget you approve, read your balance and usage, manage webhook endpoints, lower or clear your spending limit, and create checkout or billing links, all without leaving the editor.

29 tools in three tiers: reads are free, writes confirm once, money tools quote a price and require explicit confirmation. The server enforces these rules, so they do not depend on the agent behaving well.

This is a local stdio server. Your client spawns it as a subprocess and talks JSON-RPC over stdin/stdout. Nothing is hosted or proxied: your API key stays on your machine, and the server calls https://api.deeprelay.ai/v1 directly.

Full documentation: https://deeprelay.ai/docs/mcp

Requirements

• Node 22 or newer
• A deeprelay API key, created in the dashboard

Setup

The server runs with npx -y @deeprelay/mcp@latest. Your client launches it for you.

Claude Code: .mcp.json

{
  "mcpServers": {
    "deeprelay": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@deeprelay/mcp@latest"],
      "env": {
        "DEEPRELAY_API_KEY": "${DEEPRELAY_API_KEY}"
      }
    }
  }
}

Claude Code fills in ${DEEPRELAY_API_KEY} from your shell when it spawns the server, so the key stays out of the file and out of version control.

Claude Desktop: claude_desktop_config.json

Claude Desktop does not expand shell variables, so write the value literally:

{
  "mcpServers": {
    "deeprelay": {
      "command": "npx",
      "args": ["-y", "@deeprelay/mcp@latest"],
      "env": {
        "DEEPRELAY_API_KEY": "deeprelay_live_..."
      }
    }
  }
}

The file is at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows. Restart the app after editing it.

For Cursor and other clients, see https://deeprelay.ai/docs/mcp.

Restart your client, then ask the agent to run deeprelay_auth_status. If the key is set up correctly, it returns your balance, spending limit and session budget.

Configuration

| Variable | Required | Meaning | | --- | --- | --- | | DEEPRELAY_API_KEY | yes | The API key. Put it in the client's env block only; it must never be passed in args/argv, where it would show up in ps output and shell history. | | DEEPRELAY_API_BASE | no | Base URL override, for example https://api.demo.deeprelay.ai/v1. Unset means production (https://api.deeprelay.ai/v1). |

Startup is offline. The server checks that the key is present and that the base URL is valid, and makes no network call at boot. A bad key surfaces as a clear error on the first tool call. The key is never echoed in a result, an error or a confirmation prompt.

Use a dedicated key for agent work, so you can revoke it on its own and see its usage separately. A read_only key covers all 17 free tools and cannot write or spend. Checkout, the billing portal and spending-limit changes also need the org-admin role. No key scope limits how much a key can spend. Your organization's spending limit and the session budget below do.

The three tiers

| Tier | Tools | What happens before it runs | | --- | --- | --- | | Free, read-only | 17 | Nothing. No confirmation, no charge, no change. | | Writes: single confirmation | 8 | One confirmation. The first call describes the change and returns a confirmation_token. The second call, with the same arguments plus the token, runs it. | | Money tools | 4 | A price. Priced from the catalog, then checked against the per-call ceiling and the session budget. |

Tokens are single-use, expire after five minutes, and are bound to the exact arguments that were quoted. No argument or instruction can replace a token. Where the client supports MCP elicitation, the server asks you directly and your answer goes through the same token.

Money tools: one session budget

Chat, embeddings, image and video share one session budget, and a session is one server process.

• The first money call asks you to approve a $5.00 session budget. The agent can propose a different amount with session_budget_usd ($1–$100). Confirming approves the budget and runs the call.
• Calls inside the budget then run with no further prompt.
• Any single call estimated above the $0.50 per-call ceiling is confirmed on its own. The ceiling is checked before the budget. A model with no published rate is treated the same way and is never assumed to be free.
• When the budget is spent, the next call asks for a new budget.

Estimates are reserved before each call and replaced by the actual cost afterwards. A failed call releases its reservation.

Video is quoted as a floor, not a cap. deeprelay_videos_create prices the clip the way the platform bills it, per second of the requested seconds (the model's default length when omitted), and reserves that floor. When deeprelay_videos_get or deeprelay_videos_list sees the job completed, the reservation settles at the actual cost_cents. Failed, cancelled or expired jobs are not billed. If the server exits before the job finishes, the reservation is dropped and the real charge appears in deeprelay_usage_get and deeprelay_balance_get.

Do not run a spend-capable agent with the client's own approval prompts disabled. The client could then accept confirmations for you. Set an organization spending limit as the ceiling that lasts across sessions.

Writes: one confirmation

• deeprelay_webhooks_create states that deeprelay will send event data to this URL. The signing secret is returned once and can never be read again.
• deeprelay_spending_limit_update is lower-only: a raise is refused before any confirmation exists. Raise a limit in the dashboard.
• deeprelay_spending_limit_clear removes the limit entirely, after one confirmation that names the limit and says inference is then bounded only by your balance. With no limit set it reports "nothing to clear" and changes nothing. From the agent's side a limit can be lowered or cleared, never raised.
• deeprelay_subscription_checkout, deeprelay_billing_portal and deeprelay_deposits_create_crypto only create links (or a deposit address). They never charge. Nothing is paid until you complete the step yourself.
• deeprelay_deposits_create_crypto is listed only on accounts with crypto deposits enabled. It stays hidden at startup and appears once the account is shown to have the feature.

Tools

Free, read-only (17): deeprelay_auth_status, deeprelay_health, deeprelay_models_list, deeprelay_models_get, deeprelay_inference_preflight, deeprelay_usage_get, deeprelay_balance_get, deeprelay_spending_limit_get, deeprelay_subscription_get, deeprelay_deposits_list, deeprelay_deposits_get, deeprelay_referrals_get, deeprelay_webhooks_list, deeprelay_webhooks_get, deeprelay_videos_list, deeprelay_videos_get, deeprelay_videos_content.

Writes: single confirmation (8): deeprelay_webhooks_create, deeprelay_webhooks_delete, deeprelay_spending_limit_update, deeprelay_spending_limit_clear, deeprelay_subscription_checkout, deeprelay_billing_portal, deeprelay_deposits_create_crypto, deeprelay_videos_cancel.

Money (4): deeprelay_chat_completion, deeprelay_embeddings_create, deeprelay_images_generate, deeprelay_videos_create.

deeprelay_health calls the unauthenticated liveness endpoint, so it answers even when the key is wrong or revoked; the server itself still needs DEEPRELAY_API_KEY set to start. deeprelay_usage_get reports serverless inference usage: optional modality (chat, image, video, embedding), model, bucket, start and end; with no modality or model it covers all four modalities and returns total_cost_cents plus per-modality subtotals. It follows pages itself and never counts a row twice; truncated: true means the totals cover only the rows returned, so narrow start/end. deeprelay_videos_content saves the MP4 to a local file (under the system temp directory by default, or an absolute output_path) instead of returning it inline. Because it writes a file it advertises readOnlyHint: false and idempotentHint: false; it still costs nothing and needs no confirmation.

Per-tool arguments and the full guide are at https://deeprelay.ai/docs/mcp.

Support

See https://deeprelay.ai/docs.

License

Apache-2.0