Skip to content

MCP Server

The graph8 MCP server connects AI coding agents (Claude Code, Cursor, Windsurf, Claude Desktop, ChatGPT) to your graph8 workspace. It exposes tools for contact and company search, sequences, inbox, campaigns, voice/dialer, workflow building, skill authoring, intent signals, quote-to-cash, pipelines, and developer install, all from within your IDE or chat client.

Claude CodeClaude CodeCursorCursorWindsurfWindsurfClaude DesktopClaude DesktopChatGPTChatGPT

Personal vs Admin Setup

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

Use CaseWhere to set it upCredential
Personal MCP in Claude Desktop, Cursor, Windsurf, Claude CodeProfile -> DeveloperPersonal API key (for local) or OAuth (for remote)
Shared org automation and admin-managed integrationsSettings -> APIOrg API key

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.

  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)

Setup Guides

Pick your client. Every guide covers both remote OAuth and local stdio variants.

Cursor

Cursor IDE with remote OAuth or local stdio. Open guide

Claude Desktop

Anthropic’s desktop app with personal or org API key. Open guide

Claude Code

Anthropic’s terminal agent via ~/.claude/mcp.json. Open guide

VS Code

Native MCP via .vscode/mcp.json for Copilot Agent Mode. Open guide

n8n

Workflow automation via the MCP node or HTTP request. Open guide

LangChain

langchain-mcp-adapters + LangGraph for Python agents. Open guide

LlamaIndex

llama-index-tools-mcp for typed Python agents. Open guide

CrewAI

MCPServerAdapter for multi-agent crews. Open guide

Pydantic AI

Typed agent outputs with MCPServerHTTP and MCPServerStdio. Open guide

OpenAI Agents SDK

Native MCP via MCPServerStreamableHttp. Open guide

End-to-end examples

Worked workflows chaining MCP tools. Open guide

What You Can Ask

Free-form prompt patterns and supported workflows. Open guide

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).

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

uvx runs the server directly from PyPI without installing it. If you’d rather install permanently, use pip install g8-mcp-server — that ships both the MCP server and the g8 CLI.

Environment Variables (local only)

VariableRequiredDefaultDescription
G8_API_KEYYes—Your personal API key (Profile) or org API key (Settings -> API) (details)
G8_MCP_MODENoallTool set to load: dev, gtm, or all
G8_API_URLNohttps://be.graph8.comAPI 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.

ModeToolsBest for
dev32Developers building graph8 into product code in Cursor / Windsurf / Claude Code (repo scan, install snippets, generate forms, CRM operations)
gtm51Campaign managers and marketing ops in Claude Desktop (campaigns, mailbox warmup, pipelines, ICPs, personas, CRM operations)
all114Maximum capability: dev + GTM + voice/dialer + workflow builder + skill authoring (default for remote OAuth)

Counts include the g8_gtm_ / g8_voice_ / g8_workflow_ prefixed registrations used to avoid name collisions in all mode. Skill authoring tools are dual-registered under both g8_skill_* and g8_workflow_skill_* names, so the underlying handler count is ~100 distinct operations.

Progressive tool discovery

The remote MCP endpoint advertises only ~31 always-on tools at connect time, plus the g8_tool_search meta-tool. The other 80+ tools (voice, workflows, skills, pipelines, quotes, intent, custom fields, etc.) are loaded on demand — when an agent calls g8_tool_search(query="workflow"), matching tools become visible on the next tools/list fetch via the standard notifications/tools/list_changed event.

This keeps the steady-state context budget low while still giving agents access to the full 100+ tool surface when they need it.

Tool-set scoping on the remote URL (coming soon)

Today the remote OAuth endpoint https://be.graph8.com/mcp/ loads every tool your role grants, with g8_tool_search for discovery. Per-mode endpoints are on the roadmap so different clients can pull only the tools they need:

  • https://be.graph8.com/mcp/?mode=dev - load the 32 developer tools only
  • https://be.graph8.com/mcp/?mode=gtm - load the 51 GTM tools only
  • https://be.graph8.com/mcp/?groups=audience-sync,inbox - load specific tool groups

