Connect your own AI (MCP keys)

A workspace set up with a personal email address cannot create API keys or connect an AI app until its business is verified (see "Verifying your business").

You can connect your own AI assistant to HuntSales with an API key and have it work with your CRM: read your contacts, pipeline, campaigns and call statistics, add prospects, move contacts through your pipeline, build lists, build and launch campaigns, and read and change your companies, deals, tasks, notes and Suppression List. This is separate from the built-in Copilot: here you bring your own AI and point it at HuntSales over MCP (Model Context Protocol). Full setup steps for each client are at /docs/mcp.

Which AI apps can connect: MCP clients that send your API key as a header. We have tested Claude Code and Claude Desktop on Mac end to end (Claude Desktop connects through the small mcp-remote bridge, which needs Node.js; we tested it with the key written directly in the header argument). The setup guide's Claude Desktop config puts the key in an env setting instead, the form the mcp-remote documentation gives for Windows; that config, the configs for Cursor and VS Code, and an example for your own agent on the OpenAI Responses API follow each vendor's documentation and are not yet tested by us. Other apps that let you add a remote MCP server with your key in a header can connect the same way, such as n8n's MCP Client Tool, Gemini CLI and your own agent on the Claude API; they follow each maker's documentation and are not yet tested by us. claude.ai, the Claude mobile app and ChatGPT connect by OAuth sign-in instead of a key: add a custom connector with the URL https://huntsales.io/api/mcp (exactly, no trailing slash), sign in to HuntSales when the app asks, and choose what it may do. Reading is always included; adding prospects (which uses credits) is ticked by default and can be unticked; launching campaigns, which sends real email, stays off unless you tick it. Only what your role allows is offered, every call still follows your role, which needs API Keys & MCP as a key does, and the app's contact reads count toward your daily read limit. A connection lasts up to 90 days, then you sign in again. To see or disconnect a connected app, open Admin, then Developer, Connected apps; to change what an app may do, disconnect it and connect again. In a managed workspace only the Super Admin can connect an app. We have not yet tested these sign-ins end to end ourselves.

How to connect: open Admin, then Developer, and create an API key. Any member whose role includes the "API Keys & MCP" permission can do this; the page is not admin-only. Turning that permission off for a role stops its members' existing keys at their next use. Give the key a name and leave "Allow this key to launch campaigns" unticked unless the key needs to send email: a new key cannot launch or resume a campaign, or add contacts to or change a live one, unless that box was ticked when it was made (keys made before 12 October 2026 keep what they had). Copy the key (it is shown once), and add it to your AI client as the setup guide shows: as Authorization: Bearer followed by the key, or in an X-API-Key header for a client that cannot add Bearer. You can revoke your own keys any time from the same page. Each key may make 120 requests a minute over MCP, and separately 120 a minute to the REST API; past that the answer is 429, with a Retry-After header giving the seconds to wait.

Keys are personal and follow your role. A key you create can never do more than YOUR role allows: every call re-checks your CURRENT role permissions, and your AI only sees the tools your role permits. If an admin changes your role, all your keys follow immediately; if a member is removed from the team, their keys stop working entirely. A member's key also acts only on what that member could touch in the app: their own campaigns, the lists they created or that are shared with them, and, when the workspace limits prospects to their assignee and the role lacks View All Contacts, only the contacts assigned or co-assigned to them plus unassigned ones. What your AI creates (contacts, lists and campaigns) is saved as yours, so it shows up for you in the app. Admins (superadmins) see every key in the workspace under Developer with its owner, and can revoke any of them. A superadmin's own keys can use every tool. API keys are not available in a workspace managed by HuntSales, except a superadmin's own.

Workspace keys: for an integration that must keep working when staff change (a nightly sync, an n8n or Make scenario), a Super Admin can create a workspace key under Admin, then Developer, Workspace keys. It belongs to the workspace, not a person, so it keeps working if the person who created it leaves, and it is bound to a role the Super Admin picks (never the Super Admin role): every call is capped by that role's current permissions (apart from API Keys & MCP, which a workspace key ignores, since a Super Admin made it), and it acts as a member of that role who owns nothing, so in a workspace that keeps prospects to their assignee it sees only unassigned contacts unless the role has View All Contacts. It can read and change contacts, companies, deals, notes and the Suppression List as the role allows (its Suppression List adds go to the Super Admin for approval); it cannot search for or add prospects, build lists or campaigns, send email, work on tasks or manage webhooks, because those belong to a member. Every Super Admin sees and can revoke every workspace key, and creating or revoking one is recorded in the activity log; creating one also emails every Super Admin. All of a workspace's workspace keys share ONE daily read limit, the same size as one member's, so making more keys never reads more; under API reads today they show as one line, Workspace keys (shared).

Older keys: a key the Developer page marks as a legacy key was made for the whole workspace before keys became personal and held every permission. It no longer works (since 12 October 2026): revoke it, and create a workspace key bound to a role if an integration still needs one.

