Skip to main content
The Model Context Protocol (MCP) lets AI tools and agents connect to Heymarket in a secure, standardized way. Heymarket hosts a remote MCP server, so a connected client can read your inboxes, search contacts and messages, send messages, triage conversations, and draft broadcast campaigns on behalf of an authenticated team member.
The Heymarket MCP server is in beta. Endpoints, tools, and authentication may change. Try it on a non-critical team first and share feedback with Heymarket.
Sign in with Heymarket
You can now connect Claude, Claude Code, ChatGPT, and Codex to Heymarket by signing in, without creating a token:
  • Sign in from your AI app - add https://mcp.heymarket.com/mcp to the app, sign in to Heymarket in your browser, and choose the team the app can access. See Sign in with Heymarket.
  • One team per app - each app connection works with one team. Connecting the same app to another team moves it to that team. See One team per connection.
  • Connected AI apps - see and disconnect your apps under Profile > Connected AI apps. Team owners and admins can see and disconnect members’ apps on the Team tab. See Manage connected apps.
  • Ten tools and both prompts need a token - sign-in connections cannot delete contacts or lists, transfer conversations, work with broadcasts, or upload files from your machine. They can still send pictures and files from a public link. See Tools that need a personal access token.
  • New whoami tool - shows which Heymarket user and team a connection acts as.
  • Personal access tokens still work - use them for Cursor and other clients, and for the tools and prompts above.
See also Example prompts and Data and privacy.
Team MCP switch and 12 new tools
MCP no longer needs to be enabled by Heymarket:
  • On by default - every team has MCP on unless someone turns it off
  • Team MCP switch - owners and admins can turn MCP off for the whole team under Administration > Team; existing tokens work again when it is turned back on
  • Locked when Heymarket turns MCP off - Heymarket can turn MCP off for a team; the team’s MCP switch then shows Off and stays locked until Heymarket support lifts the lock
  • New 403 codes - mcp_team_expired, mcp_disabled_by_heymarket, and mcp_disabled_by_admin explain why a valid token was refused, alongside mcp_permission_required; they replace mcp_not_enabled
  • MCP status in the API - Get team now returns mcp_disabled and mcp_disabled_by_heymarket
See Turn MCP on or off for your team.The server now has 46 tools, up from 34:
  • Pictures and files (MMS) - send_message takes a media_url, and create_attachment_upload uploads a file from your machine to send. See Send pictures and files.
  • Private comments - add_private_comment adds an internal note to a conversation and can @mention teammates. See Add private comments.
  • Conversation state - close, reopen, or mark a conversation pending, unassign or block it, and mute, snooze, set a reminder on, or mark it read or unread for yourself
  • “via MCP” label - messages and private comments created through MCP show in Heymarket as written by you via MCP. See How MCP messages are labeled.
Reconnect your client to see the new tools. See Available tools.
MCP Access role permission
Access to the MCP server is now controlled per role:
  • New MCP Access permission - a team member can create a Personal Access Token and connect an MCP client only when their role includes MCP Access
  • Included for Owner and Admin - the Member role does not include it; admins can grant it to members through a custom role
  • Checked on every request - turning the permission off for a role stops its members’ existing tokens on their next request
See Who can use MCP.
Outbound outreach and triage release
The tool surface grew from 12 to 34 tools. New in this release:
  • Supervised broadcasts - draft a campaign to a list, review the recipient count, and submit it for human approval before anything sends
  • Contact lists - create and manage the lists broadcasts send to
  • Templates and team members - discover message templates and look up teammates
  • Triage and search - list and count conversations across inboxes, full-text search over message bodies, and a conversation activity timeline
  • Richer contact search - filter by tags, custom fields, lists, opt-out status, and assigned user
  • Token creation opened to members - any team member (not just admins) can now create a Personal Access Token

What you can do

Once a client is connected, you can ask it to:
  • Browse inboxes - list the inboxes you belong to and look up inbox details
  • Manage contacts - create, retrieve, update, delete, and search contacts, including by tag, custom field, list, opt-out status, or assigned user
  • Send messages - send a message to a contact through an inbox, with a picture or file attached
  • Add private comments - leave an internal note on a conversation and @mention teammates
  • Read and search history - pull a conversation’s message history or full-text search message bodies across your inboxes
  • Triage conversations - list conversations longest-waiting first, count them by assignee, inbox, or status, and see a conversation’s assignment history
  • Work conversations - assign, unassign, or transfer a conversation; close, reopen, or mark it pending; or block it
  • Keep your own queue - mute, snooze, or mark a conversation read or unread for yourself, and set a reminder to follow up
  • Run broadcasts with approval - build an audience list, draft a broadcast, and submit it for a human admin to approve before it sends
Deleting contacts and lists, transferring conversations, broadcasts, and uploading files from your machine need a personal access token. An app connected by signing in can do everything else, including sending a picture or file from a public link. See Tools that need a personal access token. The MCP server exposes Heymarket actions only. The AI model itself lives in your client (Claude, ChatGPT, Cursor, and so on), not in Heymarket.

