MCP Tool Reference

Reference for every tool the graph8 MCP server exposes. For setup and modes (dev / gtm / all), see the MCP Server page.

Tool counts per mode:

Mode	Count	Includes
dev	17	Repo, install, scan, forms, KB, campaigns
gtm	23	Studio campaigns, KB, ICPs, personas, global context
all	35+	Every tool below (default for remote OAuth)

All tools accept JSON arguments and return a JSON-encoded string in the MCP response. Tools annotated as destructive create real records, send real messages, charge credits, or both — confirm with the user before invoking them.

Write tools have side effects

Tools listed under “destructive” annotations write to your CRM, push to ad platforms or external CRMs, send messages to contacts, or charge credits. Always confirm intent and parameters with the user before calling them.

---

Contacts

g8_search_contacts

Search contacts already in your CRM database. Read-only. Use this to find people you already know about — for prospecting new leads use g8_find_contacts.

Parameters

Name	Type	Required	Description
email	string	no	Exact match on work email
list_id	string	no	Filter by contact list ID
name	string	no	Partial match on first or last name
job_title	string	no	Partial match on job title
seniority_level	string	no	Exact match (e.g. C-Suite, VP, Director, Manager)
company_name	string	no	Partial match on company name
country	string	no	Exact match on country
page	integer	no	Page number, default 1
limit	integer	no	Items per page, default 50, max 200

Backs: GET /contacts. Returns a paginated list of contact records.

Example

{
  "seniority_level": "VP",
  "company_name": "acme",
  "country": "US",
  "limit": 25
}

---

g8_find_contacts

Search graph8’s open data index (700M+ contacts / 100M+ companies) for prospects you don’t have in your CRM yet. Read-only. Free on both PAYG and Platform within the 5 rps cap — there is no monthly cap on index-backed endpoints.

Parameters

Name	Type	Required	Description
filters	array of objects	yes	Each filter is {field, operator, value}
page	integer	no	Default 1
limit	integer	no	Default 25, max 200

Available filter fields: first_name, last_name, work_email, job_title, seniority_level, job_department, role, linkedin_url, city, state, country, company_name, company_domain, company_industry, company_employee_count, company_revenue, company_founded_year.

Operators: any_of, contains, all_of, none_of, is_empty, is_not_empty, between, exists.

Backs: POST /search/contacts.

Example

{
  "filters": [
    {"field": "seniority_level", "operator": "any_of", "value": ["VP", "Director"]},
    {"field": "company_industry", "operator": "contains", "value": ["SaaS"]},
    {"field": "company_employee_count", "operator": "between", "value": [50, 500]}
  ],
  "limit": 50
}

---

g8_create_contact

Create a contact in your CRM. Use after g8_lookup_person to persist a prospect, or to add a contact manually. Returns the new contact_id (needed for g8_add_to_sequence and g8_add_to_list).

Parameters

Name	Type	Required	Description
work_email	string	yes	Work email address
first_name	string	no	First name
last_name	string	no	Last name
job_title	string	no	Job title
company_domain	string	no	Company domain (e.g. acme.com)
linkedin_url	string	no	LinkedIn profile URL
direct_phone	string	no	Direct phone
mobile_phone	string	no	Mobile phone
seniority_level	string	no	Seniority (e.g. VP)
city	string	no	City
state	string	no	State / province
country	string	no	Country
list_id	integer	no	Optionally add to this list immediately

Backs: POST /contacts. Returns the contact record including contact_id.

Caution

Writes a real CRM record. Confirm with the user before calling.

---

g8_enrich_contacts

Enrich existing CRM contacts with third-party data via graph8’s multi-provider waterfall. Runs asynchronously and returns a job_id. Credits charged per contact.

Parameters

