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 orientar 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-turno 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 conectar, 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 limitado a 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 incorporado 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-turno programaticamente.
Roteamento baseado em capacidades. Use list_fin_capabilities para determinar quais ações estão disponíveis para um determinado usuário, 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 seu Gerente de Conta 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 usuário. 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 usuário. 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 > Workspace > Segurança > Messenger). O JWT deve ser assinado com HS256 e incluir o ID externo do usuário na reivindicação sub. Este é o mesmo JWT exato que você geraria para autenticar usuários finais no Messenger, exceto pelos requisitos aud e exp indicados abaixo.
Exemplo de payload JWT:
{
"user_id": "user@example.com",
"aud": "fin-agent-api-mcp",
"exp": 1719849600
}Nota:
exp e aud são obrigatórios.
exp deve ser <= 30 dias a partir de agora.
aud deve ser fin-agent-api-mcp
Passe como um token Bearer:
Authorization: Bearer YOUR_USER_JWT
O usuário identificado no JWT é o usuário que o Fin responderá. Ele usará esse usuário 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 usuário: os procedimentos correspondentes ao público que o usuário 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 usuário específico antes de chamar outras ferramentas. O acesso a procedimentos é correspondente ao público — nem todo usuário tem acesso a todos os procedimentos.
Entrada: user_id — o ID externo do usuário.
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-turno.
Entradas: user_id, mensagem (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-turno — por exemplo, fornecendo informações adicionais que o Fin solicitou durante um procedimento.
Entradas: conversation_id, mensagem.
run_fin_procedure
Aciona um procedimento Fin específico para um usuário. 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ê deseja executar.
Entradas: procedure_id, user_id.