Modem

O Modem conecta IA a feedbacks de clientes em Slack, suporte, e-mail, chamadas e rastreadores de problemas, transformando-os em insights consultáveis que você pode usar para agir.

Ver em modem.dev

Documentação

O Servidor MCP Modem permite que clientes compatíveis com MCP trabalhem com o Modem fora do painel do Modem. Use-o quando quiser que um assistente externo pesquise seus feedbacks de clientes, tópicos, pessoas e empresas, execute o Agente Modem em suas ferramentas conectadas ou atualize seu espaço de trabalho do Modem diretamente.

A maneira mais rápida de conectar é um plugin oficial do Modem para Claude, ChatGPT, Codex ou Cursor. Para qualquer outro cliente, adicione a URL do servidor manualmente.

:::info Esta página trata de conectar um cliente MCP externo ao Modem. Para conectar servidores de ferramentas MCP externos para o Agente Modem usar, consulte a página de Servidores MCP Externos. :::

Instalar um Plugin

O Modem publica um plugin oficial em cada um desses diretórios. Um plugin conecta-se a este mesmo servidor e faz login com OAuth, então você obtém as mesmas ferramentas sem editar um arquivo de configuração.

Cliente	Diretório	Instalação
Claude	Diretório de Conectores Claude	Instalar no Claude
ChatGPT e Codex	Diretório de plugins do ChatGPT	Instalar no ChatGPT
Cursor	Marketplace do Cursor	Instalar no Cursor

Abra a listagem

Abra a listagem do Modem para seu cliente na tabela acima.
Instale o plugin

Siga o fluxo de instalação da listagem. No Cursor, você também pode executar /add-plugin modem.
Autorize o Modem

Faça login e aprove o acesso na tela de consentimento do Modem. Consulte Autorizar o Modem.

A listagem do diretório de plugins do ChatGPT cobre tanto ChatGPT quanto Codex. Para um cliente que não está listado, ou para configurar o servidor você mesmo, use a URL do servidor e as etapas de configuração do cliente abaixo.

URL do Servidor

Use esta URL no seu cliente MCP:

https://mcp.modem.dev/mcp

O servidor usa Streamable HTTP e OAuth. Você não precisa criar ou colar uma chave de API.

Ferramentas

O servidor expõe sete tipos de ferramentas: uma que executa o Agente Modem completo, uma que fornece habilidades para usar este servidor, uma que lê seus dados diretamente, uma que lê a documentação do Modem, um conjunto que grava no seu espaço de trabalho do Modem, um conjunto que gerencia automações e duas para feedback: criar um canal de feedback para seu aplicativo e enviar feedback sobre o Modem.

Quais ferramentas seu cliente vê depende dos escopos que você aprova durante a autorização. Consulte Segurança e Acesso.

Para a lista completa de parâmetros de cada ferramenta, formato de resultado e exemplos de invocação, consulte a Referência de Ferramentas MCP.

Executar o agente

As execuções do agente são assíncronas. Iniciar uma execução retorna seus IDs imediatamente. A execução continua no Modem, mesmo que seu cliente MCP se desconecte.

Ferramenta	O que faz	Entradas
`modem_agent_invoke`	Inicia uma nova conversa com o agente e retorna seus `conversation_id` e `run_id`.	`prompt`, `idempotency_key`
`modem_agent_get_run`	Retorna o status atual e, quando concluída, a resposta do agente.	`conversation_id`, `run_id`
`modem_agent_send_message`	Inicia uma rodada de acompanhamento em uma conversa MCP existente.	`conversation_id`, `prompt`, `idempotency_key`
`modem_agent_cancel_run`	Solicita o cancelamento de uma execução. Ações que o agente já concluiu não são revertidas.	`conversation_id`, `run_id`

Use estas ferramentas quando a tarefa exigir raciocínio, várias etapas ou suas ferramentas conectadas, como Linear, Slack ou GitHub. As execuções do agente consomem créditos.

Como funciona uma execução do agente

Inicie a execução

Chame modem_agent_invoke com um prompt e um idempotency_key. O Modem retorna conversation_id, run_id e um status working.
Verifique o resultado

Chame modem_agent_get_run com ambos os IDs. Continue verificando até que o status seja completed, failed ou cancelled. Uma execução concluída inclui a resposta em result.text.
Continue a conversa

