MCP Tools

MCP (Model Context Protocol) lets you connect heyBTW to AI agents like Claude, ChatGPT, or a custom agent system. Once connected, your agent can query your event data, partner relationships, attribution, and cross-event patterns in natural language. Read tools are available on every plan, including Free. One write tool, activate_list, sends real invites and is gated separately — see Write tools.

​

Setup

​

Generate an API key

1. Click your account name in the bottom-left sidebar to open the account menu.
2. Select API Keys.
3. Click Generate API Key to create a workspace-scoped key. The key starts with hbtw_ws_ and is tied to your workspace, not to an individual user.

You can regenerate or revoke the key at any time from this page, which also shows when the key was created and last used.

​

Connect your agent

The API Keys page includes a ready-to-copy configuration snippet for Claude Desktop. Expand the Connect to Claude Desktop section and copy the JSON config block. It uses npx mcp-remote to reach the heyBTW MCP server with Bearer token authentication. Paste the config into your client’s configuration file. For Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Replace <your-key> with your actual API key. Any MCP-compatible client connects the same way: point it at the heyBTW MCP server with the key as a Bearer token.

​

Restart and verify

Restart your client. heyBTW tools will appear as available MCP tools in your conversations.

​

Join heyBTW with your CRM through MCP

This is the pattern security-conscious enterprises reach for. You do not have to connect your CRM to heyBTW at all. Instead, run two MCP servers behind your agent: heyBTW’s, for event attendance and relationship intelligence, and your CRM’s own MCP server (Salesforce, HubSpot, or Attio), for pipeline data. Your agent does the join. heyBTW never connects to or receives your CRM data. heyBTW supplies the relationship and event-attendance layer, your CRM keeps the pipeline, and the agent cross-references the two to produce attribution that neither system could generate alone. See CRM for the direct-connection alternative.

​

Available tools

heyBTW exposes nine tools today: the eight read tools in this section, plus one write tool, activate_list. All tools are workspace-scoped, meaning they only return data from your workspace. The workspace is determined by your API key, never passed as a parameter. Each tool below links to a full reference page with its complete parameter table, a real sample response, and a field-by-field breakdown — read the reference page before building a parser against a tool’s output.

​

get_workspace_overview

Program health and agent capability discovery. Call this first in a new session — it tells you which integrations are connected and which other tools will return real data versus an empty/degraded result.

• When to use it. “What can I ask about this workspace?” or as the first call before anything else.
• Parameters. date_from (optional).

​

get_account_relationship

Full Context Graph profile for one account: event history, contacts with seniority, warm intro paths, engagement trajectory, and CRM pipeline context.

• When to use it. “Tell me everything about Zynga” or “Give me a profile on stripe.com.”
• Parameters. domain (preferred) or account_name — one required. limit (optional, default 50).

​

get_partner_insights

Partner influence data: sourcing breakdown, seniority profile, funnel rates, and pipeline impact per partner.

• When to use it. “Which partners have a relationship with a target account we could leverage for a warm intro?”
• Parameters. partner_name (optional), partner_domain (optional), include_archived (optional, default false).

​

get_event_attribution

Attribution data connecting events to pipeline outcomes. Classifications follow the Attribution Model: every deal is Sourced or Influenced.

• When to use it. “Which deals can we attribute to the Berlin Fintech Dinner in March?”
• Parameters. event_name or channel_id (both optional; either narrows to one event, omit both for all events), date_from (optional), date_to (optional).

​

get_cross_event_patterns

Multi-event account engagement trajectories: which companies are compounding engagement, and which are cooling off.

• When to use it. “Which accounts have attended 3 or more events?”
• Parameters. domain (optional), min_events (optional, default 2), limit (optional, default 20), include_own_domain / include_partner_accounts (optional, default false).

​

get_invite_recommendations

Ranked invite candidates for a specific upcoming event, drawing on ABM list membership, past attendance, and conversion history. Each candidate carries a plain-English reasoning string. Rank on response order: the numeric ranking scalar is withdrawn and deliberately undocumented, though contract v1 still emits it — see the tool reference for exactly what is on the wire versus what to build on.

• When to use it. “Who should we invite to this event?” once the event exists in heyBTW.
• Parameters. event_name or channel_id (one required to name the target event), limit (optional, default 25), include_own_domain (optional, default false).

​

get_event_details

The single-event deep dive: logistics and roster, attendance breakdown, seniority distribution, partner performance, top accounts, program comparison, and pipeline for one event. Meaningful before an event runs as well as after.

• When to use it. “Give me a report on last month’s Robotics Summit” or “Who’s registered for next week’s dinner?”
• Parameters. event_name or channel_id (one required), include_contacts / include_partner_breakdown (optional, default false).
• Renamed. Shipped as get_event_summary; renamed by HEY-2029. The old name is not registered and will not resolve.

​

query_event_intelligence — deprecated

Cross-event attendance grouped by company, with inline contacts.