Name	Type	Required	Description
contact_ids	array of integers	yes	CRM contact IDs to enrich
list_id	integer	yes	List the contacts belong to (required for job tracking)
mode	string	no	live (default — runs the enrichment + charges credits) or preview (dry-run, returns cost + provider plan without charging)
ai_group_id	string	no	Reuse an existing AI prompt group instead of creating a new one
providers	array of strings	no	Override the default provider order. Allowed values: apollo, dropcontact, emaillistverify, graph8, hunter, icypeas, leadmagic, lusha, prospeo, rocketreach. Mutually exclusive with caller-supplied raw steps on the underlying config endpoint.
email_verification	boolean	no	When true, attach ZeroBounce email verification (system credentials, valid_statuses=["valid"]) to the waterfall pipeline so deliverability is checked before the contact is marked enriched. Default false.

Behavior

• When providers or email_verification is supplied, the tool first calls POST /enrichment/waterfall/configs to upsert a fresh waterfall config built from your overrides (BYOK fallback handled per provider), then dispatches the enrichment job.
• When neither is supplied, the tool reuses the org’s existing active waterfall config for that column (creating the default graph8 lookup-person pipeline if none exists).

Backs: POST /enrichment/waterfall/configs (when overrides supplied) + POST /enrichment/waterfall/enrich.

Caution

Charges credits per contact. Confirm with the user first. Use mode="preview" to estimate cost without running.

---

Fields

g8_create_field

Create a custom column on a contact / company / account list. STRONGLY RECOMMENDED: pass enrichment_providers (or enrichment_email_verification=true) in the SAME call whenever the column is meant to hold enriched data (emails, phones, job titles, etc.). The companion waterfall config is provisioned in the same request so the UI Enrich button and g8_enrich_contacts work out-of-the-box.

If you skip the enrichment args, the column exists but isn’t runnable — g8_enrich_contacts and the UI Enrich button will both fail with 422 waterfall_config_missing. You’d then have to call POST /enrichment/waterfall/configs to repair it.

Parameters

Name	Type	Required	Description
list_id	integer	yes	List the column belongs to
name	string	yes	Display name for the column (e.g. "Verified work email")
type	string	yes	Column type: text, number, boolean, single_select, multi_select, date, url, email, phone
description	string	no	Optional column description
options	array of strings	no	Required when type is single_select or multi_select
enrichment_providers	array of strings	no	When supplied, a companion waterfall config is created. Same allowed providers as g8_enrich_contacts.
enrichment_email_verification	boolean	no	When true, the companion config also runs ZeroBounce email verification. Default false.
enrichment_name	string	no	Friendly name for the waterfall pipeline. Defaults to a name derived from providers + verification flag.

Backs: POST /fields with optional nested enrichment block. When the enrichment block is included, the backend writes both dynamic_columns and enrichment_configs in the same request and the response includes both column_id and config_id.

Example — column only

{
  "list_id": 123,
  "name": "Lead temperature",
  "type": "single_select",
  "options": ["hot", "warm", "cold"]
}

Example — column + waterfall enrichment

{
  "list_id": 123,
  "name": "Verified work email",
  "type": "email",
  "enrichment_providers": ["hunter", "prospeo", "graph8"],
  "enrichment_email_verification": true,
  "enrichment_name": "Verified email waterfall"
}

Caution

Writes a real column. When the enrichment_* args are present, also writes a real waterfall config row. Confirm with the user before calling.

---

Companies

g8_search_companies

Search companies already in your CRM. Read-only. For new prospects use g8_find_companies.

Parameters

Name	Type	Required	Description
domain	string	no	Filter by company domain
industry	string	no	Filter by industry
name	string	no	Partial match on name
page	integer	no	Default 1
limit	integer	no	Default 50, max 200

Backs: GET /companies.

---

g8_find_companies

Search graph8’s open data index for companies you don’t track yet. Read-only, credits charged per record returned.

Parameters

Name	Type	Required	Description
filters	array of objects	yes	{field, operator, value} filters
page	integer	no	Default 1
limit	integer	no	Default 25, max 200

