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.

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 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/"
    }
  }
}

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.

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 org API key.

Replace <your-api-key> with a key from Settings -> API (Authentication).

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 org API key (create one)
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

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”