# MCP for agents Use OpenMayhem models from an MCP-compatible agent through the hosted Streamable HTTP endpoint at `https://mcp.openmayhem.ai/mcp`, or through the local stdio bridge `@openmayhem/mcp` after publication. The hosted server reads `X-OpenMayhem-API-Key`. The stdio bridge reads `OPENMAYHEM_API_KEY`. An API key is never a tool argument. ## Connect Set the key before starting a client: ```bash export OPENMAYHEM_API_KEY="sk-om-v1-..." ``` Windows PowerShell: ```powershell $env:OPENMAYHEM_API_KEY = "sk-om-v1-..." ``` ### Hosted connection ``` URL: https://mcp.openmayhem.ai/mcp Header: X-OpenMayhem-API-Key: sk-om-v1-... ``` ### Codex ```toml # ~/.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 ```bash claude mcp add --scope user openmayhem -- npx -y @openmayhem/mcp claude mcp get openmayhem ``` ### Hermes ```bash hermes mcp add openmayhem --command npx --args -y @openmayhem/mcp hermes mcp test openmayhem ``` ### OpenClaw Add this to `~/.openclaw/openclaw.json`: ```json { "mcp": { "servers": { "openmayhem": { "command": "npx", "args": ["-y", "@openmayhem/mcp"] } } } } ``` ### 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}" } } } } } ``` ChatGPT directory support requires OpenMayhem account linking through OAuth. It is not enabled in this preview. Never paste an API key into a prompt or MCP tool argument. ## The four-step paid-call flow 1. **Discover:** use `list_models`, then `get_model` to read the exact request contract of the selected live model. 2. **Estimate:** call `estimate_request` with the endpoint, model and exact request. This validates the request, creates no hold and returns a ten-minute `estimate_id`, expected cost and maximum hold. 3. **Execute:** pass the same request without changes, the `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`; poll `get_job`, then use `get_artifact`. Example: ```json // estimate_request { "endpoint": "EMBEDDINGS", "model": "qwen/qwen3-embedding-4b", "request": { "input": ["First chunk", "Second chunk"], "dimensions": 1536, "encoding_format": "float" } } ``` ```json // embed { "model": "qwen/qwen3-embedding-4b", "request": { "input": ["First chunk", "Second chunk"], "dimensions": 1536, "encoding_format": "float" }, "estimate_id": "", "max_cost_usd": "" } ``` The `request` object must stay identical between estimation and execution. Each model page at https://openmayhem.ai/models includes exact MCP examples built from that model's live request contract. ## Free discovery and control tools | Tool | Use | Main inputs | Result | | --- | --- | --- | --- | | `list_models` | Filter and page through live models, capabilities, prices, speed, context and availability. | endpoint, modality, availability and routing filters, sort, limit, cursor | Model summaries and `next_cursor` | | `get_model` | Read one model's live request contract, pricing, limits and routes. | model | Full model record | | `estimate_request` | Validate an exact paid request without spending credit or creating a hold. | endpoint, model, request, optional routing | `estimate_id`, expected cost, maximum hold and route data | | `get_balance` | Read account credit. | include_rails | Posted, reserved and available credit | | `count_tokens` | Count with the selected model's tokenizer. | model plus exactly one of prompt or messages | Token count and optional token IDs | | `get_job` | Inspect an owned async job. | job_id | Status, billing state, cost and artifacts | | `cancel_job` | Request job cancellation. | job_id | Current cancellation/job state | | `get_artifact` | Create a short-lived link for an owned artifact. | artifact_id, download | Metadata and HTTPS resource link | ## Paid model tools Every paid tool uses this envelope: `model`, `request`, `estimate_id`, `max_cost_usd`, and optional `routing` and `idempotency_token`. | Tool | Endpoint | Use | Result | | --- | --- | --- | --- | | `chat` | CHAT | Chat Completions for text or multimodal models. | Chat response | | `create_response` | RESPONSES | OpenAI Responses-compatible request. | Responses-compatible response | | `embed` | EMBEDDINGS | One or batched embeddings; order and dimensions are preserved. | Embedding vectors and usage | | `generate_image` | IMAGES | Image generation. | Durable job handle | | `generate_video` | VIDEOS | Video generation. | Durable job handle | | `generate_speech` | AUDIO_SPEECH | Text to speech. | Durable job handle | | `transcribe_audio` | AUDIO_TRANSCRIPTIONS | Transcribe bounded base64 audio. | Durable job handle | | `generate_audio` | AUDIO_GENERATIONS | General audio generation. | Durable job handle | | `generate_music` | MUSIC | Music generation. | Durable job handle | | `run_workflow` | WORKFLOWS | Run a catalog-supported graph with its admitted files and controls. | Durable job handle | ## Routing controls Use the same optional `routing` object for estimation and execution: ```json { "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" } ``` `max_wait_ms` is only the provider-admission wait. It is not a generation or async-job runtime limit. `preferred_providers` is a strict ordered set; failover does not leave it. Hedging applies to text generation and cannot be combined with a preferred-provider list. ## Jobs, artifacts and cancellation Image, video, speech, transcription, audio, music and workflow calls are asynchronous: ```json // get_job { "job_id": "" } // get_artifact { "artifact_id": "", "download": false } // cancel_job { "job_id": "" } ``` Poll the same job until it succeeds or fails. Cancellation is a request; work already completed can still settle. Artifact links are short-lived, so call `get_artifact` again when a link expires. ## Payment and cost controls An estimate creates no hold. Execution reserves at most the approved `max_cost_usd` on one eligible balance rail. Signed usage settles the actual cost and releases the remainder. FIAT, TNK and TAP remain separate and are never combined for one request. Funding stays on https://openmayhem.ai/dashboard/credits. MCP never collects card details, wallet keys, transaction hashes or payment credentials. ## Retries, runtime and errors Omit `idempotency_token` for normal calls. Set it only when retrying the same logical paid call with the same estimate and unchanged request. New work uses a new estimate and token. MCP imposes no generation or job runtime deadline. A long model call may run until the caller cancels, the provider completes, or the service shuts down. Body and upload limits still protect memory, and `max_wait_ms` remains an admission wait. Tool errors contain a stable code, message and HTTP status. Correct validation errors before retrying. Retry availability errors with bounded backoff. If the outcome is unknown or billing is reconciling, inspect the same job or request instead of submitting duplicate paid work. Revoke the API key in the dashboard to stop access immediately.