MCP Server

The graph8 MCP server connects AI coding agents (Claude Code, Cursor, Windsurf, Claude Desktop) to your graph8 workspace. It exposes tools for contact search, campaign management, tracking snippet installation, and progressive form generation — all from within your IDE.

Personal vs Admin Setup

Most users should use personal MCP setup from Profile. You do not need org admin access.

Use Case	Where to set it up	Credential
Personal MCP in Claude Desktop, Cursor, Windsurf, Claude Code	Profile -> Developer	Personal API key (for local) or OAuth (for remote)
Shared org automation and admin-managed integrations	Settings -> API	Org API key

Tip

If you are a non-admin user and want MCP for yourself, use the personal flow in Profile. Do not use the admin-only org API settings.

Setup

There are two ways to connect: Remote (recommended) and Local. Remote uses OAuth — no API key or installation required. Local runs the server on your machine via stdio.

Remote (OAuth) — Recommended

Paste this config into your AI client. Your client will prompt you to sign in via OAuth when you first connect — no API key needed.

Claude.ai

1. Go to Customize > Connectors > Add custom connector
2. Paste the server URL: https://be.graph8.com/mcp/
3. Click Add, then Connect
4. Authorize when prompted (one time)

Claude Desktop

1. Go to Settings > MCP Servers > Add
2. Paste the server URL: https://be.graph8.com/mcp/
3. Authorize when prompted (one time)

Claude Code

Add to ~/.claude/mcp.json:

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

Cursor

Add to .cursor/mcp.json in your project root:

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

Windsurf

Add to your Windsurf MCP config:

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

ChatGPT

1. Go to Settings > Apps > Developer Mode
2. Add MCP server and paste: https://be.graph8.com/mcp/
3. Authorize via OAuth

Tip

Remote mode handles authentication automatically via OAuth. When you first use a graph8 tool, your client will open a browser window to sign in. No API key, no environment variables, no Python install needed.

In graph8, active remote OAuth sessions appear in Profile -> Connections. Local Claude Desktop and stdio setups remain in Profile -> Developer because they use your personal API key instead of an OAuth session.

Setup Guides

Cursor IDE Setup

Connect Cursor to graph8 with either remote OAuth or local stdio MCP. Open guide

Claude Desktop Setup

Configure Claude Desktop to use graph8 MCP tools and local API-key auth. Open guide

n8n Setup

Use graph8 from n8n via MCP-backed automation flows. Open guide

What You Can Ask

Review concrete prompt patterns and supported MCP workflows. Open guide

Claude Desktop (Local MCP)

Use Claude Desktop when you want graph8 tools directly inside the desktop app with local MCP and your personal API key.

1. Go to Profile -> Developer
2. Copy the local MCP config for the mode you want (gtm, dev, or all)
3. Paste it into Claude Desktop MCP config
4. Restart Claude Desktop

For a step-by-step walkthrough, use the Claude Desktop setup guide.

Claude.ai (Actions)

Claude.ai uses browser-based actions rather than local MCP.

1. Generate a personal API key in Profile -> Developer
2. Use graph8 OpenAPI actions with Bearer auth
3. Call graph8 APIs from Claude.ai using your personal credentials

Use this when you want browser-based account lookup, company intelligence, and workflow actions without running a local MCP server.

ChatGPT (Actions)

ChatGPT also uses browser-based actions rather than local MCP.

1. Generate a personal API key in Profile -> Developer
2. Import graph8 OpenAPI into your GPT or action layer
3. Authenticate with Bearer auth using your personal API key

This is the best path for ChatGPT-based account research, contact lookups, and sequence drafting from browser workflows.

Local (stdio)

If you prefer running the server locally (or your client doesn’t support remote MCP), use the stdio transport. This requires Python 3.10+ and an API key.

Replace <your-api-key> with:

• your personal API key from Profile -> Developer (recommended for end users), or
• an org API key from Settings -> API (admin/shared integrations).

Developer Mode

For developers in Cursor, Windsurf, or Claude Code:

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

GTM Mode

For campaign managers in Claude Desktop:

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

uvx runs the server directly from PyPI without installing it. If you’d rather install permanently, use pip install g8-mcp-server — but that’s primarily for the CLI.

Environment Variables (local only)

