MCP FAQ

Common questions about connecting AI agents and IDEs to graph8 through the Model Context Protocol. If your question is not here, check the MCP Server overview or file a bug in the GitHub repo for the relevant integration.

Plans and credits

Is there a free tier for MCP?

Yes. The Developer PAYG tier ships with 1,000 free credits on signup and no card required. MCP tool calls bill against that balance the same way SDK or REST calls do. Browsing tools like g8_find_contacts are free to preview - credits only deduct when you save, enrich, or send. See Pricing for full details.

What is the price per tool call?

Each credit is $0.05 on PAYG. Most read tools are free. Credit-charging tools are flagged in the MCP Tool Reference - look for the “credits” column. Enrichment, AI reply drafts, and audience syncs are the main paid surfaces.

How do I monitor my credit spend from MCP?

Open Profile -> Developer in the graph8 app. The Usage panel shows credits consumed in the last 24 hours, 7 days, and billing month, broken down by source (MCP, SDK, REST, UI). Each tool call shows up with a timestamp and credit cost.

Authentication

Where do I get a personal API key vs an org API key?

Personal API key: Profile -> Developer. Scoped to your user inside the active org. Use this for local stdio MCP setups on your own machine.
Org API key: Settings -> API. Admin only. Scoped to the whole org for shared automation, service accounts, or production integrations.

Most users want the personal key. See Authentication.

What is the difference between remote OAuth and local stdio?

	Remote OAuth	Local stdio
Where the server runs	graph8 cloud	your machine
How auth works	OAuth in browser, one-time	`G8_API_KEY` env var
Install required	No	`uvx g8-mcp-server`
Best for	Claude.ai, Claude Desktop, VS Code, hosted agents	Cursor, Windsurf, local dev, CI
Tools loaded	All tools (mode filtering coming soon)	Filterable via `G8_MCP_MODE`

Remote OAuth is the default recommendation. See the MCP setup matrix for which clients support which transport.

Where does my API key actually live?

For local stdio, the key lives in:

The env block of your MCP client config (~/.cursor/mcp.json, ~/.claude/mcp.json, etc.), or
~/.g8/credentials.json if you ran g8 login --api-key.

For remote OAuth there is no API key. graph8 issues an opaque session token tied to your PropelAuth identity. The token is held by your MCP client (Claude.ai, Claude Desktop, etc.) and rotated automatically.

How do I revoke a session or key?

OAuth sessions: Profile -> Connections in the graph8 app. Click revoke next to the client name.
Personal API keys: Profile -> Developer. Delete the key.
Org API keys: Settings -> API. Admin only.

Revocation is immediate. The client will get a 401 on the next tool call.

Modes

When do I use `dev` vs `gtm` vs `all` mode?

Mode	Audience	Tools	Set on
`dev`	Developers using Cursor, Windsurf, Claude Code	17 - repo scan, tracking install, forms, KB	stdio only
`gtm`	Campaign managers in Claude Desktop	23 - campaigns, sequences, inbox, audience syncs	stdio only
`all`	Default fallback	35 - everything	stdio only

Mode is set via G8_MCP_MODE on stdio. Remote OAuth currently loads all tools. URL-based mode filtering for remote is on the roadmap (see MCP Server overview).

Why are some tools missing from my client?

Three likely causes:

You are on stdio with G8_MCP_MODE=dev or gtm and the tool belongs to the other mode. Set G8_MCP_MODE=all or switch modes.
Your role does not grant access. Check Settings -> Members with an admin.
Your g8-mcp-server version is out of date. Run uvx g8-mcp-server@latest or pip install -U g8-mcp-server.

Common errors

`spawn uvx ENOENT`

The uvx binary is not on your PATH. Install uv (recommended) or replace uvx with the absolute path in your config:

{
  "command": "/Users/you/.local/bin/uvx",
  "args": ["g8-mcp-server"]
}

`Authentication failed` or 401

The API key in your config is expired, revoked, or scoped to a different org. Regenerate the key from Profile -> Developer and update the env block in your MCP config. Restart the MCP client after changing config.