• Deprecated, being retired by HEY-1895 and absent from the v2 toolset (HEY-893). Still served on v1; do not build new integrations on it. Use get_cross_event_patterns, get_account_relationship, or get_event_details depending on the question — see what to use instead.
• Parameters. event_name (optional), domain (optional), limit (optional, default 10), include_own_domain (optional, default false).

​

Response format

Every tool response includes a metadata block with data provenance: which data sources were queried, what date range was applied, which filters were active, and a coverage note about data completeness. This helps the agent communicate data context to the user. When no data matches your filters, tools return empty results with a clear coverage note. They do not error. An agent should read the coverage note before concluding that something is zero, because a missing data source (for example, an Attio workspace without a deal-created date field) can limit what a query can see.

​

Representing attribution honestly

When an agent reports heyBTW attribution, it should phrase claims the way the model intends. Over-claiming Sourced is the fastest way to lose a sophisticated buyer.

• Lead with Influenced for in-flight pipeline. It holds up under scrutiny, and it is safe to claim even when the source is null or owned by sales or another channel.
• Claim Sourced only with strong evidence and provenance. Never infer Sourced from heyBTW driving the targeting, and never claim Sourced for a sales- or SDR-originated lead. If the source is unclear, the honest claim is Influenced.
• Always cite provenance. Name the event, attendee, and timestamps behind a claim.
• Acceleration is correlation, not causation. It is a weight on Influenced, in development today. When it ships, describe it as correlating with faster stage progression, never as having caused movement, and always pair it with the Influenced claim.

See the Attribution Model for the full definitions.

​

Schema stability

The tool schemas and the response envelope are a stability commitment, not an implementation detail. The claim shape, dimension names, the Sourced and Influenced rule, and the exclusion rules are stable. Signal weighting nuances and partner sub-hierarchy refinements may evolve. If you build on a specific field, pin to the schema version. Schema discovery is exposed via the MCP and OpenAPI surfaces. See the Attribution Model for what is stable versus what may change. Current MCP reads are workspace-scoped at the data-access boundary. The proposed versioned identity and privacy target adds opaque entity references, foreign-handle isolation, and deletion guarantees while bounding the existing cmp_ compatibility behavior. It is documented in MCP Standards. Fields described there as a target are not live until the architecture is accepted and the tool reference page names the supported response version.

​

Contract versions

Every tool accepts an optional contract_version parameter.

• Omit it. Omission selects v1, and v1 is the only version advertised for every tool today. Unless you pass this parameter, v1 is what you receive.
• A newer response contract exists but is not advertised. It is where the withdrawn scalars described on the tool reference pages are actually removed. It is deliberately not published as adoptable: it is incomplete until the opaque-identity work in MCP Standards lands, and its meaning will still change. Do not build against it.
• Any value that is not advertised may be rejected with a structured invalid_parameter error. There is never a silent downgrade — you will not ask for one contract and quietly receive another.

​

Write tools

One write tool is live on this surface.

​

activate_list

Sends a saved List to its linked Luma event, behind a mandatory human confirmation round trip.

• This tool sends real invites to real people on action="confirm". It is registered readOnlyHint=false and idempotentHint=false, and both are accurate. Call action="preview" first, present the returned payload to a human, and only send on their explicit go-ahead.
• When to use it. After a list-building tool such as get_invite_recommendations — never as the first call in a session.
• Parameters. action (preview / confirm / status / funnel), list_id, activation_id, message, client_request_id, typed_count, weekly_warning_acknowledged.
• Access. Requires a workspace-scoped key (admin and global keys are refused) and a plan including the agent-connections-outbound capability.

Read the full reference before calling it, in particular when a retry is safe.

​

Plans and access

• Free. All eight read tools: workspace overview, account relationships, partner insights, attribution, cross-event patterns, invite recommendations, event details, and event intelligence.
• Growth. Full MCP read access for Claude, ChatGPT, and AI assistants.
• Enterprise. Everything in Growth, plus SSO/SAML on the MCP server.

activate_list is gated on the agent-connections-outbound capability rather than on a plan tier by name. Check get_workspace_overview for what your workspace actually has, or ask your admin. The workspace-scoped API key (hbtw_ws_...) grants access to the tools your plan includes. Regenerating the key invalidates the old one immediately.

​

Permissions

The eight read tools are read-only and available on all plans, including Free. They query your workspace data without modifying it, and a repeated call is safe. activate_list is not one of them. It is a write tool whose effect leaves heyBTW entirely: action="confirm" sends real invites to real people through Luma. Do not reason about it as “creating or updating a record in your workspace,” and do not assume a repeated call is free — see when a retry is safe. It requires a workspace-scoped key (admin and global keys are refused) and a plan carrying the agent-connections-outbound capability. The API key is workspace-scoped and grants access to the tools your plan includes, so treat it like a shared credential. Admins generate and manage the key from Account > API Keys.

​

Your workspace’s domain

By default, your own workspace’s domain is excluded from company-level aggregation results. This prevents your own employees from skewing account-level analytics.