IntentGPT MCP Server

Last updated: 2026-05-20

Remote MCP server that gives agents access to IntentGPT's B2B buying-intent graph: surge scores by domain, ICP search, topic taxonomy lookups, and workspace credit usage.

At a glance

Endpoint: https://mcp.intentgpt.ai/v1
Transport: JSON-RPC 2.0 over HTTPS (single request / single response)
Authentication: OAuth 2.1 with PKCE (recommended for Claude + other MCP clients) or legacy igk_live_… bearer API keys
Health probe: GET /health
Refresh cadence: 24h on Pro, weekly on Free. Surge data is delivered via daily webhooks — there is no real-time stream.

Connecting from Claude (OAuth)

In Claude, add a new MCP connector with URL https://mcp.intentgpt.ai/v1.
Claude auto-discovers /.well-known/oauth-authorization-server, registers itself via Dynamic Client Registration (RFC 7591), and starts the OAuth flow.
You're redirected to webapp.intentgpt.ai/oauth/consent. Sign in with a magic link if you aren't already, then approve the connection.
Claude is now connected. Access tokens last 1h and are silently rotated via refresh tokens (30d).

Revoke any connected app at any time from Settings → Connected apps. Revoke immediately terminates every access token, refresh token, and any in-flight authorization code for that client in your workspace.

Connecting from ChatGPT

ChatGPT custom connectors authenticate via OAuth 2.0. No API key or bearer token — ChatGPT registers itself with IntentGPT automatically and walks you through a magic-link sign-in.

In a Plus, Pro, Business, or Enterprise workspace, open Settings → Connectors → Create.
Set the MCP Server URL to https://mcp.intentgpt.ai/v1 and choose OAuth as the authentication method. Leave client ID and secret blank — IntentGPT supports Dynamic Client Registration, so ChatGPT mints its own credentials.
Click Create. ChatGPT opens an IntentGPT sign-in window — finish the magic-link flow, approve the connector, and you'll be redirected back. Mention IntentGPT in any chat and ChatGPT will route the relevant tool calls through this MCP.

Connecting from Gemini

Open the Gemini app or CLI settings. The CLI reads ~/.gemini/settings.json.
Add an mcpServers entry pointing at https://mcp.intentgpt.ai/v1 with an Authorization: Bearer igk_live_… header.
Restart Gemini. IntentGPT appears as a connected tool source — ask Gemini for surging accounts in your ICP and it will call search_accounts_by_intent.

Connecting from Perplexity

In a Pro or Enterprise workspace, open Settings → Connectors → Add connector.
Enter https://mcp.intentgpt.ai/v1 as the server URL, choose Bearer auth, and paste an igk_live_… API key.
Click Connect. Ask an account-research question and Perplexity will pull surge + intent topics from IntentGPT.

Connecting as an API client (legacy)

Sign up at intentgpt.ai (magic-link login).
Open Settings → API keys, click Create key. The full key is shown once — copy it. Format is igk_live_<40-hex>.
Pass Authorization: Bearer igk_live_… on every request to /v1.

Tools

All five tools are read-only — Claude can auto-permit them without per-call confirmation.

Name	Cost	Returns
`get_account_intent`	1 credit	Surge score + top topics + company metadata for one domain.
`search_accounts_by_intent`	5 credits	Ranked list of accounts matching an ICP that crossed a surge threshold.
`rank_accounts`	1 credit / domain	Caller-supplied domains ranked by surge score (up to 50 per call).
`topics`	free	Topic taxonomy: list / recommend for an industry / map keywords to topic_ids.
`get_usage`	free	Current workspace credit budget snapshot.

Empty-result contract

When a domain isn't in the index, tools return a structured no-match shape — never a fabricated record:

{ "matched": false, "domain": "example.com", "reason": "not_in_index", "suggestion": "..." }

Tool annotations

Every tool declares MCP annotations via tools/list: title (human-readable display name) and readOnlyHint: true. No tool currently declares destructiveHint.

Rate limits & quotas

Rate limit: Free 60 rpm, Pro 600 rpm (sliding window, Redis-backed). Exceeded calls return JSON-RPC error -32002 with a Retry-After hint.
Credits: Free 1,000 / billing period, Pro 50,000. Exceeded calls return -32001.
OAuth registration: 10 / hour per source IP.

Errors

JSON-RPC error envelopes follow the spec. Common codes:

-32700	Parse error (malformed JSON)
-32600	Invalid request envelope
-32602	Invalid params (Zod validation failed)
-32603	Internal error
-32001	Quota exceeded — wait for period reset or upgrade
-32002	Rate limited
HTTP 401	Bearer token missing / invalid / revoked / expired

Error messages are one sentence cause + one sentence next step — no stack traces.

Security

API keys hashed with Argon2id; full key shown to the user exactly once.
Workspace isolation enforced two ways: Postgres row-level security keyed on a per- request GUC, AND application-level assertWorkspaceScope checks in every tool that fetches rows by non-workspace criteria (BigQuery reads don't go through RLS).
Origin header validated on every authenticated request.
TLS only — plain HTTP requests are redirected.
Report security issues to security@intentgpt.ai. We respond within one business day.

Privacy

Full policy at webapp.intentgpt.ai/legal/privacy. Summary specific to the MCP server:

Collected per call: workspace ID, API-key prefix, tool name, validated input parameters, timestamp, credit cost, request ID.
Used for: authentication, per-workspace rate limits and credit budgets, usage history, anomaly detection.
Not collected: Claude conversation history, chat transcripts, user memory, user files, full tool input or output bodies (the read-through cache is ≤ 5 minutes and is not persisted).
Retention: request metadata 90 days, aggregated counts for the life of the workspace. Account + key deletion purges within 30 days.
Sub-processors: Google Cloud (BigQuery + Cloud Run + Cloud SQL), Upstash Redis, Stripe (billing only — no MCP payload data is shared). No advertising or analytics third parties.

Support

Status: webapp.intentgpt.ai/status
Email: support@intentgpt.ai