Filter fields: name, domain, industry, industry_group, employee_count, revenue, founded_year, country, state, city, linkedin_followers.

Operators: same set as g8_find_contacts.

Backs: POST /search/companies.

---

Enrichment & Lookup

g8_lookup_person

Look up a single person in graph8’s data index. Returns enriched data (verified email, phone, job title, company, confidence score). Costs 1 credit.

Provide at least one of: email, linkedin_url, or (first_name + last_name + company_domain).

Parameters

Name	Type	Required	Description
email	string	conditional	Person’s email
linkedin_url	string	conditional	LinkedIn profile URL
first_name	string	conditional	Combine with last_name and company_domain
last_name	string	conditional
company_domain	string	conditional	e.g. acme.com

Backs: POST /enrichment/lookup/person.

---

g8_lookup_company

Look up a single company. Returns revenue, headcount, industry, tech stack, funding, confidence score. Costs 1 credit.

Provide at least one of: domain or name.

Parameters

Name	Type	Required	Description
domain	string	conditional	Company domain
name	string	conditional	Company name

Backs: POST /enrichment/lookup/company.

---

Lists

g8_get_lists

List contact and company lists in your CRM. Read-only.

Parameters

Name	Type	Required	Description
page	integer	no	Default 1
limit	integer	no	Default 50

Backs: GET /lists.

---

g8_create_list

Create a new empty contact or company list. Returns the list_id.

Parameters

Name	Type	Required	Description
title	string	yes	List name (e.g. "Enterprise Q2 Targets")
type	string	no	"contacts" or "companies" (default "contacts")

Backs: POST /lists.

---

g8_add_to_list

Add existing contacts (must already have contact_ids) to a list.

Parameters

Name	Type	Required	Description
list_id	integer	yes	Target list
contact_ids	array of integers	yes	Contact IDs to add

Backs: POST /lists/{list_id}/contacts.

---

g8_build_contact_list

Search prospects and save matching results to a new list in one call. Free on both PAYG and Platform (within 5 rps) — save-to-list is part of the unlimited index bundle. Credits only deduct later when you enrich, send, or generate AI content on the saved records.

Parameters

Name	Type	Required	Description
filters	array of objects	yes	Same filter format as g8_find_contacts
list_title	string	yes	Name for the new list
max_results	integer	no	Cap on contacts saved (default 100)

Backs: POST /search/contacts/save.

Caution

Creates real contacts and a real list. Charges credits per contact. Run g8_find_contacts first to preview before committing.

---

Pipeline & CRM

g8_get_deals

List deals in your CRM with optional filters. Read-only.

Parameters

Name	Type	Required	Description
page	integer	no	Default 1
limit	integer	no	Default 50
stage_id	string	no	Filter by stage
pipeline_id	string	no	Filter by pipeline
search	string	no	Free-text search

Backs: GET /deals.

---

g8_get_deal

Get details for a single deal. Read-only.

Parameters

Name	Type	Required	Description
deal_id	string	yes	Deal ID

Backs: GET /deals/{deal_id}.

---

g8_get_pipeline

List deal pipelines and their stages. Read-only. No parameters.

Backs: GET /deals/pipelines.

---

Tasks

g8_get_tasks

List tasks for the current organization. Read-only.

Parameters

Name	Type	Required	Description
status	string	no	Filter by status
priority	integer	no	Filter by priority
assignee_id	string	no	Filter by assignee
search	string	no	Free-text search

Backs: GET /tasks.

---

g8_create_task

Create a task linked to a CRM contact.

Parameters

Name	Type	Required	Description
contact_id	integer	yes	Contact the task belongs to
title	string	yes	Task title
description	string	no	Task description
due_date	string	no	ISO 8601 date string
assignee_id	string	no	User ID of assignee
priority	integer	no	Priority value

Backs: POST /contacts/{contact_id}/tasks.

---

Activity & Notes

g8_get_activities

List recent CRM activities for the current organization. Read-only.