This is roadmap, not shipped. Use G8_MCP_MODE on stdio in the meantime.

Available Tools

For the complete per-tool reference (parameters, return shapes, JSON examples, danger warnings), see MCP Tool Reference. The tables below are a quick index by category.

Shared platform tools (all modes)

Available in every mode — core CRM, prospecting, sequences, inbox, intent, sync, meetings, quotes, and custom fields.

Contacts, lookup, search — 8 tools

ToolDescription
g8_search_contactsSearch contacts already in your CRM
g8_search_companiesSearch companies already in your CRM
g8_lookup_personEnrich a single person via the graph8 index (email / LinkedIn / name+domain)
g8_lookup_companyEnrich a single company via the graph8 index (domain / name)
g8_find_contactsSearch graph8’s 700M+ contact index for new prospects
g8_find_companiesSearch graph8’s 100M+ company index for new accounts
g8_create_contactCreate a contact in your CRM
g8_enrich_contactsRun third-party waterfall enrichment on saved contacts; optional providers[] + email_verification overrides (charges credits)

Contact graph (read) — 5 tools

ToolDescription
g8_get_contact_detailFull enriched details for a single contact
g8_get_contact_companyCompany record associated with a contact
g8_get_contact_dealsDeals linked to a contact
g8_get_contact_activityActivity history for a contact
g8_get_company_contactsAll contacts at a company

Lists — 3 tools

ToolDescription
g8_get_listsList contact and company lists
g8_create_listCreate a list (empty, from CRM contacts, explicit rows, or open-data search)
g8_add_to_listAdd contacts to an existing list

Custom fields — 4 tools

ToolDescription
g8_list_fieldsList field definitions (base + custom columns)
g8_create_fieldCreate a custom column on contacts or companies. STRONGLY RECOMMENDED to pass enrichment_providers (+ optional enrichment_email_verification) in the same call when the column will hold enriched data — otherwise the UI Enrich button and g8_enrich_contacts will fail with 422 waterfall_config_missing
g8_set_field_valueSet a custom column value on a single record
g8_delete_fieldSoft-delete a custom column

Deals — 7 tools

ToolDescription
g8_get_dealsList deals with stage / pipeline / text filters
g8_get_dealGet a single deal
g8_get_pipelineList deal pipelines and stages
g8_create_dealCreate a new deal
g8_update_dealUpdate a deal (partial; usually stage change)
g8_delete_dealDelete a deal
g8_get_company_dealsAll deals for a company

Tasks — 5 tools

ToolDescription
g8_get_tasksList tasks with status / priority / assignee / search filters
g8_get_taskRead a single task by ID
g8_create_taskCreate a task linked to a contact
g8_update_taskUpdate a task (partial)
g8_delete_taskDelete a task

Notes — 4 tools

ToolDescription
g8_list_notesList notes on a contact
g8_create_noteAdd a note to a contact
g8_update_noteUpdate a note
g8_delete_noteDelete a note

Enrichment jobs — 1 tool

ToolDescription
g8_get_enrichment_jobStatus + results of an async enrichment job

Sequences — 9 tools

Full lifecycle control over outreach sequences.

ToolDescription
g8_list_sequencesList outbound sequences
g8_add_to_sequenceEnroll contacts in a sequence (real sends)
g8_get_sequence_previewPreview steps and channels before launching
g8_get_sequence_analyticsPerformance metrics (reply rate, completion, engagement)
g8_create_sequenceCreate a new sequence with steps, channels, schedule
g8_update_sequenceUpdate sequence name, description, or flags
g8_update_sequence_stepUpdate a single step (template, timing, channel)
g8_pause_sequencePause a live sequence
g8_resume_sequenceResume a paused sequence
g8_delete_sequenceArchive a sequence (soft delete)

Inbox & replies — 6 tools

