MCP server

What the MCP server does

Finn runs a remote MCP server. Connect an AI assistant to it, such as Claude, ChatGPT, Cursor or Claude Code, and the assistant can work in your Finn workspace on your behalf:

• Finn agents: list and read your voice and chat agents, create new ones as drafts, edit drafts, and read aggregate call stats.
• CRM: search and read records, timelines, follow-ups, documents and forms; ask the CRM questions in plain English; add notes and follow-ups, create records and edit fields; move stages, submit forms, attach files, import sheets and create outside-party links.

What a key can do is set by its scopes, chosen when you generate it. A key never does more than its owner can do in the dashboard.

It's deliberately limited. No tool can place a call, send an email or message, start or stop a deployment, delete or merge anything, export data in bulk, read transcripts or recordings, touch billing, or take a Finn out of draft. Stage moves, form submits, file attaches, imports and outside-party links show you a preview and ask before they happen.

Server

If you connected with the older finn-mcp-73965536364.asia-southeast1.run.app address, it still works for now. Switch to the address above when you next reconnect.

The key belongs to the person who generated it. Everything the assistant does happens as that person, in their organization. You can't pass an organization or creator ID to change that.

Get a key

1. In the dashboard, go to Settings → Integrations and find AI Assistants (MCP).
2. Click Generate key.
3. Enter a Key name, for example "work laptop". In Claude, the connector shows up under this name.
4. Under What this key can do, pick its scopes (see Scopes below). Finn agents is on by default.
5. Under Organizations, keep All my organizations or pick Only these organizations.
6. Set Expires. Keys that see sensitive fields or make CRM changes must expire; they default to 90 days and can last up to 365.
7. Click Generate.

The key is shown once. The dialog that shows it also gives you a ready-made connector link and Claude Code command. Copy what you need before you click Done, I've copied it.

The key list shows each key's scopes, when it was created, when it was last used and when it expires. Revoke stops a key on its next request. Finns already created with it aren't affected. There's no public API for creating or revoking keys. To change a key's scopes, generate a new key and revoke the old one.

Scopes

The server only lists the tools a key's scopes allow, and the backend checks the scope again on every request.

Connect a client

Claude (web or desktop)

The dialog's Claude app tab shows Your connector link:

https://mcp.hirefinn.ai/mcp/finn_mcp_...

1. In Claude, open Customize → Connectors, click + and choose Add custom connector.
2. Paste the link as the remote MCP server URL and click Add.
3. In a new chat, open + → Connectors and switch Finn on.

The link contains your key, so anyone who has it can act as you. Treat it like a password, and revoke the key if it leaks.

On Claude's Free plan you can add one custom connector. On Team and Enterprise plans, only an Owner can add one, under Organization settings → Connectors, and everyone else then clicks Connect.

Claude Code

The dialog's Claude Code tab shows the command with your key filled in:

claude mcp add --transport http finn https://mcp.hirefinn.ai/mcp --header "Authorization: Bearer finn_mcp_..."

Run it in a terminal, then start claude.

Cursor

Add Finn to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json in a project:

{
  "mcpServers": {
    "finn": {
      "url": "https://mcp.hirefinn.ai/mcp",
      "headers": { "Authorization": "Bearer finn_mcp_..." }
    }
  }
}

Then open Cursor Settings → MCP and check that Finn is listed and switched on. Don't commit a project file that contains your key.

ChatGPT

ChatGPT connects to remote MCP servers in developer mode (Plus, Pro, Business, Enterprise and Edu plans, on the web). On Business and Enterprise an admin may need to allow custom connectors first.

1. In ChatGPT, open Settings → Apps & Connectors → Advanced settings and turn on Developer mode.
2. Back in Apps & Connectors, click Create.
3. Give it a name, such as "Finn", and paste your connector link (https://mcp.hirefinn.ai/mcp/finn_mcp_...) as the MCP server URL.
4. Set authentication to No authentication: the key is in the link.
5. Confirm that you trust the server, and click Create.
6. In a new chat, turn Finn on from the tools menu.

The link contains your key, as with Claude. Menu names in ChatGPT change between releases; if yours differ, look for developer mode and custom connectors.

Other clients

Any MCP client that supports streamable HTTP works. Point it at https://mcp.hirefinn.ai/mcp and send Authorization: Bearer finn_mcp_.... If the client only takes a URL, use the connector link with the key in it.

To check the connection, ask the assistant to list your Finns. It should call list_finns. With only CRM scopes, ask for your follow-ups instead: it should call crm_list_follow_ups.

Tools

There are 50: 18 Finn agent tools with the finn scope and 32 CRM tools across the crm: scopes. A key sees only the tools its scopes allow.

Finn agent tools (finn)

Tools that create or edit a Finn return a link to it in the dashboard. A dashboard tab that was already open won't list a new Finn until you reload it.

The edit tools only work on drafts. A Finn that has been deployed is edited in the dashboard.

Chat agents

Pass channel: "chat" to create_finn or generate_finn to make a text chat agent instead of a voice agent. It's the same as choosing Chat AI Agent in the dashboard, and the link the tool returns opens it in the chat agent builder. Editing or copying a chat agent keeps it a chat agent.

Connecting a chat agent to your website, WhatsApp, SMS or email inbox is done in the dashboard, under Chat AI Agents.

Call handling

update_finn_draft sets the same options as the call handling panel in the dashboard. They apply to voice agents only.

The CSV column mapping that get_finn_variables and update_finn_variables read and write isn't applied on phone calls, and neither are single-brace {placeholders}. Calls fill {{ column }} variables in the welcome message and system prompt straight from the audience row. See variables.

get_share_link returns the existing link if there is one. If sharing was switched off or the link has expired, it says so rather than making a new one. Anyone with a share link can talk to the Finn in a browser, which uses your credits.

CRM tools

Every CRM tool takes an org_id and starts with crm_. Call crm_get_schema first: it returns the organization's record kinds, stages, custom fields (and which are sensitive), document types, and the filters search accepts.

"Asks first" means the first call returns a preview and a one-time confirmation; the assistant shows it to you and repeats the call only after you say yes.

What the MCP can't do

• Build or edit a call flow canvas, or attach tools. See workflow editor.
• Connect a chat agent to a channel, or send emails or messages. Email from the CRM is drafts only.
• Place calls or create deployments. Use the dashboard, or the API: see api-calls and api-deployments.
• Delete, merge, enrich or bulk-export records, or override a stage check.
• Read call transcripts or recordings, or file contents.
• Start or manage Finn Operator cases. Use the dashboard.
• Notify the assistant when something happens. For events, use webhooks.

Troubleshooting

Related

• API authentication: API keys for the REST API, which are separate from MCP keys
• api-finns