Parameters

Name	Type	Required	Description
limit	integer	no	Default 50
activity_type	string	no	Filter by activity type
contact_id	string	no	Filter by contact
company_id	string	no	Filter by company
deal_id	string	no	Filter by deal

Backs: GET /activities.

---

g8_create_note

Add a note to a CRM contact.

Parameters

Name	Type	Required	Description
contact_id	integer	yes	Contact to attach the note to
content	string	yes	Note body

Backs: POST /contacts/{contact_id}/notes.

---

Sequences

g8_list_sequences

List available outbound sequences. Read-only. Use to find a sequence_id before calling g8_add_to_sequence.

Parameters

Name	Type	Required	Description
page	integer	no	Default 1
limit	integer	no	Default 50

Backs: GET /sequences.

---

g8_create_sequence

Create a new outbound sequence (drafted). Optionally include steps and channels.

Parameters

Name	Type	Required	Description
name	string	yes	Sequence name
user_email	string	yes	Owner email
description	string	no	Description
finish_on_reply	boolean	no	Default true
send_in_same_thread	boolean	no	Default false
steps	array of objects	no	Each step: {step_order, step_type, input_type, time_interval, step_data}
channels	array of objects	no	Each channel: {channel_id, channel_value, channel_type}
campaign_id	string	no	AI Studio campaign to link

Backs: POST /sequences.

Caution

Creates a real sequence. Confirm with the user first.

---

g8_get_sequence_preview

Preview a sequence with steps and channels. Read-only — no enrollment.

Parameters

Name	Type	Required	Description
sequence_id	string	yes	Sequence ID

Backs: GET /sequences/{sequence_id}/preview.

---

g8_update_sequence

Update sequence metadata. Cannot modify while in a transitional state.

Parameters

Name	Type	Required	Description
sequence_id	string	yes	Sequence to update
name	string	no	New name
description	string	no	New description
is_shared	boolean	no	Shared flag
finish_on_reply	boolean	no
send_in_same_thread	boolean	no
wait_for_new_contacts	boolean	no

Backs: PATCH /sequences/{sequence_id}.

---

g8_update_sequence_step

Update a single step in a sequence.

Parameters

Name	Type	Required	Description
sequence_id	string	yes	Parent sequence
step_id	string	yes	Step to update
step_data	object	no	Template / content data
time_interval	integer	no	Delay (seconds) after previous step
step_type	string	no	EMAIL, PHONE, SMS, etc.
input_type	string	no	ON_DEMAND or TEMPLATE

Backs: PATCH /sequences/{sequence_id}/steps/{step_id}.

---

g8_add_to_sequence

Enroll contacts in an outbound sequence.

Parameters

Name	Type	Required	Description
sequence_id	string	yes	From g8_list_sequences
contact_ids	array of integers	yes	CRM contact IDs
list_id	integer	yes	List the contacts belong to

Backs: POST /sequences/{sequence_id}/contacts.

Danger

This enrolls real contacts into an active sequence that will send emails or messages. Always confirm with the user before calling.

---

g8_pause_sequence

Pause a live sequence — contacts in progress wind down.

Parameters

Name	Type	Required	Description
sequence_id	string	yes	Sequence to pause

Backs: POST /sequences/{sequence_id}/pause.

Caution

Pauses real outreach. Confirm with the user first.

---

g8_resume_sequence

Resume a paused sequence.

Parameters

Name	Type	Required	Description
sequence_id	string	yes	Sequence to resume

Backs: POST /sequences/{sequence_id}/resume.

Caution

Resumes real outreach. Confirm with the user first.

---

g8_get_sequence_analytics

Get overview, performance, engagement, timeline, and contact distribution for a sequence. Read-only.

Parameters

Name	Type	Required	Description
sequence_id	string	yes	Sequence ID

Backs: GET /sequences/{sequence_id}/analytics.

---

g8_delete_sequence