Endpoint and transport

Connect your client to the Heymarket MCP server at:
The server uses the Streamable HTTP transport and speaks JSON-RPC over HTTP. Clients that support remote MCP servers can connect to this URL directly. Claude, Claude Code, ChatGPT, and Codex can also sign in to it. Clients that speak only stdio connect through the open-source mcp-remote bridge, which runs the remote server as a local command and sends a personal access token.

Authentication

You can connect an AI app to Heymarket in two ways:
  • Sign in with Heymarket. Recommended for Claude (on the web and in the desktop app), Claude Code, ChatGPT, and Codex. You add the server URL to the app, sign in to Heymarket in your browser, and choose the team the app can access. There is no token to copy or store. Sign-in uses OAuth. See Sign in with Heymarket.
  • Personal Access Token (PAT). A long-lived credential scoped to one team member and one team. Use it for clients that cannot sign in, such as Cursor, and for the tools and prompts that need a token. Every MCP request sends it as a bearer token:

Choose how to connect

Prefer sign-in when your app supports it. Use a personal access token when your client cannot sign in, when you need one of the ten token-only tools or a prompt, such as for broadcasts, or when you want one app to work with several teams at once.

Who can use MCP

You can connect an AI app to a team, by signing in or with a token, only when both of these are true:
  • MCP is on for the team. MCP is on for every team by default. A team owner or admin can turn it off, and so can Heymarket. MCP is also unavailable while the team’s subscription has expired or the team is suspended. See Turn MCP on or off for your team.
  • Your role in that team includes the MCP Access permission.
To sign in, your Heymarket profile also needs a valid email address. Heymarket checks these conditions on every MCP request, not only when you connect. If an admin turns off MCP Access for your role, moves you to a role without it, or turns MCP off for the team, your existing tokens and sign-in connections stop working within a few seconds. The same happens when Heymarket turns MCP off for the team or the team’s subscription expires. They are blocked, not revoked, and they work again once the cause is cleared.

Grant MCP access to a role

System roles such as Owner, Admin, and Member cannot be modified, so to give members MCP access, create a custom role that includes it. You need the Roles permission to manage roles, and creating custom roles depends on your Heymarket plan.
1

Open Roles

In Heymarket, click the Administration icon in the left sidebar, then select the Roles tab.
2

Duplicate the Member role

Open the ⋯ menu on the Member row, select Duplicate, and click Copy to confirm. The new role is named Copy of Member. To rename it, open its ⋯ menu and select Edit.
3

Turn on MCP Access

Open the new role, check MCP Access, and click Save Role.
4

Assign the role

On the Users tab, assign the new role to each team member who needs MCP access.

Turn MCP on or off for your team

A team owner or admin can turn MCP off for the whole team, for example to pause every connected AI client at once. Only members whose role is the Owner or Admin system role can change this setting. Custom roles cannot, including roles duplicated from Admin.
1

Open the Team tab

In Heymarket, click the Administration icon in the left sidebar, then select the Team tab.
2

Find the MCP Access section

The MCP (Model Context Protocol) switch in the MCP Access section is the team’s MCP switch. It shows whether MCP is On or Off for the team.
3

Turn MCP off

Turn the switch off. In the Turn off MCP for this team? dialog, click Turn Off to confirm. The message “MCP access updated.” confirms the change.
While MCP is off for the team:
  • MCP clients connected to the team stop working within a few seconds. Requests that use a token return 403 Forbidden with the code mcp_disabled_by_admin. Requests from apps connected by signing in are refused with the message “A team admin has turned off MCP for team” followed by the team’s name.
  • No one can generate a new token for the team or connect a new app to it by signing in.
  • Existing tokens and sign-in connections are kept, not revoked.
To turn MCP back on, turn the same switch on. No confirmation is needed. Existing tokens and sign-in connections work again within a few seconds, and connected clients do not need to be reconfigured. To read the setting through the Heymarket API, call Get team. mcp_disabled is true when a team owner or admin has turned MCP off, and mcp_disabled_by_heymarket is true when Heymarket has. MCP is off when either field is true. Neither field shows an expired subscription, a suspended team, or whether a member’s role includes MCP Access.
Heymarket can also turn MCP off for a team, for example, at your request. While it is off, the team’s MCP switch shows Off and is locked, with the tooltip “MCP was disabled for this team by Heymarket. Contact Heymarket support to turn it back on.” Team owners and admins cannot turn MCP on while the switch is locked. MCP requests return 403 Forbidden with the code mcp_disabled_by_heymarket. When Heymarket lifts the lock, the switch returns to your team’s own setting. If a team owner or admin had turned MCP off before, it stays off until they turn it on.

Sign in with Heymarket

When you add Heymarket to Claude, Claude Code, ChatGPT, or Codex without a token, the app asks you to sign in to Heymarket. The steps for each app are in Connect with sign-in. The Heymarket part of the flow is the same for every app:
1

Open the Heymarket sign-in page

