CorpusIQ MCP Troubleshooting¶

Common issues when connecting CorpusIQ to Hermes Agent.

"Chat not found" or 401 errors on cron jobs¶

Symptom: Crons that use CorpusIQ fail with 401 or "Chat not found" delivery errors.

Root cause: The CorpusIQ JWT access token expires after 60 minutes. Cron jobs that run infrequently will have an expired token.

Fix: Use the refresh token flow. The server now mints a 30-day refresh token alongside the 60-minute access token. Save both from the device OAuth response. When the access token expires, POST grant_type=refresh_token to /oauth/token:

curl -X POST https://mcp2.corpusiq.io/oauth/token \
  -d "grant_type=refresh_token&refresh_token=<saved_value>"

For crons, refresh first, write the new access token into config.yaml, then run the one-shot:

curl -s -X POST https://mcp2.corpusiq.io/oauth/token \
  -d "grant_type=refresh_token&refresh_token=<saved_value>"
hermes -z "your cron task"

The wrapper around the cron owns the refresh and the config.yaml write, so the agent always starts with a valid JWT.

If you are still on an older JWT obtained before July 28, 2026, do one device OAuth reconnect to receive the refresh token.

Tool calls return empty or "Tool execution failed"¶

Symptom: CorpusIQ tools return "Retrieved 0 results" or "Tool execution failed" even when data exists on other clients (e.g., Claude.ai).

Root cause: Tool call parameters are passed flat alongside action instead of nested inside params.

Fix: All CorpusIQ MCP tool calls must nest query parameters inside the params key:

# CORRECT
await session.call_tool("search_console_connector", {
    "action": "get_performance",
    "params": {
        "site_url": "sc-domain:corpusiq.io",
        "start_date": "2026-07-01",
        "end_date": "2026-07-28",
        "dimensions": ["query"],
        "row_limit": 10
    }
})

# WRONG - flat params silently fail
await session.call_tool("search_console_connector", {
    "action": "get_performance",
    "site_url": "sc-domain:corpusiq.io",
    ...
})

The tool inputSchema defines only action and params as properties. All query parameters go inside params.

"mcpServer not found"¶

Symptom: Hermes reports the CorpusIQ MCP server is not found.

Fix: Verify the MCP config entry:

mcp_servers:
  corpusiq:
    url: "https://mcp2.corpusiq.io/mcp"
    transport: "streamable-http"

Run hermes mcp list to verify it's registered.

OAuth device link expired¶

Symptom: The device auth URL opened in browser says "link expired."

Fix: The device auth link is valid for 15 minutes. Run hermes mcp connect corpusiq again to get a fresh link. Open immediately.

Tools not showing up¶

Symptom: CorpusIQ connects but no tools appear.

Fix: 1. Verify you've connected at least one business tool in the CorpusIQ dashboard 2. Tools are dynamically registered - you need an active tool connection 3. Run hermes mcp tools corpusiq to see available tools

"Rate limit exceeded" on GitHub API¶

Symptom: GitHub API calls return 403 with rate limit headers.

Fix: 1. Check current rate: curl -H "Authorization: token YOUR_TOKEN" https://api.github.com/rate_limit 2. Rate limit resets at the top of each hour 3. Use authenticated requests - unauthenticated gets 60/hr, authenticated gets 5,000/hr

Fork restriction (403 on fork)¶

Symptom: 403: "You cannot fork this repository at this time"

Root cause: GitHub anti-automation blocks on accounts that make rapid API calls.

Fixes: 1. Wait 1-2 hours - restriction auto-lifts 2. Use a different GitHub account 3. Reduce API call frequency (sub-1/sec)

More help: github.com/CorpusIQ/corpusiq-docs