Note
The MCP Server for the Fin Agent API is currently in beta and may change substantially before final release. Your feedback is welcome and will be helpful in guiding the future of this product feature.
The Fin Agent API exposes a remote Model Context Protocol (MCP) server that lets external AI agents call Fin as a tool. Instead of rebuilding support logic in your own agent, you can plug in Fin’s knowledge base, procedures, and multi-turn conversation capabilities directly from within any MCP-compatible client — including Claude, Claude Code, Cursor, or your own agent framework.
There are two ways to connect, depending on who the client is acting as:
| Teammate | End-user |
URL | ||
Authenticates | A workspace, via Fin Agent API api key | A single, verified end user, via a Messenger JWT |
Trust model | Trusted server-to-server backend | Untrusted per-user client (an AI assistant running in or near the end user's environment) |
Whose identity? | The client asserts which end user (user_id) each call acts as | The token is the identity — the client cannot act as anyone else |
Holds an app-level secret? | Yes (the Fin Agent API key) | No — only a JWT scoped to one user |
Use cases
The Fin Agent API MCP server is designed for multi-agent scenarios where your own agent needs access to Fin’s capabilities:
Embedded support in product agents. Give your product’s AI assistant the ability to answer support questions using your configured Fin knowledge, without duplicating your knowledge base or content.
Procedure automation. Let an orchestrating agent trigger Fin procedures (refunds, upgrades, cancellations) on behalf of users and handle multi-turn interactions programmatically.
Capability-driven routing. Use list_fin_capabilities to determine what actions are available for a given user, then route to the right tool in your agent’s decision logic.
Developer tooling. Surface your Fin knowledge inside developer tools like Claude Code or Cursor, so internal users can query your support content from their existing workflow.
Prerequisites
Your Intercom workspace must have the Fin Agent API feature enabled. Contact your Intercom account team if you don’t have access.
Endpoints
There are two endpoints, depending on who is making the request.
Teammate endpoint
https://api.intercom.io/fin/mcp
Use this when a trusted backend service is calling Fin on behalf of a user. The caller authenticates with an OAuth access token for the workspace. The end-user identity is supplied in the request body by the calling service.
This model is appropriate for server-to-server integrations where your backend controls who is making the request.
End-user endpoint
https://api.intercom.io/fin/mcp/{YOUR_APP_ID_CODE}Use this when the MCP client runs in or near the end user’s environment — for example, an AI assistant running locally on a user’s machine. The caller authenticates with a signed JWT representing a single verified end user.
The {YOUR_APP_ID_CODE} path parameter is your Intercom workspace identifier (the same app_id used in Messenger installation snippets).
Authentication uses the same Messenger JWT mechanism already used for identity verification — if you already have Messenger identity verification set up, no additional configuration is needed on the Intercom side.
Authentication
Teammate endpoint
Pass your Fin Agent API api key as a Bearer token in the Authorization header:
Authorization: Bearer YOUR_FIN_AGENT_API_KEY
End-user endpoint
Generate a signed JWT using your workspace’s Messenger secret (found in Settings → Security → Identity verification). The JWT must be signed with HS256 and include the user’s external ID in the sub claim. This is the exact same JWT as you’d generate for authenticating end users for the Messenger.
Example JWT payload:
{
"user_id":"user@example.com"
}
Pass it as a Bearer token:
Authorization: Bearer YOUR_USER_JWT
The user identified in the JWT is the user Fin will respond to. It will use this user to create conversations and to match procedures. Your backend generates this token server-side and provides it to the client — never expose your Messenger secret client-side.
Connecting from Claude
Claude Desktop
Add the following to your claude_desktop_config.json:
Teammate endpoint:
{
"mcpServers": {
"fin": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://api.intercom.io/fin/mcp",
"--header",
"Authorization: Bearer {YOUR_FIN_AGENT_API_KEY}"
}
}
}
}
End-user endpoint:
{
"mcpServers": {
"fin": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://api.intercom.io/fin/mcp/{YOUR_APP_ID_CODE}",
"--header",
"Authorization: Bearer {YOUR_USER_JWT}"
}
}
}
}
Claude Code (CLI)
Teammate endpoint:
claude mcp add intercom-fin \
--transport http \
https://api.intercom.io/fin/mcp \
--header "Authorization: Bearer YOUR_FIN_AGENT_API_KEY"
End-user endpoint:
claude mcp add intercom-fin \
--transport http \
https://api.intercom.io/fin/mcp/YOUR_APP_ID_CODE \
--header "Authorization: Bearer YOUR_USER_JWT"
Or add the equivalent JSON to .mcp.json under mcpServers.
Tools
Once connected, the MCP server exposes five tools to the client.
list_fin_capabilities
Returns the Fin Agent API capabilities available for a given user: the audience-matched procedures the user can trigger, plus the static actions available to all users (ask a question, reply to a conversation).
Call this first to discover what Fin can do for a specific user before calling other tools. Procedure access is audience-matched — not every user has access to every procedure.
Input: user_id — the external ID of the user.
Returns: A JSON document listing available capabilities, each with its type, ID, and name.
ask_fin
Sends a one-shot question to Fin and returns an answer. Fin searches your configured knowledge sources and returns a direct response without starting a persistent conversation.
Use this for informational lookups where you want a direct answer and do not need multi-turn flow.
Inputs: user_id, message (the question to ask).
get_fin_response
Polls for Fin’s reply to an in-progress conversation or procedure flow. Use this after starting a conversation or procedure to retrieve Fin’s latest response.
Input: conversation_id.
reply_to_fin_conversation
Sends a follow-up message in an existing Fin conversation. Use this to continue a multi-turn interaction — for example, providing additional information that Fin requested during a procedure.
Inputs: conversation_id, message.
run_fin_procedure
Triggers a specific Fin procedure for a user. A procedure is a configured multi-step workflow — for example, processing a refund or updating a subscription. Fin will start the procedure, may ask for additional information, and will drive the interaction to completion.
Use list_fin_capabilities first to find the procedure ID for the action you want to run.
Inputs: procedure_id, user_id.
Need more help? Get support from our Community Forum
Find answers and get help from Intercom Support and Community Experts