The app opens a Heymarket page in your browser titled Connect an AI app to Heymarket. If you are not signed in to Heymarket, you see the usual Heymarket login first, with the note “You’re signing in to connect an AI app. Finish within” and the time left. Sign in the way you usually do. After you sign in, you return to the connect page.
2

Choose a team

Under Choose the team this app can access, select one team. Teams you cannot connect are disabled, with the reason next to them. See A team is missing or cannot be selected when you sign in under Troubleshooting.The page shows the account you are signed in as. To use another Heymarket account, click Use a different account. This signs you out of Heymarket in that browser and returns you to the login page.
3

Click Continue

Click Continue before the Time left timer runs out. You have 4 minutes from when the app opened the page. If the time runs out, go back to the app and start connecting again. To stop, click Cancel.
4

Allow access

A consent screen shows the app’s name, the access it asks for, the Heymarket team you chose, and the account you are signed in with. Click Allow access. This screen appears every time you connect an app. Your browser then returns to the app, which can now use the Heymarket tools.
The page says “Only continue if you just started connecting an AI app, such as Claude or ChatGPT, to Heymarket.” If you did not start a connection yourself, click Cancel. Anyone who completes this page can give their AI app access to the team they choose.
The Heymarket sign-in page works only in a desktop browser. On a phone, Heymarket shows a prompt to install the Heymarket mobile app instead of the team list. Start the connection from a computer.
After you connect, the app keeps its access up to date by itself. You do not sign in again unless the connection ends. See What ends a connection.

One team per connection

A sign-in connection works with one Heymarket team, the one you chose on the sign-in page. Every tool reads and writes only that team, using your role and inbox access there. The app cannot switch teams by itself.
  • Check the team. Ask the app “Which Heymarket team am I connected to?”. It answers with the whoami tool.
  • Switch teams. Connect the app again and choose the other team. This moves that app’s connections, on every device where you use it with this Heymarket account, to the new team. The sign-in page warns you before you continue. Your other AI apps stay on their own teams.
  • Use several teams at once. Create a personal access token for each team and add a separate server entry for each one. See Connect with a personal access token.

Create a Personal Access Token

You create a PAT from your profile in the Heymarket app. You can create one for any team where MCP is on and your role includes MCP Access.
1

Open your profile

Log in to Heymarket, click your avatar in the bottom-left to open the account dropdown, and select Profile.
2

Scroll to Personal Access Tokens

On your profile page, scroll down past About and Two-Factor Authentication to the Personal Access Tokens section. Any existing tokens are listed here with their name, team, masked token value, creation date, and last-used timestamp.
3

Click Generate token

Click the Generate token button in the top-right of that section.
4

Fill in the token details

In the Generate personal access token modal:
  • Token name - enter something descriptive, such as Claude Desktop on laptop, so you recognize its purpose later.
  • Team - select the team the token should be scoped to. Each token is tied to exactly one team. Teams you already hold a token for are disabled in the dropdown, because you can only hold one active token per team. Other teams you cannot create a token for are also disabled and labeled with the reason. See Creating a token is blocked under Troubleshooting.
5

Generate and copy the token

Click Generate token. A Token created confirmation appears showing the token name, team, and the full token value starting with hm_pat_. Click Copy right away — the full value is not shown again after you close the dialog.
6

Store it and close

Paste the token somewhere secure — a password manager, or directly into the HEYMARKET_PAT value of your MCP client configuration (covered in Connect with a personal access token) — then click Done.
The full token is shown only when you create it. Heymarket stores it hashed and cannot show it again. Store it only in your MCP client configuration, and treat it like a password.

Token scope and limits

  • One team per token. A PAT grants access to the single team it was created in, using your role and inbox access in that team.
  • MCP Access required. Your role in the token’s team must include MCP Access, both when you create the token and on every request it makes. See Who can use MCP.
  • MCP on for the team. The token works only while MCP is on for its team. See Who can use MCP.
  • Tools follow your role. A token acts at your role. Most tools require a Member, Admin, or Owner role, and some require Admin or Owner. See Available tools.
  • One active token per team member. Each member can hold one active PAT per team. To replace a token, revoke the old one first, then create a new one.
  • No expiry. A PAT stays valid until it is revoked. You can revoke it from the Personal Access Tokens section of your profile if a device is lost or a team member leaves. Heymarket also revokes it when you leave the team, when your password is reset, and when your account is disabled. Revocation takes effect on the next request.

Connect a client

Connect Claude, Claude Code, ChatGPT, or Codex by signing in. Connect other clients, such as Cursor, with a personal access token. See Choose how to connect.

Connect with sign-in

Sign-in works only with Claude, Claude Code, ChatGPT, and Codex. Do not add an Authorization header or a token when you add the server. In some apps, a configured header turns sign-in off.
These steps work in Claude on the web and in the Claude desktop app. Once Heymarket is connected, it also works in the Claude mobile apps.Free, Pro, and Max plans
1

Open Connectors

In Claude, open Customize > Connectors. Click + Add, then Add custom connector.
2

Enter the server details