ToolDescription
g8_list_inboxList reply threads filterable by channel, sequence, status, assignee, or tag
g8_get_replyGet a single reply thread with full message history
g8_get_reply_draftGet the auto-generated draft reply (charges credits when generated)
g8_send_replySend a reply via email, SMS, or LinkedIn
g8_assign_replyAssign a reply thread to a team member
g8_tag_replyTag a reply thread for categorization

Activity stream — 3 tools

ToolDescription
g8_get_activitiesOrg-wide activity records (opens, clicks, form fills, etc.)
g8_get_activity_summaryAggregated activity summary
g8_get_contact_activityActivity history for one contact

Intent & signals — 14 tools

ToolDescription
g8_intent_list_keywordsList tracked keywords
g8_intent_search_pagesSearch website pages by URL or keyword
g8_intent_domain_searchSearch visitor activity on a specific domain
g8_intent_search_url_companiesFind companies whose users visited a URL
g8_intent_keyword_companiesCompanies showing interest in a keyword
g8_intent_keyword_contactsContacts showing interest in a keyword
g8_intent_keyword_urlsURLs associated with a keyword
g8_intent_pages_contactsContacts who visited a specific page
g8_intent_pages_visitor_countsVisitor count aggregates by page
g8_intent_page_visitorsVisitor records for a specific page
g8_intent_statsOrg-level intent stats
g8_intent_create_from_domainCreate a keyword group from a domain
g8_intent_update_keyword_filtersUpdate keyword tracking rules
g8_intent_delete_keywordStop tracking a keyword

Sync — 14 tools

Push audiences to ad platforms, sync contacts to CRMs, monitor sync health.

ToolDescription
g8_list_crm_syncsList connected CRM integrations (HubSpot, Salesforce, Pipedrive, Zoho, SugarCRM)
g8_get_crm_statusCRM connection health and rate limits
g8_get_crm_fieldsDiscover available field mappings
g8_push_to_crm_contactPush contacts to a CRM (may charge per integration)
g8_push_to_crm_companyPush companies to a CRM (may charge per integration)
g8_push_to_crm_listPush list memberships to a CRM
g8_list_audience_syncsList configured audience syncs
g8_get_audience_syncGet one sync’s config
g8_create_audience_syncCreate a sync to Meta / LinkedIn / Google / X / CRM
g8_update_audience_syncUpdate cadence, mode, or suppression lists
g8_delete_audience_syncRemove a sync config
g8_trigger_audience_syncManually trigger a sync run
g8_get_audience_sync_runsSync run history with record counts
g8_get_audience_sync_errorsError logs for failed sync runs

Meetings — 2 tools

ToolDescription
g8_list_meetingsList meetings with optional filters
g8_get_meetingFull meeting details (transcript, attendees, recording link)

Quotes (quote-to-cash) — 12 tools

ToolDescription
g8_list_quotesList quotes with optional filters
g8_get_quoteQuote details (line items, values, recipient, status)
g8_create_quoteCreate a new quote from line items
g8_update_quoteUpdate a draft quote
g8_duplicate_quoteDuplicate an existing quote
g8_edit_quote_as_draftConvert signed/sent quote back to editable draft
g8_send_quoteSend a quote via email (with signature + payment link)
g8_delete_quoteDelete a draft quote
g8_list_quotable_productsList products available for line items
g8_get_quote_settingsOrg-level quote settings
g8_get_company_quotesAll quotes for a company
g8_get_contact_quotesAll quotes for a contact

Discovery + playbooks — 3 tools

ToolDescription
g8_tool_searchSearch the full tool catalog and activate matching tools for this session
g8_list_playbooksList available graph8 playbooks (workflow guides)
g8_load_playbookLoad a playbook’s full markdown content

Developer tools (dev mode) — 11 tools

Repo-scoped tools for building graph8 into your codebase.

ToolDescription
g8_connect_repoConnect a GitHub/GitLab repo to graph8
g8_scan_repoTrigger a codebase scan for GTM integration points
g8_get_scan_resultsGet scan results (frameworks, pages, components)
g8_statusCheck repo integration status
g8_doctorDiagnose integration health issues
g8_install_spineGenerate tracking installation plan
g8_apply_installApply the tracking installation
g8_list_campaignsList campaigns for a repo
g8_get_campaignGet campaign details
g8_get_tracking_snippetGet framework-specific tracking snippet (p.js)
g8_search_kbSearch knowledge base articles