Soft-delete (archive) a sequence. Sets is_archived=true. Hidden from UI and excluded from worker processing.

Parameters

Name	Type	Required	Description
sequence_id	string	yes	Sequence to archive

Backs: DELETE /sequences/{sequence_id}.

Danger

Archives a real sequence. Confirm with the user first.

---

Inbox

Multi-channel inbox covering email, SMS, and LinkedIn. Each tool accepts an optional channel (email / sms / linkedin, default email).

g8_list_inbox

List inbox threads across channels. Read-only.

Parameters

Name	Type	Required	Description
channel	string	no	email, sms, linkedin, or omit for all
sequence_id	string	no	Filter by sequence/campaign
status	string	no	Filter by status
assignee	string	no	Assignee email
tag	string	no	Tag ID
page	integer	no	Default 1
page_size	integer	no	Default 50, max 200

Backs: GET /inbox.

---

g8_get_reply

Get a single inbox thread with full message history. Read-only.

Parameters

Name	Type	Required	Description
reply_id	string	yes	Thread / reply ID
channel	string	no	Default "email"

Backs: GET /inbox/{reply_id}.

---

g8_assign_reply

Assign a user to an inbox thread.

Parameters

Name	Type	Required	Description
reply_id	string	yes	Thread / reply ID
assignee_email	string	yes	User to assign
channel	string	no	Default "email"

Backs: POST /inbox/{reply_id}/assign.

---

g8_tag_reply

Attach tags to an inbox thread.

Parameters

Name	Type	Required	Description
reply_id	string	yes	Thread / reply ID
tag_ids	array of strings	yes	Tag IDs
channel	string	no	Default "email"

Backs: POST /inbox/{reply_id}/tag.

---

g8_get_reply_draft

Generate an AI draft reply for a thread. Charges credits. Returns HTTP 402 if the org has insufficient credits.

Parameters

Name	Type	Required	Description
reply_id	string	yes	Thread / reply ID
channel	string	no	Default "email"

Backs: GET /inbox/{reply_id}/draft.

---

g8_send_reply

Send a reply through the specified channel.

Parameters

Name	Type	Required	Description
reply_id	string	yes	Thread to reply to
body	string	yes	Message body
channel	string	yes	email, sms, or linkedin
subject	string	no	Email subject (email channel)
to	string	no	Recipient (email / phone / LinkedIn ID)
from_address	string	no	Sender mailbox / phone / LinkedIn account

Backs: POST /inbox/{reply_id}/send.

Danger

Sends a real message to the contact. Always confirm body and recipient with the user.

---

Audience Sync

Push graph8 audience lists to ad platforms (Meta, LinkedIn, Google, X).

g8_list_audience_syncs

List all audience sync configurations. Read-only. No parameters.

Backs: GET /audience-syncs.

---

g8_create_audience_sync

Create a new audience sync. Returns 409 if a sync already exists for the same audience + platform.

Parameters

Name	Type	Required	Description
audience_id	integer	yes	Audience list ID
platform	string	yes	meta, linkedin, google, or x
mode	string	no	mirror (add+remove) or append_only (default mirror)
refresh_cadence_hours	integer	no	Default 24
platform_audience_name	string	no	Custom name on the platform

Backs: POST /audience-syncs.

---

g8_get_audience_sync

Get a single sync configuration. Read-only.

Parameters

Name	Type	Required	Description
config_id	integer	yes	Sync config ID

Backs: GET /audience-syncs/{config_id}.

---

g8_update_audience_sync

Update sync config (mode, cadence, active flag).

Parameters

Name	Type	Required	Description
config_id	integer	yes	Sync config ID
mode	string	no	mirror or append_only
refresh_cadence_hours	integer	no
is_active	boolean	no	Enable / disable

Backs: PATCH /audience-syncs/{config_id}.

---

g8_delete_audience_sync

Soft-delete a sync configuration. The audience on the ad platform is not deleted — manage that on the platform directly.

Parameters