Enter a name, such as Heymarket, and https://mcp.heymarket.com/mcp as the server URL. Click Continue, review the authentication settings Claude detects, and click Continue again.
3

Choose how to sign in

Under Authentication, choose Sign in now. Under OAuth client, choose Use Claude’s published identity (Recommended). Leave Request headers empty. Click Add.
4

Sign in to Heymarket

If Claude does not open the Heymarket sign-in page by itself, click Connect next to Heymarket. Sign in to Heymarket, choose your team, and allow access. See Sign in with Heymarket.
5

Use it in a chat

In a chat, click + in the lower left, choose Connectors, and turn Heymarket on for that conversation.
Free plans allow one custom connector.Team and Enterprise plansAn organization Owner adds Heymarket once for the organization. On Team plans, Owners and Primary Owners can add it. On Enterprise plans, so can members whose custom role includes managing access to libraries. Each member then connects it with their own Heymarket account and team.
1

Add Heymarket for the organization (Owner)

Open Organization settings > Connectors and click Add. Hover over Custom and select Web. Enter a name and https://mcp.heymarket.com/mcp, click Continue, review the authentication settings, and click Continue again. Under OAuth client, choose Use Claude’s published identity (Recommended), leave Request headers empty, and click Add.
2

Connect (each member)

Open Customize > Connectors, find Heymarket (it usually has a Custom label), and click Connect. Sign in to Heymarket and choose your team.
To change a connector’s settings, remove it and add it again.From the Claude directoryOnce Heymarket is listed in the Claude directory, open Customize > Connectors, click + next to Connectors, and find Heymarket. Open it and click Connect, then sign in to Heymarket. On Team and Enterprise plans, an Owner adds it under Organization settings > Connectors with Browse connectors and Add to your team. A member who cannot add it selects Request on its page in the directory.

Connect with a personal access token

Add the Heymarket server to your client’s MCP configuration, then restart the client. Replace hm_pat_REPLACE_WITH_YOUR_TOKEN with the token you created. See Create a Personal Access Token. Clients that run the mcp-remote bridge need Node.js 18 or later so they can invoke npx.
Claude Desktop can also connect by signing in, with no configuration file. See the Claude tab under Connect with sign-in. To use a token instead, open your claude_desktop_config.json file:Add the heymarket server, then fully quit and reopen Claude Desktop:
Keep the token in env rather than inline in args so it does not appear in process listings. After restarting, open a new chat and look for the tools indicator listing the Heymarket tools.

Example prompts

Try these once your app is connected. Replace the inbox names, contact details, list names, teammates, and links with your own. Each prompt works with sign-in and with a personal access token. Many AI apps ask you to approve a tool that changes data before it runs. Heymarket marks the tools whose changes cannot be undone, such as sending a message, so your app can warn you. If you set a tool to always allow, the app runs it without asking. See the note under Available tools.

Manage connected apps

Each sign-in creates a connection that you, and your team’s admins, can see and end in Heymarket.

Your connected apps

1

Open your profile

Log in to Heymarket, click your avatar in the bottom-left, and select Profile.
2

Find Connected AI apps

Scroll to Connected AI apps, below Personal Access Tokens. Your connections are grouped by app. Each row shows the Team, the Status (for example “Last used” with a time, or “Not used yet”), and the date in Connected on.
3

Disconnect an app

Click Disconnect on the row, then click Disconnect in the dialog to confirm. For a sign-in no app has used yet, the dialog button is Remove. The dialog lists any other connections that end with it. A message confirms that the app is disconnected. It can take a minute for the app to sign out, so wait before you connect it again.
  • Disconnect ends the app everywhere. Disconnecting an app ends its access on every device where it uses that sign-in, and on every Heymarket team it reaches with it.
  • Sign-ins no app has used yet are grouped under Waiting for first use. Heymarket removes a sign-in that goes unused for 24 hours.
  • The card shows when you have a connection, or when sign-in is available and your role includes MCP Access on at least one team.
  • Disconnect in Heymarket. Removing or disconnecting Heymarket inside your AI app does not always end the connection in Heymarket. To be sure an app no longer has access, disconnect it here.
You can disconnect only your own connections on your profile. Personal access tokens are listed separately, under Personal Access Tokens.

Connected apps on your team

Team owners and admins, including members with a custom role duplicated from Admin, can see and end the apps members have connected to the team.
  1. In Heymarket, click the Administration icon in the left sidebar, then select the Team tab.
  2. Scroll to Connected AI Apps, at the end of the tab. Each row shows the Member, the Status, and the date in Connected on. The section appears once a member has connected an app or sign-in is available for the team.
  3. Click Disconnect to end that member’s access through the app, then confirm.
If the member also uses the same app on another Heymarket team with this sign-in, the dialog warns you that disconnecting it here disconnects it there too. To stop every connected app at once, turn MCP off for the team. To stop it for everyone in a role, turn off MCP Access on that role. Both keep the connections and tokens, which work again when you turn access back on. See Who can use MCP.

What ends a connection

