API, MCP & CLI

Generate API keys to integrate graph8 with your tools and workflows. Connect AI assistants via MCP, or use the CLI for command-line access.

Creating Keys

Generate a New Key

1. Go to Settings → API
2. Click Create API Key
3. Name the key (e.g., “CRM Sync”, “Internal Dashboard”)
4. Select the permission scopes
5. Click Generate
6. Copy the key immediately — it won’t be shown again

Permission Scopes

Each key can be limited to specific API areas:

• Contacts — read/write contact records
• Companies — read/write company records
• Lists — read/write lists and audiences
• Pipeline — read/write deals and stages
• Sequences — read/write sequences and enrollment
• Analytics — read analytics data
• Full Access — unrestricted access to all endpoints

Grant only the scopes your integration needs.

Key Management

Viewing Keys

The API settings page shows all active keys with:

• Name — the label you assigned
• Scopes — which API areas the key can access
• Created — when the key was generated
• Last Used — the most recent API call using this key

Rotating a Key

To replace a key without downtime:

1. Create a new key with the same scopes
2. Update your integration to use the new key
3. Verify the integration works
4. Revoke the old key

Revoking a Key

1. Find the key in the list
2. Click Revoke
3. Confirm

Revoked keys stop working immediately. Any integration using the key will receive authentication errors.

Rate Limits

API requests are rate-limited per key and plan:

Plan	Requests/Minute	Requests/Day
Starter	60	10,000
Pro	120	50,000
Enterprise	300	Unlimited

When you exceed the limit, the API returns a 429 Too Many Requests response with a Retry-After header.

Authentication

Include your API key in the request header:

Authorization: Bearer your-api-key-here

All API requests must be made over HTTPS.

Example Request

curl -H "Authorization: Bearer your-api-key-here" \
     -H "Content-Type: application/json" \
     https://be.graph8.com/v1/contacts

Webhooks

Receive real-time notifications when events happen in graph8.

Setting Up Webhooks

1. Go to Settings → API → Webhooks
2. Click Add Webhook
3. Enter your endpoint URL (must be HTTPS)
4. Select the event types to subscribe to
5. Save

Event Types

• contact.created — a new contact is added
• contact.updated — a contact record is modified
• deal.stage_changed — a deal moves to a new stage
• deal.won / deal.lost — a deal is closed
• sequence.completed — a contact finishes a sequence
• meeting.booked — an appointment is scheduled

Retry Policy

If your endpoint returns a non-2xx response, graph8 retries:

• 3 retry attempts
• Exponential backoff (1 min, 5 min, 30 min)
• After 3 failures, the webhook is paused and you’re notified

Webhook Security

Each webhook includes a signature header for verification. Use the signing secret (shown during webhook creation) to verify that requests come from graph8.

MCP Server

The graph8 MCP (Model Context Protocol) server lets AI assistants like Claude Desktop, Cursor, Windsurf, and Claude Code interact with your graph8 data directly.

Modes

graph8 MCP runs in two modes depending on your workflow:

• Developer Mode — for developers building products. Includes repo scanning, GTM infrastructure install, campaign generation, and knowledge base search. All tools require a repo_id.
• GTM Mode — for campaign managers and marketers. Browse campaigns, edit copy, search the knowledge base, enrich contacts, and launch outreach — no repo_id needed.

Remote (Streamable HTTP)

Clients that support remote MCP endpoints (Cursor, Claude Code, Windsurf) can connect directly. Authentication is handled via OAuth — no API key required in the config.

{
  "mcpServers": {
    "graph8": {
      "url": "https://be.graph8.com/mcp/"
    }
  }
}

Your client will prompt you to sign in via OAuth when you first connect.

Local (stdio)

For clients that require a local process (Claude Desktop), install the MCP server and provide your API key:

pip install g8-mcp-server

Developer Mode:

{
  "mcpServers": {
    "graph8": {
      "command": "uvx",
      "args": ["g8-mcp-server"],
      "env": {
        "G8_API_KEY": "your-api-key-here",
        "G8_MCP_MODE": "dev"
      }
    }
  }
}

GTM Mode:

{
  "mcpServers": {
    "graph8": {
      "command": "uvx",
      "args": ["g8-mcp-server"],
      "env": {
        "G8_API_KEY": "your-api-key-here",
        "G8_MCP_MODE": "gtm"
      }
    }
  }
}

Available Tools

Shared (all modes)

Tool	Description
g8_search_contacts	Search contacts by email, name, or list
g8_get_contact	Get full contact profile
g8_search_companies	Search companies by domain or industry
g8_get_company	Get full company profile
g8_lookup_person	Instant person lookup by email or LinkedIn
g8_lookup_company	Instant company lookup by domain
g8_enrich_contacts	Start enrichment for a batch of contacts
g8_verify_email	Verify email deliverability

Developer Mode

Tool	Description
g8_connect_repo	Connect a GitHub/GitLab repository
g8_scan_repo	Scan repo for tech stack and GTM readiness
g8_get_scan_results	Get scan results for a repo
g8_status	Get current repo status
g8_doctor	Run health checks on GTM installation
g8_install_spine	Generate GTM install patches
g8_apply_install	Apply generated patches to the codebase
g8_list_campaigns	List campaigns for a repo
g8_get_campaign	Get campaign details
g8_search_kb	Search the repo knowledge base
g8_list_kb_documents	List all KB documents

GTM Mode

Tool	Description
g8_list_campaigns	List campaigns for the organization
g8_get_campaign	Get full campaign details and documents
g8_get_campaign_document	Get document content (briefs, copy, etc.)
g8_create_campaign	Create a new campaign
g8_update_campaign	Update campaign fields
g8_launch_campaign	Launch a campaign for outreach
g8_search_kb	Search the knowledge base
g8_list_kb_documents	List all KB documents

CLI

The graph8 CLI provides the same MCP tools as a command-line interface. Install it alongside the MCP server:

pip install g8-mcp-server

Run a tool directly:

g8 status --repo-id <repo-id>
g8 scan --repo-id <repo-id>
g8 doctor --repo-id <repo-id>

Set your API key as an environment variable:

export G8_API_KEY=your-api-key-here

Frequently Asked Questions

Can I have multiple API keys?

Yes. Create separate keys for each integration or environment (production, staging, testing).

What happens if I lose my API key?

API keys can’t be recovered after creation. Revoke the lost key and generate a new one.

Are there SDKs available?

Check the graph8 API documentation for available client libraries and SDK references.

Can I test webhooks locally?

Use a tunneling service to expose your local endpoint during development. Point the webhook URL to your tunnel address.

Do I need an API key for remote MCP connections?

No. Remote MCP connections (Cursor, Claude Code, Windsurf) use OAuth for authentication. You only need an API key for local stdio mode (Claude Desktop) or direct API calls.

Which MCP mode should I use?

Use Developer Mode if you’re building a product and want to scan repos, install GTM infrastructure, and generate campaigns from code. Use GTM Mode if you’re managing campaigns, writing copy, or doing outreach — it doesn’t require a repository.

---

Tip: Create separate API keys per integration so you can revoke one without affecting others.