What the MCP server does
Finn exposes an MCP (Model Context Protocol) server. An MCP-compatible AI client connects to it and calls Finn tools on your behalf, so you can query and operate the platform in natural language instead of clicking through the dashboard.
This is for developers and automation engineers running Claude Desktop, Claude Code, or another MCP client. Everything the MCP exposes is also available in the dashboard, so this is optional.
The server is in public beta. The existing tools are stable, but tools are still being added.
Generate a token
Go to Settings → Integrations → MCP → Generate Token in the dashboard. There is no API endpoint for minting MCP tokens.
The token is shown once. Copy it into a password manager or secret store before closing the dialog. If you lose it, generate a new one.
| Scope | What it allows |
|---|---|
| Read-only | Query data. No mutations. |
| Read + write | Full operational access. Treat like your dashboard password. |
| Scoped | Restricted to specific Finn IDs, audience IDs, or operation types. |
Start read-only. A read+write token in an AI client can launch deployments, which spends money.
Configure your client
Claude Desktop — edit the config file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"finnai": {
"command": "npx",
"args": ["-y", "@finnai/mcp-server"],
"env": {
"FINNAI_API_TOKEN": "your_token_here"
}
}
}
}
Restart Claude Desktop after editing. The tools do not appear until you do.
Claude Code:
claude mcp add finnai \
--command "npx -y @finnai/mcp-server" \
--env FINNAI_API_TOKEN=your_token_here
Other clients (Continue, Cursor, custom): use the same npx command in that client's MCP server config. The server speaks standard MCP over stdio.
To verify, ask the assistant "What Finns do I have configured?" It should call list_finns and return real data.
Tools
The server provides roughly 30 tools. Grouped:
| Group | Tools |
|---|---|
| Finn management | list_finns, get_finn, create_finn, update_finn |
| Audiences | list_audiences, get_audience_stats, add_contacts, remove_contact |
| Deployments | list_deployments, launch_deployment, pause_deployment, resume_deployment, stop_deployment, get_deployment_status |
| Analytics | get_deployment_analytics, search_calls, get_call, aggregate_calls |
| Compliance | add_to_suppression_list, remove_from_suppression_list, check_suppression |
| Billing | get_usage_this_month, forecast_month_end, set_spend_cap |
These map onto the same objects as the REST API. See api-finns, api-deployments, api-calls, and api-audiences for the underlying resource shapes.
What the MCP does not expose
The following require dashboard access and have no MCP tool:
- Account creation and deletion
- Payment method changes
- Plan upgrades and downgrades
- Team-member invites
- SSO configuration (see sso)
This is deliberate. Those are decisions a human should make directly.
Write approvals
Every write operation requires explicit human approval through your MCP client's permission system. That covers launching deployments, adding or removing contacts, modifying Finn configs, and anything that spends money. The requirement is enforced at the protocol level, so the assistant cannot execute a write you have not confirmed in the client UI. Read operations do not prompt.
You can exempt individual tools under Settings → Integrations → MCP → Auto-approve list. Be careful with this. Auto-approving launch_deployment means an assistant can start a campaign, and the calls, without any confirmation from you.
Security
- Do not paste tokens into chat messages. Pass them through environment variables in the client config, as shown above.
- Rotate tokens periodically: Settings → Integrations → MCP → Rotate.
- Give team members and contractors scoped tokens, not full-access ones.
- Every MCP call is logged. Settings → Integrations → MCP → Activity Log.
- Revoke a leaked token immediately: Settings → Integrations → MCP → Revoke.
Troubleshooting
| Symptom | Cause and fix |
|---|---|
| Tools do not appear in the client | Config not reloaded. Restart Claude Desktop. Also check the JSON parses (trailing commas, unquoted keys). |
| Server fails to start | Run npx -y @finnai/mcp-server --test in a terminal to see the startup error directly. |
| "Authentication failed" | Token expired or revoked, or the env var is not reaching the process. Generate a new token and check the variable name is FINNAI_API_TOKEN. |
| Tool call times out | Large queries such as call-history searches can exceed 30 seconds. Most clients default to a 30-second timeout. Raise it in the client config. |
| "Permission denied for tool X" | Your token scope excludes that tool. Generate a broader-scoped token, or do the operation in the dashboard. |
Failures here are usually the token or the config file, not the server. Check both before filing a ticket with support.
Roadmap
Not yet available, in progress:
- Workflow tools for creating and editing visual workflows (see workflow-editor)
- A test-call tool for initiating test calls from the assistant (see agents-testing)
- Streaming subscriptions for live events
Until those land, use webhooks for anything event-driven. The MCP is request-response only, so an assistant cannot be notified when a call ends. It has to poll.