MCP server.

With it connected, the agent can browse the serverless model catalog and its prices, run chat completions, embeddings, image generation and video generation, read your balance and usage, manage webhook endpoints, lower or clear your spending limit, and hand you checkout or billing links. You never leave the editor or paste anything into a dashboard.

It is a local stdio server. Your client spawns it as a subprocess and talks JSON-RPC to it over stdin/stdout. Nothing is hosted or proxied, and your API key never leaves your machine. The server calls https://api.deeprelay.ai/v1 directly through the TypeScript SDK.

One of the 29 tools, deeprelay_deposits_create_crypto, is listed only on accounts with crypto deposits enabled. On every other account the client sees 28 tools.

§ 20.1Install¶

The server is published to npm as @deeprelay/mcp and runs on Node 22 or newer:

npx -y @deeprelay/mcp@latest

You usually don't run that yourself. Your MCP client runs it using the configuration in the next section. There is nothing to install globally and no separate npm install step, because npx fetches the package on first launch and caches it.

§ 20.2Client setup¶

The API key goes only in the env block of your client's MCP configuration. It must never be placed in args or anywhere on argv: arguments show up in ps output and shell history, and a credential belongs in neither. The server reads the key from its environment and nowhere else.

§20.2.1Claude Code¶

Create .mcp.json in your project root, or add to an existing one:

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

When Claude Code spawns the server it fills in that variable from your shell environment, so the key stays out of the file and out of version control. Export it once in your shell profile:

export DEEPRELAY_API_KEY=deeprelay_live_...

Restart the session, 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.

§20.2.2Claude Desktop¶

Claude Desktop starts servers with a minimal environment and 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 lives 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.

§20.2.3Cursor¶

Cursor uses the same mcpServers shape. Put the entry in your user-level ~/.cursor/mcp.json so a literal key never ends up in a repository:

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

§20.2.4Other clients¶

Any MCP client that can spawn a stdio server works the same way:

If your client only accepts one command line, use a wrapper script that exports the key and then runs npx. Never add the key to the arguments.

§ 20.3Authentication¶

Startup is offline and fails fast. At startup the server only checks that the key is present and that a base-URL override is a valid absolute http(s) URL. It makes no network call at boot, so a flaky connection can never look like a bad key. A bad key shows up as a clear authentication error on the first real tool call.

Call deeprelay_auth_status first. It confirms the key works and reports the API base, spending limit, prepaid balance and this session's budget in one call. deeprelay_health calls the API's unauthenticated liveness endpoint, so it answers even when the configured key is wrong or revoked, which is useful for telling an outage apart from a key problem. The server itself still refuses to start unless DEEPRELAY_API_KEY is set.

The server never echoes the key. No tool returns it, and it never appears in an error message or a confirmation prompt. Every error string passes through a redaction step first.

§20.3.1Use a dedicated key¶

Create a separate API key for agent use instead of reusing the one in your CI or your shell profile. You can revoke it on its own (the agent stops while your pipelines and CLI keep working), and its usage is attributed separately, so you can see what the agent spent.

• A read_only key works with every free tool and cannot use any write or money tool. The API rejects the request.
• A standard key can use all three tiers.
• deeprelay_subscription_checkout, deeprelay_billing_portal, deeprelay_spending_limit_update and deeprelay_spending_limit_clear also need the org-admin role on the account. That is an account-role check, not a key scope, so a 403 from them means you need an admin, not a new key.

§ 20.4Base URL¶

Leave DEEPRELAY_API_BASE unset and every call goes to production. To point the server at the demo environment instead:

"env": {
  "DEEPRELAY_API_KEY": "${DEEPRELAY_API_KEY}",
  "DEEPRELAY_API_BASE": "https://api.demo.deeprelay.ai/v1"
}

• Unset always means production. The package has no hidden non-production default, because a server that quietly pointed somewhere else would appear to work while billing the wrong account.
• The guardrail does not relax on a non-production base URL. Quote, confirm, execute works the same way wherever the server points.

§ 20.5The three-tier contract¶

Every tool sits in exactly one tier, and the tier decides what the server does before the tool can run: reads are free, writes confirm once, money tools quote a price and require explicit confirmation. None of this is advisory. The confirmation lives in each tier's shared wrapper, so no tool can join a guarded tier without it.

§20.5.1The two-call handshake¶

1. The first call runs nothing. It returns a summary of the change (for a money tool, the price and the budget reason) and a confirmation_token.
2. The agent shows you the summary. If you agree, it calls the same tool again with the same arguments plus that token. That second call executes.

Tokens are single-use, expire after five minutes, and are bound to the exact arguments and the tool that was quoted. If an argument changes, nothing runs and the server asks again. No argument, flag or instruction can replace a token, and a pre-authorization given before the price existed does not count. A failed call is never retried on the same approval.

