MCP — Tools Reference
The MCP server exposes 26 tools to MCP clients. Tools are grouped here by domain. Each entry shows the tool name, a one-line description, key required parameters, and the MCP annotations (readOnly, destructive, idempotent).
For full parameter shapes including optional fields, the MCP server publishes a schema via the standard MCP tools/list method — most clients (including Claude.ai) display this inline.
Contacts
Section titled “Contacts”| Tool | Description | Key params | Annotations |
|---|---|---|---|
list_contacts | List/filter contacts. Supports count_only, fields=summary, and behavioral has_event_* filters (contacts who performed a tracked event). | (filters) | read-only |
get_contact | Fetch a contact with bounded events (20). | contact_id | read-only |
create_contact | Create a contact. Min: email. | email | write |
update_contact | Update properties on a contact. | contact_id | write, idempotent |
get_contact_timeline | Chronological events for a contact across all sources. | contact_id | read-only |
get_contact_conversations | Gmail + Intercom thread history. Pass include_messages=true for bodies. | contact_id | read-only |
list_contact_email_threads | Compact thread list — thread_id, last_message_id, subject. | contact_id | read-only |
list_contact_notes | All notes on a contact. | contact_id | read-only |
create_contact_note | Add a freeform note (direct, no approval). | contact_id, content | write |
update_contact_note | Edit an existing note. | contact_id, note_id, content | write, idempotent |
delete_contact_note | Delete a note. Irreversible. | contact_id, note_id | destructive, idempotent |
Companies
Section titled “Companies”| Tool | Description | Key params | Annotations |
|---|---|---|---|
list_companies | List/filter companies (search domain, name, industry). | (filters) | read-only |
get_company | Fetch a company with up to 25 associated contacts. | company_id | read-only |
create_company | Create a company. Min: domain. | domain | write |
update_company | Update properties on a company. | company_id | write, idempotent |
list_company_notes | All notes on a company. | company_id | read-only |
create_company_note | Add a freeform note. | company_id, content | write |
update_company_note | Edit an existing note. | company_id, note_id, content | write, idempotent |
delete_company_note | Delete a note. Irreversible. | company_id, note_id | destructive, idempotent |
Events
Section titled “Events”| Tool | Description | Key params | Annotations |
|---|---|---|---|
list_events | List events with rich filters (by type, text/class/element, visitor, device). Supports count_only, fields=summary. | (filters) | read-only |
get_event | Single event with associated contact/company. | event_id | read-only |
get_event_types | Distinct event names recorded for the tenant. | — | read-only |
get_event_stats | Total + breakdown by type, domain, day. | (filters) | read-only |
Batch & Aggregate
Section titled “Batch & Aggregate”| Tool | Description | Key params | Annotations |
|---|---|---|---|
batch_get_details | Up to 25 contacts or companies in one call. | entity_type, ids | read-only |
batch_get_activity | Recent events for up to 25 contacts in one call. | contact_ids | read-only |
aggregate_data | Server-side group-by on contacts/companies/events. 50+ dimensions. | entity, group_by | read-only |
aggregate_data is the right tool for any “by X, count Y” question. Always prefer it over paginating list tools.
Enrichment actions (Apollo)
Section titled “Enrichment actions (Apollo)”These tools spend the tenant’s Apollo credits and only appear when the Apollo integration is connected and a workspace admin has enabled them (Integrations → Apollo). They also require the enrichment:write scope (opt-in-only; never auto-granted to legacy keys). They are anchored: the input is always a Pathbound entity and the result always lands in the contact graph — identity-resolved, provenance-stamped, and (if Emailable is connected) deliverability-checked in the background. They are not general prospecting tools; to build a net-new list from scratch, use Apollo’s own connector and save the keepers with create_contact / create_company.
| Tool | Description | Key params | Annotations |
|---|---|---|---|
apollo_enrich_contact | Enrich existing contacts (email, title, LinkedIn, phone, location) via Apollo people-match. Up to 25 IDs; ~1 credit per match. | contact_ids | write |
apollo_enrich_company | Enrich existing companies (industry, headcount, revenue, founded year) via Apollo. Up to 25 IDs; ~1 credit per match. | company_ids | write |
apollo_find_people | Anchored discovery: find people at a company already in Pathbound, reveal emails, and save them as contacts linked to that company. Optional titles/seniorities/departments/locations/keywords, limit (≤25), and tags. The search is free; revealing an email costs ~1 credit. | company_ids | write |
Engagement actions (Apollo sequences & email)
Section titled “Engagement actions (Apollo sequences & email)”These tools manage Apollo outreach; enrollment and single-email tools send real email through the tenant’s Apollo mailboxes, while sequence creation writes an inactive draft and turning it on is a separate, confirmed step. They appear only when Apollo is connected with a grant that includes the sequence permissions (connections made before September 2026 must be reconnected) and a workspace admin has enabled them (MCP Server → Apollo → Sequences / Single email). Writes require the actions:write scope and an Idempotency-Key (auto-generated by the MCP server). Every enrollment or send is anchored to a Pathbound contact or segment and recorded on the contact timeline. Engagement (apollo_email_sent, apollo_email_opened, apollo_email_replied, apollo_email_bounced, apollo_sequence_finished, …) is read back from Apollo on a schedule and lands there too.
Two rules hold on every surface. The sending mailbox is chosen explicitly every time — the agent lists the allowed mailboxes, the user confirms one by address, and there is no default; an admin curates the allowed list under Integrations → Apollo (empty = every active mailbox linked in the Apollo team). And Apollo’s safeguards are never overridden: contacts Apollo refuses (already in another sequence, do-not-contact stage, unverified email, …) come back in skipped with the reason. Agents can author automatic-email sequence drafts; Pathbound creates them inactive, and turning one on is a separate apollo_activate_sequence call the agent must confirm with the user (turn it off again with apollo_pause_sequence).
Scheduling and rulesets. A sequence’s sending schedule decides the days and hours Apollo may send its emails. Agents can read the team’s schedules and attach one to a sequence — at creation or afterwards — but the windows themselves are only editable in Apollo (Settings → Sequences → Schedules), which publishes no API for creating or changing a schedule. A sequence ruleset (shared settings applied to a sequence) can be set only when the sequence is created, and Apollo has no endpoint that lists or names rulesets, so apollo_list_sequence_options reports the ids already applied to the team’s sequences alongside the sequences using each one. Omit it and the sequence is created with a blank ruleset, which is Apollo’s own default.
| Tool | Description | Key params | Annotations |
|---|---|---|---|
apollo_create_sequence | Create an inactive Apollo sequence draft with 1–10 automatic-email steps, ready to send once activated. Optionally takes a schedule_id and a ruleset_id. It does not activate or enroll anyone. | name, steps | write |
apollo_activate_sequence | Turn a sequence on: Apollo starts sending its steps to every enrolled contact on the sequence schedule. Requires explicit user confirmation in the same turn. | sequence_id | write |
apollo_pause_sequence | Turn a sequence off: every enrolled contact pauses and nothing sends until it is activated again. | sequence_id | write |
apollo_list_sequences | The team’s sequences with stats, plus the sending schedule and ruleset each one runs under; archived hidden by default. Call before enrolling. | q | read-only |
apollo_list_sequence_options | The team’s sending schedules — name, time zone and the weekly windows rendered as sending_hours (e.g. “Mon–Fri 8:00–17:00”) — plus the sequence rulesets already in use. Call to answer “when will this send”, and before creating a sequence or changing its schedule. | — | read-only |
apollo_set_sequence_schedule | Point an existing sequence at one of those schedules, changing the days and hours it may send — including for contacts already enrolled. Sends only the schedule field: it never touches steps, owner, copy or on/off state. | sequence_id, schedule_id | write |
apollo_list_senders | Mailboxes an agent may send from (the allowlist). Call before enrolling or sending a single email and confirm the sender with the user. Available when either Apollo tool is enabled. | — | read-only |
apollo_add_to_sequence | Enroll 1–25 contacts in an existing sequence from a chosen mailbox. start_at enrolls them paused until that time. Contacts are matched or created in Apollo by email (free). Once per contact per sequence. | contact_ids, sequence_id, sender_account_id | write |
apollo_add_segment_to_sequence | The whole-segment version, as a background job (get_job for progress and the per-reason skip breakdown). | segment, sequence_id, sender_account_id | write |
apollo_stop_in_sequence | Stop (keep history) or remove contacts from a sequence. | contact_ids, sequence_id, mode | write |
apollo_sequence_activity | One contact’s enrollment records plus Apollo’s activity feed (enrolled, replied, completed, removed…). Meters like get_contact_timeline. | contact_id | read-only |
apollo_send_email | One email to a contact, now or at send_at (up to 30 days out), from an allowed Apollo mailbox named by sender_account_id. Pathbound holds scheduled sends and issues them through Apollo at the time; Apollo tracks opens and replies. | contact_id, sender_account_id, subject, body, send_at | write |
apollo_list_scheduled_emails | Pending, sent, delayed, failed and canceled single emails. | contact_id, status | read-only |
apollo_cancel_scheduled_email | Cancel a scheduled single email before it fires. | scheduled_email_id | write |
Authoring custom MCP integrations
Section titled “Authoring custom MCP integrations”The Pathbound MCP server is built on the @modelcontextprotocol/sdk. The same tool list above is exposed via the standard tools/list method — any compliant MCP client can connect via OAuth (interactive) or with a REST API key (headless) and call them. See MCP authentication for both flows.
For the source of truth on each tool’s parameter schema and behaviour, see packages/mcp/src/tools.ts in the Pathbound repo.