These end your sign-in connections automatically: Signing out of Heymarket, or signing out of other devices, does not end a connection. These pause a connection without ending it: MCP turned off for the team, your role losing MCP Access, an expired subscription, or a suspended team. The app gets an error until the cause is fixed, then works again without reconnecting.

Reconnect an app

When a connection ends, the app’s Heymarket tools stop working until you connect it again. No app reconnects by itself.

Available tools

The server advertises 47 tools. Your client discovers them automatically after it connects. Every tool requires a Member, Admin, or Owner role. delete_contact, delete_list, and approve_broadcast require Admin or Owner. A custom role counts as the role it was duplicated from, and a role created with the Create button on the Roles tab counts as Member. Clients load the tool list when they connect, so they do not see tools Heymarket adds later until they reconnect. In Claude, disconnect the Heymarket connection and connect it again. In other clients, fully quit and reopen the client.

Tools that need a personal access token

Apps connected by signing in get every tool except these ten. They are not listed on a sign-in connection, and a call to one of them fails with an error that the tool “is not available on this connection”. Sign-in connections also do not get the two prompts, launch_campaign and review_pending_broadcast. Asking for one fails with an error that the prompt “is not available on this connection”. So an app connected by signing in cannot draft, view, send, or cancel broadcasts, and cannot upload a file from your machine. It can still send a picture or file with send_message and a public link. See Send a file that is already online. To use these tools and prompts, connect with a personal access token. See Connect with a personal access token. You can also delete contacts and lists, transfer conversations, run broadcasts, and attach files in the Heymarket app.

Inboxes

Conversations

Your conversation state

These tools change a conversation for you only. Your teammates’ notifications, snoozes, and unread state are unaffected.

Messages

Contacts

Lists

Templates and team members

Broadcasts

Every broadcast tool needs a personal access token. Apps connected by signing in do not get them. See How broadcasts stay supervised.
Heymarket tells your AI app which tools only read data, which change it, and which make changes that cannot be undone, such as sending a message or deleting a contact. Many MCP clients use this to decide when to ask you before a tool runs. Most ask before a tool that sends a message or changes a contact, list, or conversation, unless you allow that tool for the session or always.

Send pictures and files

send_message sends a picture or file as an MMS when you pass media_url. Text is optional when you send media. You cannot combine media_url with template_id, so send the attachment as a separate message.

Send a file that is already online

The carrier downloads the file from media_url when it sends the message, so the link must be:
  • Direct and public. An https link to the file itself that anyone can download without signing in. http, data:, file:, and relative URLs are refused, and so are URLs that contain a username or password.
  • A media file. The URL’s path must end in the file’s extension, such as .jpg, .png, .gif, .mp4, .mp3, .pdf, or .vcf. A query string after the extension is fine. Images (except SVG), video, audio, PDF, and vCard files are accepted. Share pages and links without a file extension are refused, even when they show the picture in a browser.
  • On a public host. Hosts that are not found in DNS are refused, and so are local, private, and internal addresses.
  • At most 2,048 bytes long.
Hosted chat apps, such as claude.ai and ChatGPT, cannot pass a file you attach in the chat to an MCP tool, and apps connected by signing in cannot upload files. To send a picture or file from one of them, give it a public link to the file.

Send a file from your machine

Clients connected with a personal access token that can also make HTTP requests, such as Claude Code, n8n, or your own scripts, can upload a local file with create_attachment_upload and then send it. Apps connected by signing in do not get create_attachment_upload, so they send files from a public link only.
1

Request an upload URL

Call create_attachment_upload with the file’s content_type and its exact size in bytes as size_bytes. You can also pass filename. Only its extension is used, to check that it matches content_type.The response contains upload_url, the upload_headers to send with the upload, the media_url to send the file with, expires_at, and max_bytes for that type.
2

Upload the file

Send the raw file in an HTTP PUT to upload_url, with every header in upload_headers set to exactly the returned value. For example:
curl sets Content-Length from the file, and it must equal size_bytes. The upload URL expires after 15 minutes and accepts a single upload of exactly the declared type and size. A 412 Precondition Failed response means the file is already uploaded.
3

Send the message

After the upload returns 200 OK, call send_message with media_url set to the returned media_url. If you send before the upload finishes, the recipient gets a broken attachment.
create_attachment_upload accepts these types: Resize larger images before you upload them. Once a file is uploaded, anyone with its media_url can download it.

Add private comments

add_private_comment adds a private comment, an internal note, to a conversation. Only your teammates see it. It is never sent to the contact.
  • Choose the conversation with conversation_id, or with phone_number to use the contact’s existing conversation in inbox_id. Give exactly one of them. The tool never starts a conversation: a phone number with no conversation in the inbox is an error.
  • Mention teammates by passing their user IDs from list_users in mention_user_ids, up to 20 per comment. Each one must be a member of the inbox, directly or through a group. Mentioned teammates are notified.
  • Inbox membership. You must be a member of the inbox.
  • Length. Comment text can be up to 2,000 characters.
