Nota
O MCP Server para o Fin Agent API está atualmente em beta e pode mudar substancialmente antes do lançamento final. Seu feedback é bem-vindo e será útil para guiar o futuro deste recurso do produto.
O Fin Agent API expõe um servidor remoto Model Context Protocol (MCP) que permite que agentes externos de IA chamem o Fin como uma ferramenta. Em vez de reconstruir a lógica de suporte em seu próprio agente, você pode conectar a knowledge base, procedimentos e capacidades de conversação multi-turn do Fin diretamente de qualquer cliente compatível com MCP — incluindo Claude, Claude Code, Cursor ou seu próprio framework de agente.
Existem duas formas de conexão, dependendo de quem o cliente está atuando como:
| Companheiro de equipe | Usuário final |
URL | ||
Autentica | Um workspace, via Fin Agent API api key | Um único usuário final verificado, via um Messenger JWT |
Modelo de confiança | Backend confiável servidor a servidor | Cliente por usuário não confiável (um assistente de IA rodando no ambiente do usuário final ou próximo a ele) |
De quem é a identidade? | O cliente afirma qual usuário final (user_id) cada chamada representa | O token é a identidade — o cliente não pode agir como outra pessoa |
Possui um segredo em nível de app? | Sim (a Fin Agent API key) | Não — apenas um JWT com escopo para um usuário |
Casos de uso
O Fin Agent API MCP server é projetado para cenários multi-agente onde seu próprio agente precisa acessar as capacidades do Fin:
Suporte embutido em agentes de produto. Dê ao assistente de IA do seu produto a capacidade de responder perguntas de suporte usando seu conhecimento Fin configurado, sem duplicar sua knowledge base ou conteúdo.
Automação de procedimentos. Permita que um agente orquestrador acione procedimentos Fin (reembolsos, upgrades, cancelamentos) em nome dos users e gerencie interações multi-turn programaticamente.
Roteamento baseado em capacidades. Use list_fin_capabilities para determinar quais ações estão disponíveis para um determinado user, então direcione para a ferramenta certa na lógica de decisão do seu agente.
Ferramentas para desenvolvedores. Exponha seu conhecimento Fin dentro de ferramentas para desenvolvedores como Claude Code ou Cursor, para que users internos possam consultar seu conteúdo de suporte a partir do fluxo de trabalho existente.
Pré-requisitos
Seu workspace Intercom deve ter o recurso Fin Agent API habilitado. Contate sua equipe de conta Intercom se você não tiver acesso.
Endpoints
Existem dois endpoints, dependendo de quem está fazendo a solicitação.
Endpoint de companheiro de equipe
https://api.intercom.io/fin/mcp
Use isso quando um serviço backend confiável estiver chamando o Fin em nome de um user. O chamador autentica com um token de acesso OAuth para o workspace. A identidade do usuário final é fornecida no corpo da solicitação pelo serviço chamador.
Este modelo é apropriado para integrações servidor a servidor onde seu backend controla quem está fazendo a solicitação.
Endpoint de usuário final
https://api.intercom.io/fin/mcp/{YOUR_APP_ID_CODE}Use isso quando o cliente MCP roda no ambiente do usuário final ou próximo a ele — por exemplo, um assistente de IA rodando localmente na máquina do user. O chamador autentica com um JWT assinado representando um único usuário final verificado.
O parâmetro de caminho {YOUR_APP_ID_CODE} é o identificador do seu workspace Intercom (o mesmo app_id usado nos snippets de instalação do Messenger).
A autenticação usa o mesmo mecanismo Messenger JWT já usado para verificação de identidade — se você já configurou a verificação de identidade do Messenger, nenhuma configuração adicional é necessária do lado do Intercom.
Autenticação
Endpoint de companheiro de equipe
Passe sua Fin Agent API api key como um token Bearer no cabeçalho Authorization:
Authorization: Bearer YOUR_FIN_AGENT_API_KEY
Endpoint de usuário final
Gere um JWT assinado usando o segredo Messenger do seu workspace (encontrado em Configurações → Segurança → Verificação de identidade). O JWT deve ser assinado com HS256 e incluir o ID externo do user na reivindicação sub. Este é exatamente o mesmo JWT que você geraria para autenticar usuários finais para o Messenger.
Exemplo de payload JWT:
{
"user_id":"user@example.com"
}
Passe como um token Bearer:
Authorization: Bearer YOUR_USER_JWT
O user identificado no JWT é o user ao qual o Fin responderá. Ele usará esse user para criar conversas e para corresponder procedimentos. Seu backend gera esse token no servidor e o fornece ao cliente — nunca exponha seu segredo Messenger no lado do cliente.
Conectando do Claude
Claude Desktop
Adicione o seguinte ao seu claude_desktop_config.json:
Endpoint de companheiro de equipe:
{
"mcpServers": {
"fin": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://api.intercom.io/fin/mcp",
"--header",
"Authorization: Bearer {YOUR_FIN_AGENT_API_KEY}"
}
}
}
}
Endpoint de usuário final:
{
"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)
Endpoint de companheiro de equipe:
claude mcp add intercom-fin \
--transport http \
https://api.intercom.io/fin/mcp \
--header "Authorization: Bearer YOUR_FIN_AGENT_API_KEY"
Endpoint de usuário final:
claude mcp add intercom-fin \
--transport http \
https://api.intercom.io/fin/mcp/YOUR_APP_ID_CODE \
--header "Authorization: Bearer YOUR_USER_JWT"
Ou adicione o JSON equivalente em .mcp.json sob mcpServers.
Ferramentas
Uma vez conectado, o servidor MCP expõe cinco ferramentas para o cliente.
list_fin_capabilities
Retorna as capacidades do Fin Agent API disponíveis para um determinado user: os procedimentos correspondentes ao público que o user pode acionar, além das ações estáticas disponíveis para todos os users (fazer uma pergunta, responder a uma conversa).
Chame isso primeiro para descobrir o que o Fin pode fazer para um user específico antes de chamar outras ferramentas. O acesso a procedimentos é correspondente ao público — nem todo user tem acesso a todos os procedimentos.
Entrada: user_id — o ID externo do user.
Retorna: Um documento JSON listando as capacidades disponíveis, cada uma com seu tipo, ID e nome.
ask_fin
Envia uma pergunta única para o Fin e retorna uma resposta. O Fin busca suas fontes de conhecimento configuradas e retorna uma resposta direta sem iniciar uma conversa persistente.
Use isso para consultas informativas onde você quer uma resposta direta e não precisa de fluxo multi-turn.
Entradas: user_id, message (a pergunta a ser feita).
get_fin_response
Consulta a resposta do Fin para uma conversa ou fluxo de procedimento em andamento. Use isso após iniciar uma conversa ou procedimento para recuperar a resposta mais recente do Fin.
Entrada: conversation_id.
reply_to_fin_conversation
Envia uma mensagem de acompanhamento em uma conversa Fin existente. Use isso para continuar uma interação multi-turn — por exemplo, fornecendo informações adicionais que o Fin solicitou durante um procedimento.
Entradas: conversation_id, message.
run_fin_procedure
Aciona um procedimento Fin específico para um user. Um procedimento é um fluxo de trabalho multi-etapas configurado — por exemplo, processar um reembolso ou atualizar uma assinatura. O Fin iniciará o procedimento, pode pedir informações adicionais e conduzirá a interação até a conclusão.
Use list_fin_capabilities primeiro para encontrar o ID do procedimento para a ação que você quer executar.
Entradas: procedure_id, user_id.