For OAuth: revoke the session in Profile -> Connections and reconnect from your client.

`Permission denied`

The MCP can only do what your graph8 role can do. If a tool returns “permission denied”, you do not have the underlying capability in the app either. Ask an admin to update your role in Settings -> Members.

`Tool not found`

Three likely causes:

Typo in the tool name. Tool names are case-sensitive and prefixed with g8_.
Tool belongs to a mode not loaded (see “Why are some tools missing”).
Your g8-mcp-server version is older than the tool. Update with uvx g8-mcp-server@latest.

OAuth redirect loop

Caused by stale browser cookies or a half-completed sign-in. Clear cookies for be.graph8.com and app.graph8.com, then reconnect.

If you use a custom domain or self-hosted instance, make sure the redirect_uri registered in your client matches the canonical graph8 URL.

`JSON parse error` on Claude Desktop startup

The claude_desktop_config.json has invalid syntax. Common culprits: trailing comma, missing quote, smart quotes from a word processor. Paste it into a JSON validator like jsonlint.com and fix.

Multi-org and multi-instance

How do I switch graph8 orgs in my MCP client?

Each MCP session is tied to one org. To switch:

Revoke the current session in Profile -> Connections (OAuth) or replace your API key (stdio).
Switch orgs in the graph8 app web UI.
Reconnect from your MCP client, or generate a new personal key under the new org.

You can keep one config per org by adding multiple servers to mcpServers, e.g. graph8-acme and graph8-staging.

Can I run multiple MCP instances in parallel?

Yes. Each MCP client process is independent. You can have Cursor, Claude Desktop, and a CLI session all pointing at graph8 simultaneously. Credit billing is per call, not per session.

For agent frameworks (LangChain, CrewAI, etc.) that spawn parallel tool calls, the server handles concurrent requests per session. Rate limits apply per org, not per session - see Rate Limits.

Security

What does the OAuth session see?

The session sees exactly what your user account sees in the graph8 web app. Same role permissions, same org boundaries. The session does not see other orgs you are not a member of.

Is my data sent to Anthropic / OpenAI / etc.?

graph8 returns tool results to your MCP client. Your client (Claude, GPT, Cursor) then includes those results in the LLM prompt. graph8 does not push data to model providers directly. If you have a data residency requirement, set up a self-hosted MCP using stdio so the connection stays inside your machine.

Can I scope an API key to specific tools?

Not today. API keys carry the full permission set of the user or org they belong to. Tool-level scoping is on the roadmap.

Timeouts and rate limits

What is the rate limit?

5 requests per second per org for all surfaces (REST, SDK, MCP). Burst above that returns HTTP 429. See Rate Limits.

Why does my tool call time out?

Long-running tools (g8_build_contact_list, g8_enrich_contacts, g8_scan_repo) can take 30-90 seconds. Most MCP clients enforce a 60s timeout on tool responses by default. Workarounds:

Use the smaller-batch variant (e.g. g8_find_contacts first to preview, then g8_build_contact_list with a smaller limit).
For Claude Desktop, raise the timeout in app settings.
For programmatic agents, increase the per-tool timeout in your framework config.

Preview tools

Are there preview / dry-run tools?

Yes. Use these before tools that cost credits or send real messages:

g8_find_contacts previews search results before g8_build_contact_list saves them.
g8_get_sequence_preview previews sequence steps and channels before launch.
g8_lookup_person / g8_lookup_company cost 1 credit but do not save - run them first if you want to check data quality before bulk enrichment.

The graph8 MCP server enforces a “confirm before commit” rule for any tool that costs credits or sends outreach. Your client should prompt you each time.

Filing bugs and requesting features

Bugs: open an issue against the relevant repo. For server bugs use the graph8 MCP server repo. For client bugs use the client repo.
New tools: open a discussion or contact your account manager. We prioritise tools by aggregate usage.
Docs: this site is open to PRs. Edit any .mdx file under frontend/docs/src/content/docs/developers/.