Om MCP Troubleshooting
Common setup and runtime problems when connecting Claude, Codex, Cursor, VS Code, Copilot, Gemini, Grok, 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 Claude, Codex, Cursor, VS Code, or the MCP client you added |
| `om_status` returns an auth error | Missing, expired, or incomplete OAuth login | Re-run the client auth flow. Codex: `codex mcp login --scopes email omtx`. Claude Code: `/mcp`. Cursor: Connect in Tools & MCP. Gemini: `/mcp auth omtx`. |
| 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
Check client authentication
Complete the client OAuth flow. Codex: `codex mcp login --scopes email omtx`. Claude Code: `/mcp`. Cursor: Connect in Tools & MCP. Gemini: `/mcp auth omtx`.
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.
- Cursor desktop uses a local OAuth callback. Cursor on the web and Cursor Agents are not enabled yet.