In dev mode g8_get_tracking_snippet and g8_get_form_template are also registered for use with the installation flow.

GTM tools (gtm mode) — 30 tools

Campaign builder, Studio, mailbox, and audience operations.

Campaigns — 17 tools

ToolDescription
g8_list_campaignsList campaigns in your org
g8_get_campaignCampaign details (summary or full)
g8_create_campaignCreate a new campaign
g8_update_campaignUpdate campaign metadata
g8_patch_campaign_fullUpdate full campaign state in one call
g8_launch_campaignLaunch a campaign (sends real outreach)
g8_get_campaign_ideasAI-generated campaign ideas from org context
g8_get_campaign_metricsOpen / click / reply / meeting metrics
g8_attach_audienceAttach an audience (list) to a campaign
g8_list_campaign_documentsList documents (copy, images, landing pages)
g8_get_campaign_documentGet document content
g8_create_campaign_documentCreate a new document
g8_update_campaign_documentUpdate document content
g8_delete_campaign_documentDelete a document
g8_get_ad_imagesList ad image creatives
g8_hide_ad_imageHide an ad creative from the grid
g8_get_campaign_sequenceGet sequence attached to a campaign

Campaign sequence steps — 4 tools

ToolDescription
g8_update_campaign_sequenceUpdate the sequence on a campaign
g8_create_campaign_stepAdd a step
g8_update_campaign_stepUpdate a step
g8_delete_campaign_stepDelete a step

Studio context — 5 tools

ToolDescription
g8_get_global_contextOrg-level Studio documents (brand, value props, messaging)
g8_get_icpsICP definitions
g8_get_personasBuyer persona definitions
g8_list_intelligence_dataIntelligence data (scrapes, enrichment, competitor research)
g8_list_research_reportsAI research reports (buyer psychology, GTM channel analysis)

Mailbox & KB — 4 tools

ToolDescription
g8_list_mailboxesWarmup-enabled mailboxes
g8_get_mailbox_warmupWarmup status + analytics
g8_list_kb_documentsKnowledge Base documents
g8_search_kbSearch the Knowledge Base

Pipelines (stage checklist v2) — 12 tools

gtm mode unprefixed; all mode prefixed as g8_gtm_*.

ToolDescription
g8_list_pipelinesList deal pipelines with stages + evidence + channel scripts
g8_get_pipelineGet a pipeline by ID
g8_list_stage_evidence_libraryGet the 8 canonical evidence keys
g8_create_pipelineCreate a new pipeline (default or blank)
g8_update_pipelineUpdate pipeline metadata
g8_create_stageAdd a stage with evidence + scripts
g8_update_stageUpdate a stage
g8_reorder_stagesReorder stages
g8_delete_pipelineDelete a pipeline (when no deals exist)
g8_delete_stageDelete a stage
g8_suggest_pipeline_from_contextAI-suggested pipeline from org context
g8_create_pipeline_from_suggestionCreate pipeline from AI suggestion

all mode adds — voice, workflows, skills

Available only in all mode (the default for remote OAuth).

Voice & dialer — 13 tools (g8_voice_*)

ToolDescription
g8_voice_list_dialer_sessionsList parallel dialer sessions (status, SDR, campaign, metrics)
g8_voice_get_dialer_statsAggregated dialer analytics (dials, connection rate, talk time)
g8_voice_list_numbersPhone numbers the org owns
g8_voice_list_agentsAvailable voice agents
g8_voice_list_missed_callbacksMissed inbound callbacks / voicemails
g8_voice_list_calls_for_contactCall history for a contact
g8_voice_list_calls_for_sdrCall history for an SDR
g8_voice_get_call_transcriptTranscript of a recorded call
g8_voice_get_call_gradingAI grading + talk-track feedback
g8_voice_create_dialer_sessionCreate a paused dialer session (SDR opens UI to dial)
g8_voice_pause_sessionPause a dialer session
g8_voice_resume_sessionResume a session and dial next batch (real calls)
g8_voice_stop_sessionStop a session permanently

