MCP for agents

Set up

Create a restricted API key in your dashboard. Give it only the model scopes you need, BILLING_READ for balance checks, a per-request cap, and a spend limit.

API keys

Hosted connection

For clients that support Streamable HTTP and secret headers:

URL: https://mcp.openmayhem.ai/mcp
Header: X-OpenMayhem-API-Key: sk-om-v1-...

Local stdio bridge

For clients that start a local MCP process, keep the key in the environment:

OPENMAYHEM_API_KEY=sk-om-v1-... npx -y @openmayhem/mcp

Client setup

Set the API key in the environment before starting the client. Use the hosted connection where secret headers are supported; use the stdio bridge for local-process clients.

# macOS / Linux
export OPENMAYHEM_API_KEY="sk-om-v1-..."

# Windows PowerShell
$env:OPENMAYHEM_API_KEY = "sk-om-v1-..."

Codex

Codex connects directly to the hosted server and reads the secret header from the environment.

# ~/.codex/config.toml
[mcp_servers.openmayhem]
url = "https://mcp.openmayhem.ai/mcp"
env_http_headers = { "X-OpenMayhem-API-Key" = "OPENMAYHEM_API_KEY" }
default_tools_approval_mode = "approve"

Claude Code

Claude Code starts the stdio bridge. Restart Claude after adding the server.

claude mcp add --scope user openmayhem -- npx -y @openmayhem/mcp
claude mcp get openmayhem

Hermes

Hermes starts the stdio bridge and can verify tool discovery with its MCP test command.

hermes mcp add openmayhem --command npx --args -y @openmayhem/mcp
hermes mcp test openmayhem

OpenClaw

OpenClaw starts the stdio bridge from its MCP server configuration.

// ~/.openclaw/openclaw.json
{
  "mcp": {
    "servers": {
      "openmayhem": {
        "command": "npx",
        "args": ["-y", "@openmayhem/mcp"]
      }
    }
  }
}

OpenCode

OpenCode connects directly to the hosted server and resolves the API key from the environment.

// opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "openmayhem": {
        "type": "remote",
        "url": "https://mcp.openmayhem.ai/mcp",
        "oauth": false,
        "headers": {
          "X-OpenMayhem-API-Key": "{env:OPENMAYHEM_API_KEY}"
        }
      }
    }
  }
}

Your first MCP call

Every paid call follows the same four-step flow.

1. Discover. Use list_models to filter live routes, then get_model to read the selected model’s exact request contract.
2. Estimate. Pass the endpoint, model and exact request to estimate_request. It validates the request, creates no hold and returns a ten-minute estimate.
3. Execute. Review the estimate, then pass the unchanged request, estimate_id and an explicit max_cost_usd to the matching paid tool.
4. Collect. Text and embeddings return directly. Media and workflows return a job_id; use get_job, then get_artifact.

Exact estimate and execution

The request object must remain identical between estimate_request and the paid tool. The model pages contain ready-to-copy MCP calls for every supported model.

Tool: estimate_request
{
  "endpoint": "EMBEDDINGS",
  "model": "qwen/qwen3-embedding-4b",
  "request": {
    "input": ["First chunk", "Second chunk"],
    "dimensions": 1536,
    "encoding_format": "float"
  }
}

Tool: embed
{
  "model": "qwen/qwen3-embedding-4b",
  "request": {
    "input": ["First chunk", "Second chunk"],
    "dimensions": 1536,
    "encoding_format": "float"
  },
  "estimate_id": "<estimate_id from estimate_request>",
  "max_cost_usd": "<maximum_cost_usd from estimate_request>"
}

Open the model catalog for model-specific MCP examples.

Tools

Free tools list models, read model details, estimate exact requests, check balance, count tokens, poll or cancel jobs, and create short-lived artifact links. They do not spend model credit.

Discovery and control

Paid tools run chat, Responses, embeddings, images, video, speech, transcription, audio, music, and workflows. Each paid call needs a recent estimate_id and an explicit max_cost_usd.

Run models

Routing controls

Add the same routing object to estimate_request and the paid tool when you need a specific trust tier, context size, quantization, provider set, throughput, admission wait or price ceiling.

{
  "min_attestation_tier": 2,
  "min_context_tokens": 131072,
  "quantization": "nvfp4",
  "preferred_providers": ["<64-character provider id>"],
  "hedge": false,
  "min_throughput_tokens_per_second": 20,
  "max_wait_ms": 60000,
  "max_input_price_per_million_usd": "0.10",
  "max_output_price_per_million_usd": "0.50",
  "max_representative_request_price_usd": "0.25"
}

Jobs and artifacts

Image, video, speech, transcription, generated audio, music and workflows are asynchronous. The paid tool returns a durable job handle. Poll get_job until it succeeds or fails; then use get_artifact for each artifact_id.

Tool: get_job
{ "job_id": "<job_id from the paid tool>" }

Tool: get_artifact
{ "artifact_id": "<artifact_id from get_job>", "download": false }

Tool: cancel_job
{ "job_id": "<job_id from the paid tool>" }

cancel_job requests cancellation. Work already completed can still settle. Artifact links are short-lived, so request a fresh link when needed.

Retries and idempotency

Omit idempotency_token for normal calls. Set it only when retrying the same logical paid call with the same estimate and request. Use a new estimate and token for new work.

Runtime and size limits

MCP does not impose a generation or job runtime deadline. Long model calls may continue until the caller cancels, the provider finishes or the service is shut down. Body and upload limits still protect memory, and max_wait_ms remains an admission wait.

How payment works

An estimate creates no hold. When a paid call starts, OpenMayhem reserves at most the approved maximum on one eligible balance rail. Signed usage settles the actual cost and releases the rest. FIAT, TNK, and TAP remain separate and are never combined for one request.

Failures and retries

Tool errors return a stable code, message and HTTP status. Correct validation errors before retrying. Retry availability errors with bounded backoff. If billing is reconciling or the outcome is unknown, inspect the same job or request instead of starting duplicate paid work.

Revoke the API key in your dashboard to stop access immediately.