How to Add CorpusIQ MCP to Hermes Agent¶

Hermes Agent can use CorpusIQ as an MCP server to query business data from 40+ tools. Here's how.

1. Get a CorpusIQ account¶

Sign up at corpusiq.io. Free trial, no credit card.

2. Connect your business tools¶

Go to your CorpusIQ dashboard. Connect tools via OAuth: - QuickBooks (read-only) - Stripe (read-only) - HubSpot (read-only) - Shopify (read-only) - GA4, Google Ads, Meta Ads, and 40+ more

Each takes 30 seconds. One click. No API keys to manage.

3. Add CorpusIQ MCP to Hermes¶

Add this to your Hermes Agent config (~/.hermes/config.yaml):

mcp_servers:
  corpusiq:
    url: "https://mcp2.corpusiq.io/mcp"
    transport: "streamable-http"
    headers:
      Authorization: "Bearer <jwt>"

The Authorization header carries the JWT obtained during device authentication. The transport must be streamable-http (not sse or stdio).

Or if using hermes mcp CLI:

hermes mcp add corpusiq --url https://mcp2.corpusiq.io/mcp --transport streamable-http

4. Authenticate¶

CorpusIQ uses OAuth 2.0 Device Authorization Grant for CLI tools and agent loops. The flow:

Generate a device code: POST https://mcp2.corpusiq.io/oauth/device/authorize
Open the returned verification_uri (https://mcp2.corpusiq.io/oauth/device/verify) in a browser, enter the user_code, and approve
Exchange the device code for tokens: POST https://mcp2.corpusiq.io/oauth/token with form data containing ONLY grant_type=urn:ietf:params:oauth:grant-type:device_code and device_code=<code>. Do NOT include client_id.
Save both access_token (60-min expiry) and refresh_token (30-day expiry) to mcp_tokens.json
Set the JWT in config: headers.Authorization: Bearer <access_token>

For the Python device login script, see the account's own token store (mcp_tokens.json) and the device flow above.

When the access token expires, refresh silently:

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

The refresh token flow is live in production. One device OAuth reconnect after July 28, 2026 mints the 30-day refresh credential. No hourly babysitting required.

5. Call tools correctly¶

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

# CORRECT - params nested
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 return empty or fail
await session.call_tool("search_console_connector", {
    "action": "get_performance",
    "site_url": "...",
    ...
})

The tool inputSchema defines action and params as the only two properties. All query parameters go inside params. Flat parameters alongside action will produce zero results or Tool execution failed errors.

6. Ask questions¶

Now your Hermes Agent can answer business questions from live data:

"What's our revenue this month vs last month across Stripe and QuickBooks?"

"Show me HubSpot pipeline by stage. Which deals are stuck?"

"What's our blended ROAS across Google Ads and Meta Ads this week?"

Tools available¶

CorpusIQ exposes 40+ connectors as MCP tools. Hermes auto-discovers them. No code. No SDK. Just connect and ask.

Operation-level safety¶

External-source retrieval tools are marked read-only. Write-capable connector-management and CorpusIQ control-plane tools are separately named and annotated; provider scopes vary by connector. Direct MCP does not retain raw customer files or full connector response payloads; scoped operational logs may persist for up to 30 days.

Token refresh for crons¶

The refresh token (30-day expiry) is now available in production. Save both access_token and refresh_token from the device OAuth response. When the access token expires, POST grant_type=refresh_token to /oauth/token for a new one. Never overwrite the refresh token when updating the access token.

For cron jobs, wrap the task so the token is refreshed before the run, then call the one-shot mode:

# 1. refresh (returns a new access_token; keep the refresh_token unchanged)
curl -s -X POST https://mcp2.corpusiq.io/oauth/token \
  -d "grant_type=refresh_token&refresh_token=<saved_refresh_token>"

# 2. write the returned access_token into headers.Authorization in config.yaml

# 3. run the task
hermes -z "your task"

Your wrapper script owns steps 1 and 2; the agent only ever sees a valid JWT.

Complete docs: github.com/CorpusIQ/corpusiq-docs