A comment added through MCP sends the private_comment_created webhook event, the same as a private comment added in the app or through the API. Only webhooks with Include private comments turned on receive it. See Webhook Event.

How MCP messages are labeled

Messages and private comments created through MCP show in the Heymarket app as written by your name via MCP, or Sent via MCP if your profile has no name. API responses and webhook payloads carry the same label in the message’s author field. Messages sent to email conversations do not carry the label.

How broadcasts stay supervised

Every broadcast sent through MCP requires human approval — an AI agent cannot mass-message on its own. The flow has three gates:
1

Draft

create_broadcast creates a draft and sends nothing. It returns the recipient count with opted-out contacts already filtered, sample recipients, and a preview of the message so a person can review what would go out.
2

Confirm the count

send_broadcast requires expected_recipient_count to match the count shown on the draft. If the live count has changed — for example, contacts opted out since drafting — the call is rejected with the new count, forcing a fresh review. On success the broadcast moves to pending approval; still nothing sends.
3

Human approval

A team admin or owner approves the pending broadcast with approve_broadcast (or rejects it with cancel_broadcast, which returns it to draft). Only after approval does the broadcast send.
Retries are safe throughout: create_broadcast and create_list accept an optional idempotency_key, and resubmitting or re-approving an already-processed broadcast returns success with idempotent_replay: true instead of acting twice. Broadcasts through MCP need a personal access token. An app connected by signing in gets none of the broadcast tools, so it cannot draft, view, submit, approve, or cancel a broadcast. Run broadcasts in the Heymarket app, or connect with a personal access token.

Prompts

On a personal access token connection, the server also publishes two MCP prompts — guided workflows your client can offer alongside the tools:
  • launch_campaign - walks the client through building an audience, composing a message, creating a draft broadcast, reviewing the filtered recipient count with you, and submitting it for approval
  • review_pending_broadcast - renders a pre-send review of a broadcast awaiting approval: recipients, message, and the exact approval step. Run it before approving.
Both prompts drive the broadcast tools, so apps connected by signing in do not get them. They are not listed on a sign-in connection, and asking for one fails with an error that the prompt “is not available on this connection”.

Rate limits

The server limits how often you can call it.
  • Tool calls. Each token, and each sign-in connection, can make about 180 tool calls a minute. All of a team’s tokens and sign-in connections together can make about 600 a minute. Only tool calls count: connecting and listing tools do not. When you reach either limit, the tool call fails with an error that names the limit and says how long to wait, for example Rate limited: this access token is limited to 180 requests per minute. Retry in 23 seconds. Fetch items one at a time rather than in parallel. Your AI client passes this error to the model, so it can wait and try again. Calls refused this way do not count against the limit.
  • Invalid tokens (401 Unauthorized). After about 30 failed attempts in a minute from the same IP address or with the same token, requests return HTTP 429 Too Many Requests with a Retry-After: 60 header. Fix or replace the token before you retry. An expired sign-in token that your app refreshes does not count.
  • Refused valid tokens (403 Forbidden). After about 30 refusals in a minute for the same token or sign-in connection, requests return 429 with a Retry-After: 60 header. Fix the cause named by the code. Do not replace the token. These refusals do not count against your other tokens.
The Heymarket sign-in page and the Connected AI apps lists have their own limits per account. Over a limit, they show “Too many attempts. Try again in” and the number of seconds to wait.

Data and privacy

The AI model runs in your AI app, not in Heymarket. Heymarket answers only the tool calls the app makes, with the access of the Heymarket user and team the connection is for.

What your AI app sends to Heymarket

  • Tool calls. For each call, the tool’s name and the inputs the app fills in, such as the text of a message to send, a search term, or a contact’s name and phone number. Heymarket does not receive the rest of your chat.
  • The app’s name and version, and the IP address the request comes from.
  • Credentials. With sign-in, an access token that your app gets and refreshes on its own. Heymarket checks it on each request and does not store it. With a personal access token, Heymarket stores only a hash of the token.

What Heymarket returns

  • Data from one team only, limited by your role and by the inboxes you are a member of. Depending on the tool, that includes contact details (names, phone numbers, email addresses, custom fields, tags, and notes), message text and history, conversation details, lists, templates, broadcasts, and teammates’ names and roles. The team member list does not include teammates’ email addresses.
  • What the app does with it is up to the app. Data that Heymarket returns becomes part of your chat. Your AI provider handles it under its own terms and your settings with that provider.
Message text, contact details, and notes are written by your customers and teammates, and can contain instructions aimed at an AI. Check what the app plans to do before you approve a send or a change.

What Heymarket records

  • Your data changes like it does in the app. A message sent, a contact created, or a conversation closed through MCP is saved in Heymarket the same way as in the Heymarket app. Messages and private comments are labeled as written via MCP.
  • A record of each tool call, for security and support: the tool, the time, your user and team, the app’s name, the IP address, whether the call succeeded, and the IDs and options it used. The record leaves out message text, phone numbers, email addresses, contact details, search terms, and file names. A name you type into a tool, such as a list name, is recorded only as a fingerprint, not as text.
  • A record of each sign-in connection: when it was created, last used, and ended, and why it ended.
  • Service logs hold IDs and error codes, not message content. Heymarket keeps them for 30 days.