Chame modem_agent_send_message com o mesmo conversation_id, um novo prompt e um novo idempotency_key. Aguarde a execução atual terminar antes de iniciar o acompanhamento.
Cancele se necessário

Chame modem_agent_cancel_run com os IDs da conversa e da execução. O cancelamento interrompe o trabalho restante, mas não desfaz ações que o agente já concluiu.

Salve os IDs da conversa e da execução após cada chamada de início. Você pode usá-los para verificar a execução de uma nova conexão se o cliente original sair.

Chaves de idempotência

Dê a cada rodada lógica uma idempotency_key estável e única.

Repita a mesma rodada com a mesma chave e exatamente o mesmo prompt. O Modem retorna a execução existente em vez de iniciar outra.
Não reutilize uma chave com um prompt alterado. O Modem a rejeita como conflito.
Inicie cada acompanhamento com uma nova chave. Apenas uma rodada pode ser executada em uma conversa por vez.

Os prompts podem conter até 50.000 caracteres. Todas as quatro ferramentas de execução do agente exigem o escopo agent:invoke.

Habilidades

Ferramenta	O que faz	Escopo
`modem_skills`	Habilidades para usar este servidor. Omita `name` para o catálogo; passe `name` (por exemplo, `search-modem`) para essa habilidade.	`data:read` ou `agent:invoke`

Seu cliente MCP lê estas por conta própria, então não há nada para instalar. Consulte Habilidades para Clientes MCP para saber como isso funciona. modem_skills não é a página de Habilidades no painel do Modem.

Pesquisar seus dados

Ferramenta	O que faz	Escopo
`search_modem`	Responde a uma pergunta em linguagem natural sobre seus dados do Modem e retorna as linhas correspondentes.	`data:read`

search_modem é somente leitura e não executa o Agente Modem completo nem consome créditos do agente. Prefira-a para consultas e busca semântica. É mais rápida e mais barata que modem_agent_invoke.

Ler a documentação

Ferramenta	O que faz	Escopo
`modem_docs`	Pesquisa ou lê a documentação do Modem para responder como o Modem funciona: configuração, integrações, escopos e a API.	`data:read` ou `agent:invoke`

modem_docs é somente leitura e não consome créditos do agente.

Gravar no seu espaço de trabalho

Estas ferramentas aplicam alterações diretamente, sem passar pelo agente.

Ferramenta	O que faz
`update_topic`	Atualiza um único tópico: prioridade, estado do ciclo de vida ou status de arquivamento.
`bulk_update_topics`	Atualiza até 100 tópicos de uma vez, como arquivar ou re-priorizar um conjunto.
`merge_topics`	Ainda não suportada: retorna um erro e não altera nada.
`create_companies`	Cria até 50 empresas. Cada uma precisa de um `name` e um `domain`.
`update_companies`	Atualiza até 50 empresas existentes: nome, domínio principal, logotipo, status VIP ou conexões.
`merge_companies`	Mescla empresas de origem em uma empresa de destino, que é a mantida.
`add_people_to_company`	Associa uma ou mais pessoas a uma empresa.
`update_people`	Atualiza até 50 pessoas existentes: nome de exibição, e-mail, descrição, status VIP ou conexões.
`merge_people`	Mescla pessoas de origem em uma pessoa de destino, que é a mantida.

Todas as ferramentas de gravação exigem o escopo agent:invoke. As ferramentas de atualização e mesclagem são marcadas como destrutivas, então a maioria dos clientes MCP pede que você confirme cada chamada antes de executá-la. create_companies e add_people_to_company apenas adicionam dados e não são.

:::warning As ferramentas de gravação aplicam alterações imediatamente e o Modem não as desfaz por você. Mesclagens em particular não são reversíveis pelo cliente MCP, então confirme se o destino está correto antes de aprovar a chamada. :::

Permissões

As ferramentas de gravação agem como você, não como uma conta de serviço. Cada uma é executada com base no seu papel existente na organização que você selecionou durante a autorização, aplicado da mesma forma que o painel do Modem. Se sua conta não puder fazer uma alteração no painel, a ferramenta também não poderá. Se sua conta não for membro da organização selecionada, a chamada é rejeitada.

Valores de campos

Alguns campos aceitam apenas um conjunto fixo de valores:

Campo	Valores aceitos
`priority`	`very_low`, `low`, `default`, `high`, `very_high`
`lifecycleState`	`open`, `in_progress`, `completed`, `dismissed`
`issueType`	`bug_report`, `feature_request`, `complaint`, `praise`, `discussion`