Variable	Required	Default	Description
G8_API_KEY	Yes	—	Your personal API key (Profile) or org API key (Settings -> API) (details)
G8_MCP_MODE	No	all	Tool set to load: dev, gtm, or all
G8_API_URL	No	https://be.graph8.com	API base URL (for self-hosted or staging)

Modes

The G8_MCP_MODE variable controls which tools are loaded. This applies to local (stdio) connections only — remote connections load all tools.

Developer Mode (dev)

For developers building products in Cursor, Windsurf, or Claude Code. Provides repo-scoped tools for scanning codebases, installing tracking, generating forms, and managing campaigns.

Set: G8_MCP_MODE=dev

GTM Mode (gtm)

For campaign managers and marketing ops in Claude Desktop. Provides org-scoped tools for creating campaigns, browsing knowledge base content, and launching outreach — no repo context needed.

Set: G8_MCP_MODE=gtm

All Mode (default)

Loads all legacy tools for backward compatibility. If you don’t set G8_MCP_MODE, this is the default.

Set: G8_MCP_MODE=all (or omit the variable)

Available Tools

Platform Tools (all modes)

Available in every mode — core contact and company operations.

Tool	Description
g8_search_contacts	Search contacts by email or list membership
g8_search_companies	Search companies by name, domain, or industry
g8_lookup_person	Enrich a person by email — returns full profile
g8_lookup_company	Enrich a company by domain — returns firmographics
g8_add_to_sequence	Add a contact to an outreach sequence

Sequence Management (all modes)

Full lifecycle control over outreach sequences.

Tool	Description
g8_create_sequence	Create a new sequence with steps, channels, and schedule
g8_get_sequence_preview	Preview sequence steps and channels before launching
g8_update_sequence	Update sequence name, description, or flags
g8_update_sequence_step	Update a single step (template, timing, channel)
g8_pause_sequence	Pause a live sequence (no new sends until resumed)
g8_resume_sequence	Resume a paused sequence
g8_get_sequence_analytics	Get performance metrics (reply rate, completion, engagement)
g8_delete_sequence	Archive a sequence (soft delete)

Caution

Pausing, resuming, and deleting sequences affect live outreach. These tools require confirmation before execution.

Inbox & Replies (all modes)

Manage reply threads across email, SMS, and LinkedIn from a unified surface.

Tool	Description
g8_list_inbox	List reply threads, filterable by channel, sequence, status, assignee, or tag
g8_get_reply	Get a single reply thread with full message history
g8_assign_reply	Assign a reply thread to a team member
g8_tag_reply	Tag a reply thread for categorization
g8_get_reply_draft	Generate an AI reply draft based on conversation context (charges credits)
g8_send_reply	Send a reply via email, SMS, or LinkedIn

Caution

g8_send_reply sends a real message to the contact. g8_get_reply_draft charges credits for AI generation.

Audience & CRM Sync (all modes)

Push audiences to ad platforms and sync contacts to CRMs.

Tool	Description
g8_list_audience_syncs	List configured audience syncs
g8_create_audience_sync	Create a sync to Meta, LinkedIn Ads, Google Ads, or X
g8_get_audience_sync	Get sync config details
g8_update_audience_sync	Update sync cadence, mode, or suppression lists
g8_delete_audience_sync	Remove a sync config (soft delete)
g8_trigger_audience_sync	Manually trigger a sync run
g8_get_audience_sync_runs	View sync run history with record counts
g8_get_audience_sync_errors	View error logs for failed sync runs
g8_list_crm_syncs	List connected CRM integrations (HubSpot, Salesforce, Pipedrive, Zoho, SugarCRM)
g8_push_to_crm_contact	Push contacts to a CRM provider
g8_push_to_crm_company	Push companies to a CRM provider
g8_push_to_crm_list	Push list memberships to a CRM provider
g8_get_crm_fields	Discover available field mappings for a CRM provider
g8_get_crm_status	Check CRM connection health and rate limits

Developer Tools (dev mode)

Repo-scoped tools for building graph8 into your codebase.

Tool	Description
g8_connect_repo	Connect a GitHub/GitLab repo to graph8
g8_scan_repo	Trigger a codebase scan for GTM integration points
g8_get_scan_results	Get scan results (frameworks, pages, components)
g8_status	Check repo integration status
g8_doctor	Diagnose integration health issues
g8_install_spine	Generate tracking installation plan
g8_apply_install	Apply the tracking installation
g8_list_campaigns	List campaigns for a repo
g8_get_campaign	Get campaign details
g8_search_kb	Search knowledge base articles
g8_list_kb_documents	List all KB documents

