Claude MCP

The Model Context Protocol (MCP) is an open standard that lets AI assistants like Claude securely access external tools and data sources. FinnAI exposes an MCP server, so you can plug FinnAI into Claude (or any MCP-compatible client) and have your AI assistant query, configure, and operate the platform conversationally.

Who this is for. This is for power users — developers, automation engineers, and AI-savvy operators who want to drive FinnAI from Claude Desktop, Claude Code, or any other MCP client. If you're not familiar with Claude or MCP, you don't need this — the dashboard does everything the MCP exposes.

Status: the FinnAI MCP server is in public beta. APIs are stable but additional tools are being added regularly.

What you can do with the MCP

Once connected, your Claude (or other MCP-compatible AI) can do all of the following on your behalf:

Read operations

• Get the status of any deployment.
• List your Finns, audiences, phone numbers.
• Pull call transcripts and analytics for any time range.
• Search call history for specific patterns ("show me calls where the caller mentioned 'refund'").
• Read deployment costs, plan usage, and billing summaries.

Write operations

• Launch a new deployment.
• Pause or stop an active deployment.
• Add contacts to an audience.
• Update post-call analysis fields on a Finn.
• Suppress numbers (add to do-not-call list).

Coordination

• Generate weekly/monthly reports automatically.
• Cross-reference call outcomes with your CRM to detect attribution gaps.
• Auto-create a new deployment when a CRM list reaches a threshold size.
• Summarize a deployment in plain English suitable for sharing with a non-technical stakeholder.

Setting up the MCP server

Step 1 — Generate an MCP token

Settings → Integrations → MCP → Generate Token.

Copy the token immediately — you'll only see it once. Store in your password manager or secret store.

The token scopes are configurable:

• Read-only — query data but not modify
• Read + write — full operational access (cautious)
• Scoped to specific Finns/audiences — limit access to a subset

For most users, start with Read-only to get comfortable, then expand later.

Step 2 — Configure your MCP client

Claude Desktop (Mac, Windows):

Edit your Claude Desktop config file:

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

Add the FinnAI server:

{
  "mcpServers": {
    "finnai": {
      "command": "npx",
      "args": ["-y", "@finnai/mcp-server"],
      "env": {
        "FINNAI_API_TOKEN": "your_token_here"
      }
    }
  }
}

Restart Claude Desktop. The FinnAI tools become available in any conversation.

Claude Code (CLI):

claude mcp add finnai \
  --command "npx -y @finnai/mcp-server" \
  --env FINNAI_API_TOKEN=your_token_here

Then claude from any directory — FinnAI tools are available.

Other MCP clients (Continue, Cursor, custom):

Use the same npx command in your client's MCP server configuration. The server speaks standard MCP over stdio.

Step 3 — Test the connection

In Claude (any client), ask:

"What Finns do I have configured?"

If the connection works, Claude calls the list_finns tool and responds with a real answer.

Tools the MCP exposes

The server provides ~30 tools. Highlights:

Finn management

• list_finns — list all Finns in the account.
• get_finn — fetch one Finn's full config.
• create_finn — make a new Finn (advanced).
• update_finn — modify Finn settings.

Audience management

• list_audiences — list all audiences.
• get_audience_stats — counts, validation status, recent imports.
• add_contacts — bulk add contacts.
• remove_contact — drop a single contact.

Deployment lifecycle

• list_deployments — list past + active deployments.
• launch_deployment — start a new one.
• pause_deployment / resume_deployment / stop_deployment.
• get_deployment_status — live status with current call counts.

Analytics

• get_deployment_analytics — full metrics for a deployment.
• search_calls — find calls matching content patterns.
• get_call — fetch a single call's transcript + analysis.
• aggregate_calls — custom rollups by any field over any time range.

Compliance

• add_to_suppression_list — globally suppress a number.
• remove_from_suppression_list — un-suppress.
• check_suppression — is a number on the list?

Billing

• get_usage_this_month — running spend.
• forecast_month_end — projection based on trajectory.
• set_spend_cap — adjust caps.

Full schema for each tool: api.hirefinn.ai/academy/mcp.

Things you can ask Claude to do

Real prompts that work:

"Show me yesterday's deployment results and tell me which Finn performed best."