IDs de tópicos são UUIDs. IDs de empresas e pessoas são strings numéricas. Use search_modem para encontrar os IDs necessários antes de chamar uma ferramenta de gravação.

Gerenciar automações

Estas ferramentas listam, criam e alteram automações, os prompts que o Modem executa em um agendamento ou quando um evento acontece.

Ferramenta	O que faz	Escopo
`list_automations`	Lista todas as automações na organização, com seu agendamento, saídas e execuções recentes.	`data:read`
`create_automation`	Cria uma automação a partir de um nome, fuso horário, agendamento e prompt.	`agent:invoke`
`update_automation`	Altera os campos que você envia em uma automação, como seu prompt, agendamento ou sinalizador de ativação.	`agent:invoke`

Como as ferramentas de gravação, elas agem como você: você é dono das automações que cria e só pode alterar aquelas que o painel permite editar.

Feedback

Ferramenta	O que faz	Escopo
`create_feedback_channel`	Cria um canal de feedback no aplicativo e retorna seu token. Somente administradores da organização.	`agent:invoke`
`send_feedback`	Envia feedback sobre o Modem para a equipe do Modem, com sua aprovação.	`data:read` ou `agent:invoke`

A habilidade install-feedback orienta um agente de codificação na criação de um canal e na adição de feedback a um aplicativo. Consulte Feedback no aplicativo.

Pré-requisitos

Uma conta Modem com acesso à organização que você deseja usar
Claude, ChatGPT, Codex ou Cursor para instalar um plugin
Qualquer outro cliente deve suportar servidores MCP remotos Streamable HTTP com OAuth

O suporte do cliente muda rapidamente. Os exemplos abaixo cobrem clientes MCP comuns com suporte HTTP remoto. Seu cliente pode usar rótulos ligeiramente diferentes para os mesmos campos, e deve suportar OAuth para o servidor do Modem.

Configure Seu Cliente

Estas etapas adicionam o servidor ao seu cliente manualmente. Para Claude, ChatGPT, Codex e Cursor, instalar um plugin é mais rápido. Em todos os casos, a URL do servidor é:

https://mcp.modem.dev/mcp

Claude Code

O Claude Code pode adicionar servidores MCP HTTP remotos pela CLI.

claude mcp add --transport http modem https://mcp.modem.dev/mcp

Em seguida, execute /mcp dentro do Claude Code e conclua o fluxo de autorização no navegador.

Cursor

Para instalar o plugin, abra a listagem do Modem no Cursor Marketplace ou execute /add-plugin modem no Cursor.

O botão adiciona o servidor com um clique (Cursor 3.15.12 ou mais recente). Para adicioná-lo manualmente, abra Configurações → Configurações do Cursor → Ferramentas e MCP e adicione um novo servidor MCP. O Cursor armazena a configuração MCP em um arquivo mcp.json.

{
    "mcpServers": {
        "modem": {
            "url": "https://mcp.modem.dev/mcp"
        }
    }
}

Se o Cursor perguntar sobre o tipo de transporte, escolha Streamable HTTP.

VS Code e GitHub Copilot

O VS Code armazena a configuração MCP em um arquivo mcp.json, seja no seu perfil de usuário ou em .vscode/mcp.json para um workspace.

{
    "servers": {
        "modem": {
            "type": "http",
            "url": "https://mcp.modem.dev/mcp"
        }
    }
}

Use MCP: Adicionar Servidor ou MCP: Abrir Configuração do Usuário na paleta de comandos se preferir editar pelo VS Code.

Codex

O plugin do Modem no diretório de plugins do ChatGPT também funciona no Codex. Para adicionar o servidor pela CLI, execute:

codex mcp add modem --url https://mcp.modem.dev/mcp

Em seguida, autorize o servidor, o que abre o fluxo no navegador:

codex mcp login modem

O Codex armazena a configuração MCP em ~/.codex/config.toml se você preferir editá-la diretamente. auth tem como padrão oauth, então pode ser omitido.

[mcp_servers.modem]
url = "https://mcp.modem.dev/mcp"
auth = "oauth"

opencode

O opencode armazena a configuração MCP em opencode.json. Use "type": "remote" para o servidor Modem.

{
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
        "modem": {
            "type": "remote",
            "url": "https://mcp.modem.dev/mcp"
        }
    }
}