Where a client supports MCP elicitation, the server asks you a yes/no question directly in the client's UI, and your answer goes through the same token. Client support varies, so you will often see the two-call flow instead. A “no” through elicitation cancels the token.

§20.5.2Money: one session budget¶

Four tools can create a charge: deeprelay_chat_completion, deeprelay_embeddings_create, deeprelay_images_generate and deeprelay_videos_create. They share one session budget, and a session is one server process. The budget lives in memory and ends when the process exits, because your approval ends with it.

1. Price it. The server estimates the call from the model's catalog rates. A model with no published rate for that kind of call is never treated as free. It is confirmed on its own.
2. Per-call ceiling. Above $0.50, the server quotes this one call. Confirming runs it and does not approve a budget.
3. Budget approval. With no budget approved yet, the server quotes a $5.00 session budget (or the amount in session_budget_usd). Confirming approves it and runs the call.
4. The wall. When settled spend has reached the budget, or the estimate is more than what remains, the server asks you to approve a new budget.
5. Otherwise it runs immediately, with no quote, token or prompt.

The ceiling is checked before the budget on purpose. Otherwise an oversized call in a session with no budget would show up as “needs a budget”, you would approve an ordinary $5.00 session, and the oversized call would run without ever being confirmed on its own.

• Chat is priced by tokens, with the completion bounded by max_tokens (default 1024), and settled on actual token usage.
• Embeddings are priced by input tokens and settled on actual prompt tokens.
• Images are priced per image, or per megapixel of the requested size, and settled on the images actually returned.
• Video is priced the way the platform bills it: the per-second rate times the requested length (the model's default length when omitted). That estimate is a floor, not a cap.

Each estimate is reserved before the call, so parallel calls cannot all spend the same remaining budget. After the call, the reservation is replaced by the actual cost, rounded up to whole cents per call the way the platform bills. A failed call releases its reservation. The wall counts settled actual costs only, never estimates.

§20.5.3Video: quoted as a floor, settled by a later read¶

• The quote is a floor. The final charge is only known when the job completes.
• The floor is reserved at create and counts against the session budget while the job runs.
• A later read settles it. When deeprelay_videos_get or deeprelay_videos_list sees the job completed, the reservation is replaced by the actual cost_cents, which the read reports.
• Jobs that don't finish are not charged. A job that ends failed, cancelled or expired, or that you cancel with deeprelay_videos_cancel, releases its reservation.
• If the session ends first, the reservation is dropped when the process exits. The job keeps running, and its real charge appears in deeprelay_usage_get and deeprelay_balance_get.

§20.5.4Writes: one confirmation, no price¶

Eight tools change account state without charging anything. No charge does not mean no consequence, so they use the same token handshake, and the quote describes the consequence instead of a price.

• Creating a webhook endpoint is an egress decision. The confirmation for deeprelay_webhooks_create says that deeprelay will send event data to that URL. Event types are always explicit. The signing secret is returned once and can never be read again.
• The spending limit can be lowered or cleared, never raised. deeprelay_spending_limit_update refuses any value that is not a strict decrease before a confirmation exists, and checks again just before running. It resends your current enforcement mode. deeprelay_spending_limit_clear removes the limit entirely; its confirmation names the limit and says inference is then bounded only by your balance. With no limit set it reports that there is nothing to clear. Both need org-admin.
• Payment links never charge. deeprelay_subscription_checkout, deeprelay_billing_portal and deeprelay_deposits_create_crypto only create a link or a deposit address. Nothing is paid until you complete the step yourself.
• Crypto deposits appear only where enabled. deeprelay_deposits_create_crypto is hidden when the server starts. It appears once a background check, or a deposits read, shows the account has crypto deposits enabled.

§ 20.6Tool reference¶

§20.6.1Free, read-only (17)¶

None of these change anything or cost money, and all of them work with a read_only key.

deeprelay_videos_content writes the MP4 on the machine running the server, under the OS temp directory by default, or at an absolute output_path. It never overwrites an existing file. Artifacts are kept for 24 hours after the job completes. Because it writes a file, it is the one tool in this tier that advertises readOnlyHint: false and idempotentHint: false, so a client that auto-approves read-only tools may still ask before running it. It changes nothing on your account and costs nothing.

§20.6.2Writes, single confirmation (8)¶

§20.6.3Money tools (4)¶

Each call is priced first and runs inside the session budget ($5.00 default, $0.50 per-call ceiling). Every money tool also accepts confirmation_token and session_budget_usd.

§ 20.7Related¶

• Inference API: the API underneath, with every modality these tools call.
• TypeScript SDK and Python SDK: the same API from code.
• The deeprelay CLI: the same capabilities from a terminal.
• Webhooks: how to verify a delivery to the endpoints the webhook tools manage.