Om MCP Troubleshooting
Common setup and runtime problems when connecting Codex, Claude Code, or other clients to the hosted Om MCP.
Start with a simple health check
If Om MCP is installed but you are not sure it is working, start with
om_status and pricing_get. Those are the fastest ways to verify the
connection and auth path.
Common issues
| Symptom | Likely cause | What to do |
|---|---|---|
| The MCP server does not appear in the client | The client was not restarted after config changes | Restart Codex, Claude Code, or the MCP-compatible harness |
| `om_status` returns an auth error | Missing or invalid Om API key | Recheck `OM_API_KEY` and confirm the client is sending either `Authorization: Bearer $OM_API_KEY` or `x-api-key: $OM_API_KEY`, depending on the client. |
| The client can connect but tools fail | The MCP URL or auth header is wrong | Verify the server URL is `https://agents.omtx.ai/mcp` and the auth mode matches the client: bearer token for Codex, `x-api-key` for Claude Code and other header-capable clients. |
| A workflow takes longer than expected | Some Om tools launch async jobs behind the scenes | Ask the client to wait on the job, inspect job status, or export the result after completion |
| You expected the client to know what tools exist | The server attached correctly, but you have not prompted it clearly | Ask for `om_status`, then ask for Diligence, Data Access, Jobs, or Hub workflows explicitly |
Verification workflow
If setup is not working
1
Check the URL
Confirm the MCP server is `https://agents.omtx.ai/mcp`.
2
Check the API key
Confirm your client is sending the right auth for that client: bearer token in Codex, or `x-api-key: $OM_API_KEY` in Claude Code and other header-capable clients.
3
Restart the client
Most MCP clients only discover newly added servers on startup.
4
Run `om_status`
This is the fastest server health check.
5
Run `pricing_get` or `datasets_catalog`
If those work, auth and tool registration are healthy.
When to move beyond MCP
- If you need strict retries, orchestration, or service-to-service integrations, move into the direct Om API.
- If you need long-running production logic, use the MCP to discover the workflow and the API to operationalize it.
- If a client does not support custom headers, use bearer auth instead of abandoning the hosted MCP.