Deixe o campo headers vazio. O Modem usa OAuth, então não há chave de API para passar. O opencode solicita autorização na primeira vez que você usa o servidor, ou você pode acionar o fluxo manualmente:

opencode mcp auth modem

ChatGPT

O caminho mais rápido é o plugin do Modem no diretório de plugins do ChatGPT.

Para conectar o servidor manualmente, use o modo Desenvolvedor, disponível em planos pagos. A disponibilidade pode depender da política da sua conta e do workspace, e a OpenAI moveu a configuração entre menus, então verifique os dois locais abaixo.

Abra Configurações do ChatGPT e ative o modo Desenvolvedor. Dependendo da versão do ChatGPT, ele fica em Segurança e login ou em Aplicativos (anteriormente Conectores) → Configurações avançadas.
Na lista de aplicativos/conectores, clique no botão adicionar (+) para criar uma nova conexão.
Dê um nome como Modem e insira a URL do servidor https://mcp.modem.dev/mcp.
Se solicitado sobre o tipo de autenticação, escolha OAuth. Crie a conexão.
Conclua o fluxo de autorização do Modem na janela do navegador que abrir e revise as ferramentas descobertas.

Em uma conversa, ative a conexão Modem no menu de ferramentas do compositor e faça perguntas que a utilizem. O ChatGPT pede confirmação antes de executar ferramentas de escrita.

Outros Clientes MCP

Use o fluxo de configuração HTTP remoto ou Streamable HTTP do cliente. Se ele solicitar campos, use:

Campo	Valor
Nome	`modem`
URL	`https://mcp.modem.dev/mcp`
Transporte	Streamable HTTP ou HTTP
Autenticação	OAuth

Documentação MCP específica do cliente:

Cliente	Documentação
Claude Code	Conecte o Claude Code a ferramentas via MCP
ChatGPT	Conecte um servidor MCP remoto ao ChatGPT
Cursor	Documentação MCP do Cursor
VS Code	Referência de configuração MCP
Codex	Documentação MCP do Codex
opencode	Servidores MCP do opencode

Autorize o Modem

Seu cliente MCP deve abrir uma janela do navegador para autorização OAuth na primeira conexão.

Na tela de consentimento do Modem:

Confirme o nome do cliente solicitante.
Revise o destino do redirecionamento.
Escolha a organização Modem se sua conta pertencer a mais de uma.
Aprove as permissões solicitadas.

Após a autorização, seu cliente MCP pode chamar as ferramentas MCP do Modem.

Seu cliente vê apenas as ferramentas cobertas pelos escopos que você aprovou. Um token com data:read mas sem agent:invoke vê modem_skills, modem_docs, search_modem, list_automations e send_feedback. modem_skills, modem_docs e send_feedback são expostos em qualquer escopo.

Exemplos de Prompts

Seu cliente MCP escolhe a ferramenta, então formule a solicitação para o resultado desejado. Os exemplos abaixo tendem a selecionar a ferramenta indicada ao lado.

Consultas e perguntas, que normalmente roteiam para search_modem:

Prompt: Pesquise no Modem os tópicos com mais feedback de contas empresariais neste mês.

Prompt: Pergunte ao Modem quais pessoas estão associadas a acme.com.

Trabalho de várias etapas e qualquer coisa envolvendo ferramentas conectadas, que normalmente roteia para modem_agent_invoke:

Prompt: Use o Modem para resumir os relatórios de bugs de maior prioridade dos últimos 7 dias.

Prompt: Pergunte ao Modem quais clientes solicitaram SSO e se já existem problemas relacionados no Linear.

Prompt: Continue essa conversa do Modem e verifique quais clientes afetados estão em planos anuais.

Alterações no seu workspace, que normalmente roteiam para as ferramentas de escrita:

Prompt: No Modem, arquive todos os tópicos sobre a página de cobrança antiga e me diga quais você arquivou.

Prompt: Encontre as empresas Acme duplicadas no Modem e mescle-as na que tem o domínio acme.com.

Prompt: Marque o tópico sobre falhas de login SSO como alta prioridade no Modem.

Automações, que normalmente roteiam para as ferramentas de automação:

Prompt: Crie uma automação no Modem que publique cada novo item de feedback no nosso canal #feedback do Slack.

Prompt: Pause minha automação semanal de resumo de bugs no Modem.