Tracking & Forms (dev mode)

Install graph8’s JavaScript tracking and generate progressive forms.

Tool	Description
g8_get_tracking_snippet	Get framework-specific tracking snippet (p.js). Supports: HTML, React, Next.js, Vue, WordPress, Webflow, Shopify
g8_get_form_template	Get progressive form template (embedded or popup). Supports the same frameworks as the tracking snippet

Caution

The tracking snippet must be installed before progressive forms will work. Always call g8_get_tracking_snippet first.

Tracking Snippet — Server-Side vs Client-Side

The graph8 tracking snippet (p.js) works differently depending on whether your framework renders on the server or the client. Understanding this is critical for correct installation.

Server-Side Rendered (SSR)

Frameworks: Next.js, WordPress, Shopify, Webflow, HTML

The snippet is included in the server-rendered HTML layout (e.g., app/layout.tsx, theme.liquid, functions.php). It loads on every page from the first paint — no hydration delay.

// SSR — snippet is always available, call directly
g8.identify("user-123", { email: "user@example.com" });
g8.track("page_view", { page: "/pricing" });

Client-Side Rendered (CSR)

Frameworks: React, Vue

The snippet is injected via useEffect (React) or onMounted (Vue) after hydration. The script may not be ready immediately — use optional chaining to safely call tracking methods.

// CSR — use optional chaining since g8 loads after hydration
window.g8?.identify("user-123", { email: "user@example.com" });
window.g8?.track("button_click", { button: "signup" });

Privacy Options

Add these data-attributes to the script tag to control privacy behavior:

Attribute	Values	Description
data-privacy-dont-send	"true"	Disables cookies and event sending
data-privacy-user-ids	"true"	Disables storing user identifiers
data-privacy-ip-policy	"keep", "stripLastOctet", "remove"	Controls IP address handling
data-init-only	"true"	Initializes the script without sending a page event

Verification

After installing the snippet, verify it’s working:

1. Open browser DevTools -> Network tab
2. Look for requests to your tracking host (/p.js)
3. In Console: window.g8 should be defined
4. Call g8.track('test_event') — you should see a network request

Campaign Management (gtm mode)

Org-scoped tools for campaign managers — no repo context required.

Tool	Description
g8_list_campaigns	List all campaigns in the org
g8_get_campaign	Get campaign details and status
g8_get_campaign_document	Get a campaign document (emails, landing pages)
g8_create_campaign	Create a new campaign with audience, channels, and content
g8_update_campaign	Update campaign settings
g8_launch_campaign	Launch a campaign (or dry run)
g8_search_kb	Search knowledge base
g8_list_kb_documents	List KB documents

Resources

MCP resources provide read-only context that agents can include in prompts.

Resource URI	Description
g8://repos	List of connected repositories
g8://repos/{repo_id}/scan	Scan results for a repo
g8://repos/{repo_id}/kb	Knowledge base documents for a repo
g8://repos/{repo_id}/kb/{doc_id}	Single KB document content
g8://repos/{repo_id}/campaigns	Campaigns for a repo
g8://repos/{repo_id}/campaigns/{campaign_id}/brief	Campaign brief
g8://contacts	Contact list summary
g8://companies	Company list summary

Prompt Templates

Pre-built prompts for common GTM workflows.

Prompt	Arguments	Description
gtm_setup	repo_url	Full setup workflow: connect, scan, install, launch
campaign_review	campaign_id	Review and optimize a campaign
icp_refinement	feedback	Refine ideal customer profile based on feedback

Getting Started

A typical developer workflow with the MCP server:

1. Configure — Add the remote config to your AI client (no install needed)
2. Connect — Ask your agent to connect your repo: “Connect my repo github.com/org/app”
3. Scan — The agent scans your codebase for frameworks and integration points
4. Install snippet — “Install the graph8 tracking snippet for Next.js”
5. Configure tracking — Add g8.identify() on login and g8.track() on key actions
6. Add forms — “Generate an embedded progressive form for React”
7. Launch campaigns — “Create a campaign targeting trial users”