Name	Type	Required	Description
config_id	integer	yes	Sync config ID

Backs: DELETE /audience-syncs/{config_id}.

Caution

Deactivates the sync. Confirm with the user first.

---

g8_trigger_audience_sync

Manually push the latest audience members to the ad platform now.

Parameters

Name	Type	Required	Description
config_id	integer	yes	Sync config ID

Backs: POST /audience-syncs/{config_id}/trigger.

Danger

Pushes real data to the ad platform immediately. Confirm with the user first.

---

g8_get_audience_sync_runs

Get sync run history with status, member counts, and timing. Read-only.

Parameters

Name	Type	Required	Description
config_id	integer	yes	Sync config ID
limit	integer	no	Default 20, max 100

Backs: GET /audience-syncs/{config_id}/runs.

---

g8_get_audience_sync_errors

Get failed sync runs with error messages. Read-only.

Parameters

Name	Type	Required	Description
config_id	integer	yes	Sync config ID
limit	integer	no	Default 20, max 100

Backs: GET /audience-syncs/{config_id}/errors.

---

CRM Sync

Push contacts, companies, and list memberships to external CRMs (HubSpot, Salesforce, Pipedrive, Zoho, SugarCRM).

g8_list_crm_syncs

List configured CRM integrations and their connection status. Read-only. No parameters.

Backs: GET /crm-syncs.

---

g8_push_to_crm_contact

Push contacts to an external CRM.

Parameters

Name	Type	Required	Description
provider	string	yes	hubspot, salesforce, pipedrive, zoho, or sugarcrm
records	array of objects	yes	Contact records (each a dict of contact fields)

Backs: POST /crm-syncs/{provider}/contacts/push.

Danger

Creates real records in the external CRM. Confirm with the user first.

---

g8_push_to_crm_company

Push companies to an external CRM.

Parameters

Name	Type	Required	Description
provider	string	yes	CRM provider
records	array of objects	yes	Company records

Backs: POST /crm-syncs/{provider}/companies/push.

Danger

Creates real records in the external CRM. Confirm with the user first.

---

g8_push_to_crm_list

Modify CRM list memberships (add/remove contacts from lists). Each record contains list_id, add_contact_ids, remove_contact_ids.

Parameters

Name	Type	Required	Description
provider	string	yes	CRM provider
records	array of objects	yes	Membership operations

Backs: POST /crm-syncs/{provider}/lists/push.

---

g8_get_crm_fields

Discover available fields for an entity type on a CRM provider — useful for building field mappings before pushing data. Read-only.

Parameters

Name	Type	Required	Description
provider	string	yes	CRM provider
entity_type	string	no	contacts (default), companies, leads, deals

Backs: GET /crm-syncs/{provider}/fields.

---

g8_get_crm_status

Check connection health for a CRM provider. Read-only.

Parameters

Name	Type	Required	Description
provider	string	yes	CRM provider

Backs: GET /crm-syncs/{provider}/status.

---

Tool Annotations

Every MCP tool carries one of two annotation presets that hint at side effects:

Annotation	Meaning
readOnlyHint=true, idempotentHint=true	Safe to call repeatedly. No writes, no credits, no external delivery.
destructiveHint=true, openWorldHint=true	Writes to your CRM, sends messages, pushes to external systems, or charges credits. Confirm with the user before invoking.

Tools without an explicit annotation (e.g. g8_create_contact, g8_create_list, g8_add_to_list, g8_create_task, g8_create_note, g8_assign_reply, g8_tag_reply, g8_create_audience_sync, g8_update_audience_sync) still write data — they just aren’t tagged as destructive in the MCP layer. Treat any tool that creates or modifies records as a write.

---

See Also

• MCP Server setup — install, modes, OAuth, environment variables
• What You Can Ask — natural-language prompt patterns
• CLI — same operations from the command line
• REST API: Contacts, Companies, Lists, Sequences — underlying HTTP endpoints