Para uma nova tarefa, inclua o contexto que o agente precisa no primeiro prompt. Para continuar uma execução, peça ao seu cliente para enviar um acompanhamento na conversa Modem existente.

Segurança e Acesso

O Modem autoriza o cliente MCP com OAuth. O token de acesso é limitado à conta Modem e à organização selecionadas durante o consentimento.

As permissões MCP são:

Escopo	Significado	Ferramentas que expõe
`agent:invoke`	Execute o Agente Modem em seu nome e aplique alterações no seu workspace como você.	`modem_skills`, `modem_docs`, `send_feedback`, quatro ferramentas de execução do agente, as ferramentas de escrita do workspace, `create_automation`, `update_automation` e `create_feedback_channel`
`data:read`	Leia seus dados do Modem por meio de pesquisa em linguagem natural e carregue habilidades para este servidor. Não executa o agente pago.	`modem_skills`, `modem_docs`, `send_feedback`, `search_modem`, `list_automations`

O servidor MCP resolve a organização a partir das declarações do token OAuth, não da URL. Mantenha a URL do servidor como https://mcp.modem.dev/mcp.

As ferramentas de escrita também aplicam sua própria função na organização em cada chamada, então um token aprovado nunca concede mais acesso do que sua conta Modem já tem.

Limites de taxa

As chamadas de ferramentas MCP são limitadas por organização, por ferramenta, a 20 chamadas por minuto. Exceder isso retorna um erro de limite de taxa; aguarde cerca de um minuto e tente novamente com backoff. modem_agent_invoke e modem_agent_send_message estão adicionalmente sujeitos aos limites de crédito do agente da sua organização.

Solução de Problemas

Meu cliente MCP não mostra as ferramentas do Modem

Confirme se a URL do servidor é exatamente `https://mcp.modem.dev/mcp`.
Reinicie o cliente ou recarregue a lista de servidores MCP.
Certifique-se de que seu cliente suporte servidores MCP remotos Streamable HTTP com OAuth.

Algumas ferramentas estão ausentes, mas outras funcionam

As ferramentas são expostas por escopo. Se você vê modem_skills, modem_docs, search_modem, list_automations e send_feedback mas nenhuma ferramenta de agente ou escrita, seu token carrega data:read mas não agent:invoke. Execute novamente o fluxo OAuth e aprove ambas as permissões.

A autorização falha ou retorna não autorizado

Entre com a conta Modem que pertence à organização selecionada.
Execute novamente o fluxo OAuth e aprove as permissões solicitadas.
Se a autorização ainda falhar, entre em contato com o suporte do Modem.

Uma ferramenta de escrita retorna proibido

As ferramentas de escrita são executadas como você, sob sua função na organização selecionada. Confirme se sua conta pode fazer a mesma alteração no painel do Modem e se ela é membro da organização que você autorizou.

Uma chamada de ferramenta está com limite de taxa

As chamadas de ferramentas MCP são limitadas a 20 por minuto por organização, por ferramenta. Aguarde cerca de um minuto e tente novamente com backoff. Se uma ferramenta de agente for rejeitada por custo em vez de taxa, as tentativas continuarão falhando até que o uso nas últimas 24 horas caia abaixo do limite diário ou, para o limite mensal de uso, até que sua cota seja redefinida.

A chamada do agente retornou antes de a resposta estar pronta

modem_agent_invoke e modem_agent_send_message retornam assim que o Modem aceita a execução. Use o conversation_id e o run_id retornados com modem_agent_get_run até que a execução atinja um status final.

Um acompanhamento retorna um conflito Aguarde a execução atual terminar antes de enviar outra mensagem na mesma conversa. Se você estiver tentando novamente uma solicitação, reutilize o idempotency_key somente quando o prompt não tiver sido alterado.

Meu cliente desconectou durante uma execução do agente

Reconecte e chame modem_agent_get_run com o conversation_id e o run_id retornados quando a execução começou. O Modem continua execuções aceitas após a conexão MCP original ser encerrada.

Conectei a organização errada

Remova ou desconecte o servidor MCP do Modem no seu cliente, depois autorize novamente e selecione a organização correta na tela de consentimento do Modem.

Relacionados

Skills para Clientes MCP

As skills que o servidor fornece ao seu cliente MCP e como o cliente as encontra.

O Agente Modem

Saiba o que o Agente Modem pode consultar e fazer.

Servidores MCP Externos

Conecte servidores de ferramentas MCP externos para o Agente Modem usar.