Este guia explica como conectar servidores externos de Model Context Protocol (MCP) aos agentes de IA do Discourse, permitindo que qualquer provedor de ferramenta compatível com MCP seja usado diretamente dentro do bot de IA.
Nível de usuário necessário: Administrador
O que é “Bring Your Own MCP”?
O Model Context Protocol é um padrão aberto (originalmente proposto pela Anthropic) que permite que agentes de IA se comuniquem com servidores de ferramentas externos por meio de uma interface padrão HTTP/JSON-RPC. Um servidor MCP expõe um menu de “ferramentas” — funções com entradas tipadas — que um LLM pode chamar para realizar tarefas.
O Discourse AI agora atua como um cliente MCP. Você registra qualquer servidor MCP HTTPS no painel de administração, o Discourse descobre suas ferramentas disponíveis e essas ferramentas se tornam cidadãos de primeira classe em qualquer agente de IA que você escolher. Não há necessidade de escrever JavaScript; as ferramentas são definidas pelo servidor remoto.
Isso difere das ferramentas de script personalizadas, que exigem a escrita de JavaScript executado dentro do Discourse. Com o MCP, você traz um servidor externo já em execução.
Resumo
- Registre um servidor MCP (URL + autenticação opcional)
- O Discourse descobre e armazena em cache automaticamente as ferramentas do servidor
- Atribua o servidor a um ou mais agentes de IA
- Opcionalmente, limite quais ferramentas cada agente pode usar
- As ferramentas são chamadas pelo LLM em tempo de execução, roteadas pelo Discourse até o servidor externo
Registrando um Servidor MCP
Navegue até:
Admin → Plugins → Discourse AI → Ferramentas → aba Servidores MCP → Novo servidor MCP
Preencha os seguintes campos:
| Campo | Descrição |
|---|---|
| Nome | Um rótulo legível (exibido no editor do agente e nos logs) |
| Descrição | Para que serve este servidor (referência para administradores) |
| URL | O endpoint HTTPS do servidor MCP — deve ser uma URL HTTPS pública, sem IPs privados |
| Autenticação | Uma das opções: Sem autenticação, Credencial de cabeçalho ou OAuth |
| Tempo limite (segundos) | Quanto tempo o Discourse aguarda por solicitação — padrão 30, máximo 300 |
| Habilitado | Alternar para desabilitar temporariamente o servidor sem excluí-lo |
As URLs devem usar HTTPS.
localhoste endereços privados RFC-1918 são bloqueados (a proteção SSRF é aplicada no lado do servidor).
Opções de Autenticação
Sem Autenticação
O servidor é acessível publicamente. Nenhuma credencial é enviada.
Credencial de Cabeçalho
Um valor secreto é injetado como um cabeçalho HTTP em cada solicitação.
- Primeiro, crie uma Credencial em Admin → IA → Credenciais
- Selecione-a como Credencial no formulário do servidor MCP
- Defina o nome do Cabeçalho de autenticação (padrão:
Authorization) - Defina o prefixo opcional do Esquema de autenticação (padrão:
Bearer)
O cabeçalho de solicitação enviado ao servidor MCP será:
Authorization: Bearer <seu-valor-secreto>
Você pode alterar tanto o nome do cabeçalho quanto o esquema para corresponder a qualquer estilo de autenticação exigido pelo seu servidor (por exemplo, X-Api-Key: <valor> deixando o esquema em branco).
OAuth
O Discourse implementa um fluxo completo OAuth 2.0 + PKCE como cliente MCP. Isso suporta servidores MCP que protegem suas ferramentas atrás do OAuth.
Passos de configuração:
- Defina Autenticação como
OAuth - Escolha Registro do cliente:
- Documento de metadados do cliente (padrão) — O Discourse publica seus próprios metadados de cliente OAuth em
https://seu-site.com/discourse-ai/mcp/oauth/client-metadata. Se o servidor MCP suportar Registro Dinâmico de Cliente RFC 7591, o Discourse se registrará automaticamente - Credenciais de cliente manuais — insira seu ID de cliente OAuth pré-registrado e escolha uma credencial de segredo de cliente OAuth
- Documento de metadados do cliente (padrão) — O Discourse publica seus próprios metadados de cliente OAuth em
- Opcionalmente, defina Escopos OAuth (separados por espaço)
- Salve o servidor
- Clique em Conectar — o Discourse irá redirecioná-lo pela página de autorização do provedor
- Após autorizar, você será retornado ao painel administrativo e o status mostrará Conectado
Opções avançadas de OAuth (ative “Mostrar opções avançadas”):
| Opção | Finalidade |
|---|---|
| Parâmetros de autorização OAuth | Objeto JSON mesclado na solicitação de autorização (por exemplo, {"access_type":"offline"}) |
| Parâmetros de token OAuth | Objeto JSON mesclado nas solicitações de troca de token |
| Exigir token de atualização | Falhar na conexão se o provedor não retornar um token de atualização |
O Discourse atualiza automaticamente os tokens de acesso antes do vencimento e retenta em caso de 401 se um token de atualização estiver disponível.
Testando a Conexão
Antes de atribuir um servidor a um agente, use o botão Testar conexão no formulário do editor. Isso inicializa imediatamente uma sessão MCP, chama tools/list e retorna:
- Versão do protocolo MCP negociada
- Número de ferramentas descobertas
- Nomes de todas as ferramentas
Se o teste falhar, a mensagem de erro do servidor (ou um indicador de tempo limite) será exibida na linha.
Como o Discourse Descobre Ferramentas
O Discourse segue a especificação MCP 2025-03-26. A sequência de conexão é:
Discourse → POST / { method: "initialize", params: { protocolVersion, capabilities, clientInfo } }
Servidor → { result: { protocolVersion, capabilities } } + cabeçalho Mcp-Session-Id
Discourse → POST / { method: "notifications/initialized" } (aperto de mão da sessão concluído)
Discourse → POST / { method: "tools/list", session_id: … }
Servidor → { result: { tools: [ { name, description, inputSchema } … ] } }
As definições de ferramenta são armazenadas em cache por 1 hora por servidor. Após a expiração do cache, um trabalho em segundo plano o atualiza transparentemente. A chave do cache é por site/servidor, portanto, instalações multi-site são isoladas.
Você também pode acionar manualmente uma atualização clicando em Testar conexão — isso sempre busca dados ao vivo.
O status de saúde do servidor (healthy / error) é atualizado a cada atualização de cache.
Atribuindo Servidores MCP a Agentes de IA
Depois que um servidor for registrado, atribua-o a um agente:
- Vá para Admin → Plugins → Discourse AI → Agentes e edite ou crie um agente
- Role até a seção Servidores MCP (abaixo da seção Ferramentas regular)
- A lista mostra todos os servidores MCP habilitados com sua contagem de ferramentas e custo estimado de tokens
- Ative um servidor — ele agora está disponível para aquele agente
Dica: Por padrão, todas as ferramentas de um servidor são disponibilizadas ao agente. A string de localidade diz bem: “Servidores MCP selecionados expõem todas as suas ferramentas por padrão. Reduza-as por agente para reduzir o uso de tokens e manter o foco na escolha de ferramentas.”
Selecionando Ferramentas Específicas por Agente
Ter dezenas de ferramentas disponíveis aumenta o custo de tokens de cada mensagem (cada definição de ferramenta é enviada ao modelo no prompt do sistema). Para manter tudo enxuto:
- No editor do agente, ao lado de um servidor MCP atribuído, clique em Escolher ferramentas
- Um modal mostra todas as ferramentas que o servidor expõe atualmente, com sua descrição e lista de parâmetros
- Marque apenas as ferramentas de que o agente precisa
- Clique em Salvar — o agente agora verá apenas o subconjunto selecionado
A tabela de junção ai_agent_mcp_servers armazena selected_tool_names como um array JSONB. Um array vazio significa “todas as ferramentas habilitadas”.
Nomeação de Ferramentas e Resolução de Conflitos
Os nomes das ferramentas MCP devem ser exclusivos dentro da lista de ferramentas de um único agente (incluindo as ferramentas integradas e de script personalizado do agente). O Discourse lida com conflitos automaticamente:
- Se dois servidores MCP diferentes expuserem uma ferramenta com o mesmo nome, o Discourse as nomeia:
servername__toolname - Se uma ferramenta integrada do Discourse e uma ferramenta MCP compartilharem um nome, a ferramenta MCP também será nomeada
- Se ainda houver colisões após a nomeação, um sufixo numérico será adicionado (
_2,_3, …)
O function_name usado na chamada do LLM pode, portanto, diferir do tool_name bruto no servidor MCP. Isso é tratado transparentemente — a classe de ferramenta MCP sempre armazena o tool_name_value original separadamente e o usa ao chamar o servidor.
Como as Chamadas de Ferramenta Funcionam em Tempo de Execução
Quando o LLM decide usar uma ferramenta MCP:
- Reutilização de sessão: O Discourse procura um ID de sessão MCP em cache para este servidor no contexto atual do bot (
context.mcp_state). As sessões são criadas por cadeia de resposta do bot e reutilizadas em chamadas de ferramenta para o mesmo servidor. - Inicializar se necessário: Se nenhuma sessão existir, um novo aperto de mão
initialize+notifications/initializedé executado. - Chamar:
POST /com{ method: "tools/call", params: { name: tool_name, arguments: params } } - Expiração de sessão: Se o servidor retornar
404(sessão expirada), o Discourse re-inicializa automaticamente e retenta uma vez. - Normalização de resposta: Itens de conteúdo MCP do tipo
textsão concatenados. Itens não-textuais são serializados em JSON.structuredContenté JSON formatado. - Resultado de erro: Se o servidor retornar
isError: true, o bot recebe uma mensagem de erro em vez de um resultado.
A resposta do servidor pode ser JSON puro ou um fluxo SSE — o Discourse lida com ambos.
Exibição de Custo de Tokens
No editor do agente, cada servidor MCP atribuído mostra uma contagem estimada de tokens. Isso é calculado usando o tokenizador OpenAI cl100k_base aplicado à assinatura JSON completa de cada ferramenta (nome + descrição + esquema de entrada). Esta é uma aproximação — o custo real depende do tokenizador do seu LLM.
A divisão de custos de tokens é exibida para ajudá-lo a tomar decisões informadas sobre quais servidores e ferramentas atribuir a um determinado agente.
Solução de Problemas
| Sintoma | O que verificar |
|---|---|
| Testar conexão falha com tempo limite | Aumente o Tempo limite (segundos). O padrão é 30. Se o servidor for lento para inicializar, tente 60–120. |
| Teste tem sucesso, mas as ferramentas não aparecem no agente | Certifique-se de que o servidor esteja Habilitado e de que o agente o tenha ativado na seção de servidores MCP. |
| Status OAuth mostra “Precisa de atenção” | O último erro OAuth é exibido no formulário do editor. Causas comuns: token de atualização expirado (clique em Reconectar), o servidor retornou escopos inesperados ou a URL de metadados do cliente não é acessível a partir do seu servidor. |
Nomes de ferramentas parecem myserver__sometool |
Normal — outra ferramenta (integrada ou de outro servidor) tinha o mesmo nome. O LLM vê e usa automaticamente este nome namespace. |
| Saúde mostra “error” após um período | O trabalho de atualização em segundo plano não conseguiu alcançar o servidor. Verifique /logs no seu site e confirme que o servidor MCP é acessível a partir do host do Discourse. |
| As ferramentas pararam de funcionar no meio da conversa | Expiração de sessão. O Discourse retenta automaticamente uma vez por chamada de ferramenta, mas se o servidor estiver reiniciando consistentemente, encurte seu TTL de sessão ou investigue os logs do lado do servidor. |
Para depuração mais profunda, habilite o acesso a transcrições de IA via ai_bot_debugging_allowed_groups e inspecione o log completo da conversa.
Referência Técnica
Detalhes do Protocolo MCP
| Propriedade | Valor |
|---|---|
| Versão do protocolo | 2025-03-26 |
| Transporte | HTTP POST (JSON-RPC 2.0) |
| Suporte a SSE | Sim (para streaming de respostas tools/call) |
| Gerenciamento de sessão | Cabeçalho HTTP Mcp-Session-Id |
| Tamanho máximo da resposta | 5 MB |
| User-Agent do cliente | Discourse AI MCP Client / <versão> |
Suporte a Esquema JSON
O Discourse resolve as seguintes construções de Esquema JSON nas definições inputSchema de ferramenta antes de passá-las para o LLM:
$ref— resolvido contra$defs/definitionsdo esquema raizallOf— mesclado (propriedades e arrays obrigatórios são mesclados por união)anyOf/oneOf— a primeira variante não-nullé usada
Arquivos Fonte Relevantes
plugins/discourse-ai/lib/mcp/client.rb— cliente HTTP MCP (sessão, chamada, retentativa OAuth)plugins/discourse-ai/lib/mcp/tool_registry.rb— cache de ferramentas, resolução de conflitosplugins/discourse-ai/lib/agents/tools/mcp.rb— classe de ferramenta encapsulando chamadas MCP para o tempo de execução do agenteplugins/discourse-ai/app/models/ai_mcp_server.rb— modelo de servidor, gerenciamento de token OAuthplugins/discourse-ai/app/models/ai_agent_mcp_server.rb— seleção de ferramenta por agenteplugins/discourse-ai/lib/mcp/oauth_flow.rb— fluxo OAuth 2.0 + PKCE
Tópicos Relacionados
- Bot de IA – Ferramentas Personalizadas (baseadas em script)
- Guia de persona/agente do Discourse AI
- Discourse MCP chegou! (Discourse como um servidor MCP)
O recurso Discourse-como-servidor-MCP (discourse/discourse-mcp) é o complemento a este: permite que clientes de IA externos (Claude Code, Cursor, etc.) leiam e escrevam no seu site Discourse. Este guia é o inverso — permite que seus agentes de IA do Discourse chamem servidores MCP externos.