Who else receives data

Sign-in runs through WorkOS, which Heymarket uses to issue sign-in tokens to AI apps. When you connect an app, WorkOS receives your Heymarket user ID, your name, your email address, and the name of the team you chose.

Stop sharing data

  • Disconnect an app under Profile > Connected AI apps. See Manage connected apps.
  • Revoke a personal access token under Profile > Personal Access Tokens.
  • Team owners and admins can disconnect members’ apps on the Team tab, or turn MCP off for the whole team. See Turn MCP on or off for your team.
For how Heymarket collects, uses, and protects personal data, read the Heymarket Privacy Policy.

Security best practices

  • Prefer sign-in for Claude, Claude Code, ChatGPT, and Codex. You never copy or store a token yourself, and you can see and end each app’s access under Profile > Connected AI apps.
  • Check Connected AI apps from time to time, and disconnect apps you no longer use. Disconnect in Heymarket, not only in the AI app.
  • Store the token only in your MCP client configuration. Do not commit it to source control or paste it into shared documents.
  • A PAT acts as your account’s access for the team it was created in, at your role. Anyone with the token can act as you in that team.
  • Revoke a token immediately from the Personal Access Tokens section of your profile when a device is lost, a team member leaves, or you suspect the token leaked. Revocation takes effect on the next request.
  • Rotate a token by revoking the old one and creating a new one. There is no separate refresh step.
  • To cut off MCP for everyone in a role at once, turn off MCP Access on that role. Their tokens and sign-in connections stop working within a few seconds.
  • To cut off MCP for the whole team at once, turn off the team’s MCP switch. See Turn MCP on or off for your team. Tokens and sign-in connections are kept and work again when you turn MCP back on. Before you turn it back on, ask the owner of any token that may have leaked to revoke it from the Personal Access Tokens section of their profile, and disconnect any app you do not recognize under Connected AI Apps.

Troubleshooting

Confirm the configuration file is valid JSON and points to https://mcp.heymarket.com/mcp. Most clients read MCP configuration only at startup, so fully quit and reopen the client after editing it. In Claude Desktop, check Settings > Developer for MCP server startup errors.If the client shows Heymarket tools but not the newest ones, it is still using the tool list from when it connected. In Claude, disconnect the Heymarket connection and connect it again. In other clients, fully quit and reopen the client.If you connected by signing in, ten tools and both prompts are not listed, including every broadcast tool and create_attachment_upload. See Tools that need a personal access token.
The sign-in page lists every team you belong to. If a team is missing, you may be signed in with another Heymarket account. Click Use a different account. If you belong to more than 200 teams, the page says “Only your first 200 teams are listed.”A team you cannot connect is disabled, with one of these reasons next to it:If a team’s access changes after the page loads, clicking Continue shows the reason above the team list, after the team’s name, and the list reloads. The same reasons can appear there, and so can “You’re no longer a member of this team.” In that case, ask a team admin to add you back, or choose another team.If no team can be connected, the page says “None of your teams can connect an AI app right now.” If you belong to no team, it says “You aren’t a member of any Heymarket team, so there is nothing to connect.”
Most of these mean the request ended. Go back to the app you were connecting and start again, for example by clicking Connect again.
  • “This request expired. Go back to the app you were connecting and click Connect again.” - more than 4 minutes passed. Start again and finish within the time shown.
  • “This link isn’t valid or has expired.” or “This request was already used.” - start again from the app.
  • The app shows an error after you click Continue - sign-in took too long. Start again.
  • “Add a valid email address to your Heymarket profile, then try again.” - add an email address under Profile, then start again.
  • “Another connection is in progress. Try again.” - wait a moment and try again. If it keeps happening, you may have 10 recent sign-ins to this team that no app has used yet. Remove them under Waiting for first use in Profile > Connected AI apps, then try again.
  • “Too many attempts. Try again in” followed by a number of seconds, or “in a moment” - wait that long.
  • “This AI app isn’t supported.” - the app could not finish signing in to Heymarket. Sign-in works only with Claude, Claude Code, ChatGPT, and Codex. For other apps, use a personal access token.
  • “Connecting AI apps isn’t available right now.” - sign-in is turned off. Use a personal access token, or try again later.
  • “Your Heymarket account can’t connect AI apps. Contact Heymarket support.” - contact Heymarket support.
  • “Your account can’t be linked right now. Contact support.” - contact Heymarket support.
  • “This page can’t use your Heymarket sign-in here. Open Heymarket at its usual address and try again.” - open app.heymarket.com, then start again from the app.
  • “For your security, this page can’t be opened inside another website.” - start again, and let the app open the page in its own browser tab.
  • A prompt to install the Heymarket mobile app - the sign-in page works only in a desktop browser. Start the connection from a computer.