Workflow builder — 25 tools (g8_workflow_*)

ToolDescription
g8_workflow_listList workflows
g8_workflow_getFull workflow definition (nodes, connections, trigger, execution state)
g8_workflow_createCreate a new workflow
g8_workflow_updateUpdate workflow metadata
g8_workflow_deleteDelete a workflow
g8_workflow_add_nodeAdd a node (Action, Delay, Branch, Agent, Skill, Loop)
g8_workflow_update_nodeUpdate a node’s configuration
g8_workflow_remove_nodeRemove a node
g8_workflow_connect_nodesAdd an edge between two nodes
g8_workflow_list_node_typesAvailable node types with schemas
g8_workflow_describe_node_typeDetailed schema for a node type
g8_workflow_describe_form_fieldsForm-field schema for the config UI
g8_workflow_validateValidate a workflow (orphans, dangling connections, required fields)
g8_workflow_executeExecute immediately with trigger payload
g8_workflow_get_executionStatus + output of an execution
g8_workflow_pause_executionPause an in-flight execution
g8_workflow_resume_executionResume a paused execution
g8_workflow_stop_executionStop an execution (terminal)
g8_workflow_get_trigger_statusStatus of external trigger
g8_workflow_reset_trigger_cursorReset trigger cursor (event-stream triggers)
g8_workflow_list_slack_usersSlack workspace users
g8_workflow_list_slack_channelsSlack workspace channels
g8_workflow_list_roam_usersRoam (Copilot chat) users
g8_workflow_list_roam_groupsRoam (Copilot chat) groups
g8_workflow_list_mcp_serversAvailable MCP servers (for Agent nodes)
g8_workflow_list_dispositionsAvailable call dispositions (voice nodes)

Skill authoring — 14 tools (g8_skill_* + g8_workflow_skill_* alias)

Each skill tool is registered under two names that point at the same handler — pick whichever matches the calling context (canonical g8_skill_* or workflow-namespaced g8_workflow_skill_*).

ToolDescription
g8_skill_listList skills (LLM/API building blocks)
g8_skill_getFull skill definition (type, prompt/code, model, schemas)
g8_skill_create_llmCreate an LLM skill (prompt template + model)
g8_skill_create_apiCreate an API skill (HTTP request config)
g8_skill_create_from_templateCreate a skill from a built-in template
g8_skill_create_from_nodeLift a workflow node into a reusable skill
g8_skill_update_llmUpdate an LLM skill
g8_skill_update_apiUpdate an API skill
g8_skill_deleteDelete a skill
g8_skill_executeExecute a skill immediately (test / preview)
g8_skill_validate_templateValidate a skill template
g8_skill_list_templatesList available templates
g8_skill_list_modelsList available LLM models
g8_skill_extract_variablesExtract {variable} placeholders from a prompt

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:

AttributeValuesDescription
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

Resources

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

Resource URIDescription
g8://reposList of connected repositories
g8://repos/{repo_id}/scanScan results for a repo
g8://repos/{repo_id}/kbKnowledge base documents for a repo
g8://repos/{repo_id}/kb/{doc_id}Single KB document content
g8://repos/{repo_id}/campaignsCampaigns for a repo
g8://repos/{repo_id}/campaigns/{campaign_id}/briefCampaign brief
g8://contactsContact list summary
g8://companiesCompany list summary

Prompt Templates

Pre-built prompts for common workflows.

PromptArgumentsDescription
gtm_setuprepo_urlFull setup workflow: connect, scan, install, launch
campaign_reviewcampaign_idReview and optimize a campaign
icp_refinementfeedbackRefine 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”

For agents using progressive discovery: call g8_tool_search(query="<topic>") whenever the right tool isn’t visible in the current tools/list. The matching tools become available on the next request.

Need help?