"Find all calls in the last week where the caller said 'too expensive' and summarize the common context."

"Launch the same deployment as last Monday's, but on the new audience I uploaded this morning."

"How much did we spend last week, and is it on track vs. our budget?"

"Add these phone numbers to the suppression list: [paste list]"

"What's the difference in success rate between our morning calls and afternoon calls?"

"Generate a 1-page summary of last month's appointment-reminder campaign for the clinic manager."

The MCP makes FinnAI conversational. Operations that would take 5-10 clicks in the dashboard become a single natural-language ask.

Security considerations

What the token can do

The token scopes determine what's allowed:

• Read-only token → can query everything but mutate nothing.
• Read + write → full operational access. Treat it like your dashboard password.
• Scoped tokens → limit by Finn ID, audience ID, or operation type.

Best practices

• Don't paste tokens into chat messages. Use environment variables in your MCP client config.
• Rotate tokens periodically. Settings → Integrations → MCP → Rotate.
• Use scoped tokens for team members. Don't give a contractor a full-access token.
• Audit log. Every MCP call is logged. Settings → Integrations → MCP → Activity Log.
• Revoke tokens immediately if leaked. Settings → Integrations → MCP → Revoke.

What Claude can't do

The MCP doesn't expose:

• Account creation/deletion
• Payment method changes
• Plan upgrades/downgrades
• Team-member invites
• SSO configuration

These require dashboard access. Intentional — these are decisions you want a human to make.

Approving sensitive actions

By default, the MCP requires explicit human approval (via your MCP client's permission system) for any write operation:

• Launching deployments
• Adding/removing contacts
• Modifying Finn configs
• Spending money

This is enforced at the protocol level — Claude can't execute a write without you confirming in the client UI. Read operations don't require approval.

You can disable this on a per-tool basis under Settings → Integrations → MCP → Auto-approve list if you want certain tools to run without prompts. Use sparingly — auto-approving "launch_deployment" is a real way to spend a lot of money fast.

Common patterns

Daily standup

Configure Claude to fetch yesterday's metrics every morning:

"Every weekday at 9 AM, summarize yesterday's deployment results, highlight any anomalies, and post to my Slack."

(Requires Claude Code with scheduled tasks, or your own cron + MCP wrapper.)

Anomaly detection

"Check if any deployment in the last 24 hours had a success rate below 50% or a cost more than 2x its 7-day average. Flag them with details."

Bulk auditing

"List all Finns that don't have post-call analysis fields defined. Suggest reasonable defaults for each based on the Finn's identity description."

Quick exports

"Pull all calls from deployment X where qualified=true, export as CSV, and email to me."

Troubleshooting

"Claude can't find the FinnAI tools"

• Restart Claude Desktop after editing config.
• Check the config JSON is valid (commas, quotes).
• Run npx -y @finnai/mcp-server --test in terminal to verify the server starts.

"Authentication failed"

• Token expired or revoked. Generate a new one.
• Token environment variable not being passed through (config typo).

"Tool call timed out"

• Large queries (e.g. searching call history) can take 30+ seconds.
• Default timeout in most clients is 30s. Increase if needed.

"Permission denied for tool X"

• Your token scope doesn't include this tool.
• Re-generate a token with broader scope, or use the dashboard for that operation.

What's coming

The MCP roadmap (as of this writing):

• Workflow tools — create and edit visual workflows via Claude.
• Test-on-Call tool — initiate test calls from Claude.
• Streaming subscriptions — real-time event streams for live deployments.
• Multi-account support — manage multiple FinnAI accounts from one Claude session.
• Recording playback — stream call audio to Claude for direct listening (Enterprise).

Suggest tools you want at support@hirefinn.ai.

Beyond Claude

Although this page focuses on Claude, the MCP server is provider-agnostic. It works with:

• Continue.dev (VS Code AI extension)
• Cursor (AI-first IDE)
• OpenAI ChatGPT Desktop (when MCP support ships)
• Custom MCP clients built on the open spec

Any client that speaks MCP can use FinnAI through the same server.

Next

• Integrations → REST API — the underlying API the MCP wraps.
• Integrations → Webhooks — push notifications for event-driven workflows.
• Capacity & Scale → — rate limits that apply to MCP calls.