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 OAuth-capable MCP harness |
| `om_status` returns an auth error | Missing, expired, or incomplete OAuth login | Re-run the client auth flow: `codex mcp login omtx` in Codex, or `/mcp` inside Claude Code. |
| The client can connect but tools fail | The MCP URL is wrong or the hosted OAuth login was not completed | Verify the server URL is `https://agents.omtx.ai/mcp`, then complete the OAuth flow in the client. |
| 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
Complete OAuth login
In Codex, run `codex mcp login omtx`. In Claude Code, use `/mcp` and complete the browser login flow.
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 remote-MCP OAuth, use the direct Om API instead of the hosted MCP.