What your role needs: your key reaches what your role reaches in the app, page by page. Listing contacts needs View All Contacts or View Assigned Contacts, as the Contacts page does, and if your role lacks View All Contacts in a workspace that limits prospects to their assignee, your key reads only the contacts assigned or co-assigned to you plus unassigned ones, following the same visibility as search in the app. A contact search returns one page a call, 20 by default and up to 50, and no tool pages through your whole workspace; downloading contacts as a file stays with Export Contacts in the app. Contacts read through the API, MCP and connected AI apps also count toward a daily limit for each member, set by the plan: Free 200, Scout 1,000, Hunter 5,000 and Apex 20,000 contacts a day. It resets at midnight Singapore time; past it, a contact read is refused with the time it resets, and if a call reaches the limit partway it returns only what is left, with a note. Reading contacts in the app and the built-in Copilot are not limited. All of a workspace's workspace keys share one limit of the same size between them. A Super Admin sees how many contacts each member, and the workspace keys together, have read through the API today under Admin, then Developer, API reads today. Pipeline counts follow the Dashboard: the whole workspace with View All Contacts, otherwise your own contacts and the ones shared with you. Reading campaigns and their engagement needs Campaigns & Email Setup or View All Campaigns, or a campaign shared with you, as the Campaigns page does. Your contact lists, connected mailboxes and credit balances work for every member's key. Mailbox reads cover the address, provider, status, and daily limit only; credentials are never exposed. Reading call statistics (calls, answered calls, talk time, outcomes and appointments set for any period) follows the Call Log: a key whose owner has See all calls reads the whole team, one with the Calling permission reads only the owner's own calls, and one with neither is refused. Counting prospects not yet in your CRM works for every member's key and is free, as in the app. The count covers the people in our shared contact database, which is part of the market, not all of it. Adding them needs Add Prospects, and each add spends 2 People Search credits when the contact comes with an email, nothing when it does not. Creating contacts needs Edit Contacts, moving a contact's stage needs Manage Leads, and creating lists or adding contacts to them needs Manage Lists, as in the app. Building, enrolling, and launching campaigns needs Campaigns & Email Setup; launching or resuming a campaign, and adding contacts to or changing a live one, also need a key made with "Allow this key to launch campaigns" ticked. Companies, deals, tasks, notes and the Suppression List follow their pages in the app, over MCP and the REST API alike. Listing companies needs View All Contacts, as the Companies page does; one company opens as its panel does, so in a workspace that keeps prospects to their assignee another member's company shows only its name and owner unless you hold people there. Every member reads, logs, changes and deletes their own deals, and every deal with View All Deals; a deal's contact must be one you may work. Your tasks are the ones you created, are assigned or watch (a Super Admin's too); creating, editing and deleting them needs Tasks, except that you may move a task assigned to you through its statuses without it, as My Day allows. Notes are read and added on any contact you can open, with no permission of their own. A task's contact must be one you may work. Over the API these two are deliberately stricter than the app: the API never reads or changes anything on a contact you cannot open yourself. The Suppression List needs Campaigns & Email Setup to read or change; only a Super Admin's key adds to it directly, and anyone else's add goes to the Super Admin for approval on Edit Requests, marked as from the API; only a Super Admin's key removes an entry that makes someone Do Not Call. Deleting a deal or a task, and adding to or removing from the Suppression List, preview first and wait for confirm:true. Managing webhook endpoints over the REST API follows the app, where only a superadmin manages webhooks: only a Super Admin's key manages them, and any other key is refused. Over the REST API, searching prospects and revealing their work emails needs People Search, and reveals spend People Search credits.

Safety model: the tools that add prospects, spend credits, or start real sending run a dry-run preview first and then wait for your explicit confirm before doing anything: adding prospects, creating a list from a filter, enrolling a list, launching a campaign, enrolling contacts into a live (active or scheduled) campaign, resuming a paused campaign, and editing a live campaign's steps. Creating a contact, a list or a draft campaign, adding contacts to a list, and editing a draft or paused campaign apply straight away because none of them sends anything. Per-call caps apply: adding prospects (claim_prospects) is capped at 500 per call, and enrolling contacts by id or from a list (enroll_contacts) or adding contacts to a list (add_contacts_to_list) at 2,000 per call; when enroll_contacts stops at 2,000 it says so, and your AI calls again with the rest. Enrolling a whole list (enroll_list) has no per-call cap: it enrols every eligible member once you confirm its preview. Launching checks the campaign has at least one step, a sending mailbox, and enrolled contacts, then only flips it live; mailbox daily limits, warmup (if you have switched it on), the Free plan's send caps and your send window still pace the actual sending exactly as they do in the app. Connecting a mailbox stays a manual step you do in Email Setup; the AI can list your connected mailboxes but never sees their credentials. Writes fire your automations and webhooks as the same action in the app would: a new contact fires Contact created, a stage move fires Stage changed, and a launch fires Campaign launched. Every write the AI makes is recorded in the audit log against the key and, for a personal key, its owner, and revoking the key cuts access immediately.

A typical end-to-end ask, if your role includes the adding and campaign permissions, is something like: count HR managers in Singapore who are not yet in your CRM, add up to 200 into a new list, draft a 2-step campaign on your connected mailbox, enrol the list, preview the launch, and launch it once you confirm.