When Heymarket refuses a request from an app connected by signing in, it sends one of the messages below with the refusal. Some apps show it. Others show only a general error, or a prompt to connect again. No app reconnects by itself. Messages that start with “Reconnect”, for example “Reconnect Claude to Heymarket”, mean the connection ended. See What ends a connection, then reconnect the app.
  • “You are no longer a member of team” followed by the team name - you were removed from the team. Reconnect and choose another team.
  • “Connection replaced by a newer one; refresh and retry” - you connected the same app again, perhaps to another team. Retry, and reconnect if it continues. See One team per connection.
  • “Access token expired; refresh and retry” - the app normally refreshes by itself. If it continues, reconnect.
  • A message that the app cannot connect to Heymarket - sign-in works only with Claude, Claude Code, ChatGPT, and Codex. Use a personal access token.
  • “Your Heymarket account cannot use AI apps; contact Heymarket support” - contact Heymarket support. Once your account is restored, reconnect the app.
  • “Heymarket is temporarily unavailable; retry shortly” - wait a moment and retry.
These messages do not need a reconnect. The connection works again once the cause is fixed:
  • “A team admin has turned off MCP for team” followed by the team name
  • “Heymarket has turned off MCP for team” followed by the team name, then “contact Heymarket support”
  • “The subscription for team” followed by the team name, then “has expired; renew it to use MCP”
  • “Team” followed by the team name, then “is suspended; contact Heymarket support”
  • “Your role on team” followed by the team name, then “does not include MCP access” or “cannot use MCP”
For what to do about each one, see A team is missing or cannot be selected when you sign in.
Ask the app “Which Heymarket team am I connected to?”. To change it, connect the app again and choose the right team. This moves that app’s connections, on every device where you use it with this Heymarket account, to the new team. Your other AI apps are not affected.To work with two teams at once, use a personal access token for the second team. See One team per connection.
It can take a minute for an app to sign out after you click Disconnect. Wait a minute before you connect it again. If it still works after that, check Profile > Connected AI apps and the Personal Access Tokens list: the app may use a token or another sign-in.
The token is missing, malformed, or revoked. Confirm the Authorization header is Bearer hm_pat_... with no extra spaces or line breaks, and that the token has not been revoked. If you are unsure, create a new token and update your client configuration.Requests also return 401 Unauthorized if you are no longer a member of the token’s team, or if the team is suspended. You cannot create a new token for a suspended team. Contact Heymarket support.For apps connected by signing in, see Your AI app asks you to reconnect Heymarket.
The token is valid, but the server refused it for its team. The JSON response body says why:
Match on code. The error text is for people and may change. The code is one of:
  • mcp_team_expired - the team’s subscription has expired. Ask whoever manages billing for your team to renew it.
  • mcp_disabled_by_heymarket - Heymarket has turned MCP off for the team. Contact Heymarket support.
  • mcp_disabled_by_admin - a team owner or admin has turned MCP off for the team. Ask them to turn it back on (see Turn MCP on or off for your team).
  • mcp_permission_required - your role in that team does not include MCP Access. Ask a team admin to grant it (see Grant MCP access to a role).
When more than one applies, the server reports the first one in this list. You do not need a new token: your existing one works again once the cause is fixed. Until then, stop retrying with it. Repeated refusals are throttled, as described in Rate limits.For apps connected by signing in, Heymarket sends the refusal as a message that names the team. See Your AI app asks you to reconnect Heymarket.
The server is throttling repeated refusals. Check which response you got before the 429:
  • 401 Unauthorized - the token is bad or revoked. Fix or replace it.
  • 403 Forbidden - the token is valid but was refused. Fix the cause given by its code.
Wait for the Retry-After period, 60 seconds, before trying again. Too many tool calls from a valid token do not return 429; the tool call fails with a “Rate limited” error instead. See Rate limits.
You can create a Personal Access Token for a team only when MCP is on for that team and your role there includes MCP Access. In the Team dropdown of the Generate personal access token modal, each team you cannot create a token for is disabled and labeled with the reason. Your profile can also show a message about it.
  • subscription expired, or “This team’s subscription has expired. Renew it to use MCP.” - ask whoever manages billing for your team to renew it.
  • MCP disabled by Heymarket, or “MCP has been disabled for this team by Heymarket. Contact Heymarket support.” - contact Heymarket support.
  • MCP turned off by a team admin, or “A team admin has turned off MCP for this team.” - ask a team owner or admin to turn MCP back on.
  • ask a team admin for MCP access, or “MCP access isn’t enabled for your role yet.” or “Ask a team admin to enable MCP access for your role.” - ask a team admin to grant MCP Access to your role (see Grant MCP access to a role).
  • team suspended - no one can use MCP or create tokens for a suspended team. Contact Heymarket support.
Each member can also hold only one active token per team. If you already have one for that team, revoke it before creating a new one.
Only members whose role is the Owner or Admin system role see the MCP Access section on the Team tab. Custom roles do not see it, even roles duplicated from Admin. Ask a team owner or admin to change the setting for you.