Bot de IA: Trae tu propio servidor MCP

Documentación Gestión del sitio
,
1

:bookmark: Esta guía explica cómo conectar servidores externos de Model Context Protocol (MCP) a los agentes de Discourse AI, permitiendo que cualquier proveedor de herramientas compatible con MCP sea utilizado directamente dentro del bot de IA.

:person_raising_hand: Nivel de usuario requerido: Administrador

¿Qué es “Bring Your Own MCP”?

Model Context Protocol es un estándar abierto (propuesto originalmente por Anthropic) que permite a los agentes de IA comunicarse con servidores de herramientas externos a través de una interfaz estándar HTTP/JSON-RPC. Un servidor MCP expone un menú de “herramientas” —funciones con entradas tipadas— que un LLM puede llamar para realizar tareas.

Discourse AI actúa ahora como un cliente MCP. Puedes registrar cualquier servidor MCP HTTPS en el panel de administración, Discourse descubre sus herramientas disponibles y estas se convierten en ciudadanos de primera clase dentro de cualquier agente de IA que elijas. No hay JavaScript que escribir; las herramientas están definidas por el servidor remoto.

Esto difiere de las herramientas de scripts personalizados que requieren escribir JavaScript que se ejecuta dentro de Discourse. Con MCP, traes un servidor externo que ya está en ejecución.

Resumen

  • Registrar un servidor MCP (URL + autenticación opcional)
  • Discourse descubre y almacena en caché automáticamente las herramientas del servidor
  • Asignar el servidor a uno o varios agentes de IA
  • Opcionalmente limitar qué herramientas puede usar cada agente
  • Las herramientas son llamadas por el LLM en tiempo de ejecución, enrutadas a través de Discourse hacia el servidor externo

Registro de un servidor MCP

Navega a:

Admin → Plugins → Discourse AI → Tools → Pestaña MCP servers → New MCP server

Rellena los siguientes campos:

Campo Descripción
Name Una etiqueta legible (mostrada en el editor del agente y en los registros)
Description Para qué sirve este servidor (referencia para administradores)
URL El punto de conexión HTTPS del servidor MCP; debe ser una URL HTTPS pública, sin direcciones IP privadas
Authentication Una de las siguientes opciones: Sin autenticación, Credencial de encabezado o OAuth
Timeout (seconds) Tiempo que Discourse espera por solicitud; por defecto 30, máximo 300
Enabled Interruptor para desactivar temporalmente el servidor sin eliminarlo

:warning: Las URL deben usar HTTPS. localhost y las direcciones privadas RFC-1918 están bloqueadas (la protección SSRF se aplica del lado del servidor).

Opciones de autenticación

Sin autenticación

El servidor es accesible públicamente. No se envían credenciales.

Credencial de encabezado

Un valor secreto se inyecta como un encabezado HTTP en cada solicitud.

  1. Primero crea una Credential en Admin → AI → Credentials
  2. Selecciónala como Credential en el formulario del servidor MCP
  3. Establece el nombre del Auth header (por defecto: Authorization)
  4. Establece el prefijo opcional Auth scheme (por defecto: Bearer)

El encabezado de solicitud enviado al servidor MCP será:

Authorization: Bearer <tu-valor-secreto>

Puedes cambiar tanto el nombre del encabezado como el esquema para coincidir con cualquier estilo de autenticación que requiera tu servidor (por ejemplo, X-Api-Key: <valor> dejando el esquema en blanco).

OAuth

Discourse implementa un flujo completo de OAuth 2.0 + PKCE como cliente MCP. Esto soporta servidores MCP que protegen sus herramientas detrás de OAuth.

Pasos de configuración:

  1. Establece Authentication en OAuth
  2. Elige Client registration:
    • Client metadata document (por defecto) — Discourse publica su propio metadato de cliente OAuth en https://tu-sitio.com/discourse-ai/mcp/oauth/client-metadata. Si el servidor MCP soporta RFC 7591 Dynamic Client Registration, Discourse se registrará automáticamente
    • Manual client credentials — ingresa tu OAuth client ID pre-registrado y selecciona una credencial de OAuth client secret
  3. Opcionalmente establece OAuth scopes (separados por espacios)
  4. Guarda el servidor
  5. Haz clic en Connect — Discourse te redirigirá a través de la página de autorización del proveedor
  6. Después de autorizar, serás devuelto al panel de administración y el estado mostrará Connected

Opciones avanzadas de OAuth (activa “Show advanced options”):

Opción Propósito
OAuth authorization params Objeto JSON fusionado en la solicitud de autorización (ej. {"access_type":"offline"})
OAuth token params Objeto JSON fusionado en las solicitudes de intercambio de tokens
Require refresh token Fallar la conexión si el proveedor no devuelve un token de refresco

Discourse actualiza automáticamente los tokens de acceso antes de su expiración y reintenta en caso de 401 si hay un token de refresco disponible.

Probar la conexión

Antes de asignar un servidor a un agente, usa el botón Test connection en el formulario del editor. Esto inicializa inmediatamente una sesión MCP, llama a tools/list y devuelve:

  • Versión del protocolo MCP negociada
  • Número de herramientas descubiertas
  • Nombres de todas las herramientas

Si la prueba falla, se mostrará el mensaje de error del servidor (o un indicador de tiempo de espera) en línea.

Cómo Discourse descubre las herramientas

Discourse sigue la especificación MCP 2025-03-26. La secuencia de conexión es:

Discourse → POST /  { method: "initialize", params: { protocolVersion, capabilities, clientInfo } }
Server    → { result: { protocolVersion, capabilities } } + Encabezado Mcp-Session-Id
Discourse → POST /  { method: "notifications/initialized" }   (apretón de manos de sesión completado)
Discourse → POST /  { method: "tools/list", session_id: … }
Server    → { result: { tools: [ { name, description, inputSchema } … ] } }

Las definiciones de herramientas se almacenan en caché por 1 hora por servidor. Después de que la caché expira, un trabajo en segundo plano la actualiza transparentemente. La clave de caché es por sitio/servidor, por lo que las instalaciones multi-sitio están aisladas.

También puedes activar manualmente una actualización haciendo clic en Test connection; esto siempre obtiene datos en vivo.

El estado de salud del servidor (healthy / error) se actualiza en cada actualización de caché.

Asignación de servidores MCP a agentes de IA

Una vez registrado un servidor, asígnalo a un agente:

  1. Ve a Admin → Plugins → Discourse AI → Agents y edita o crea un agente
  2. Desplázate hasta la sección MCP servers (debajo de la sección regular de Tools)
  3. La lista muestra todos los servidores MCP habilitados con su recuento de herramientas y el costo estimado de tokens
  4. Activa un servidor; ahora está disponible para ese agente

Consejo: Por defecto, todas las herramientas de un servidor están disponibles para el agente. La cadena de localización lo dice bien: “Selected MCP servers expose all of their tools by default. Narrow them per agent to reduce token usage and keep tool choice focused.”

Selección de herramientas específicas por agente

Tener docenas de herramientas disponibles aumenta el costo de tokens de cada mensaje (cada definición de herramienta se envía al modelo en el prompt del sistema). Para mantener las cosas ligeras:

  1. En el editor del agente, junto a un servidor MCP asignado, haz clic en Choose tools
  2. Un modal muestra cada herramienta que el servidor expone actualmente, con su descripción y lista de parámetros
  3. Marca solo las herramientas que necesita este agente
  4. Haz clic en Guardar; el agente ahora solo verá el subconjunto seleccionado

La tabla de unión ai_agent_mcp_servers almacena selected_tool_names como un array JSONB. Un array vacío significa “todas las herramientas habilitadas”.

Nomenclatura de herramientas y resolución de conflictos

Los nombres de las herramientas MCP deben ser únicos dentro de la lista de herramientas de un solo agente (incluidas las herramientas integradas y de scripts personalizados del agente). Discourse maneja los conflictos automáticamente:

  • Si dos servidores MCP diferentes exponen una herramienta con el mismo nombre, Discourse las asigna a un espacio de nombres: servername__toolname
  • Si una herramienta integrada de Discourse y una herramienta MCP comparten un nombre, la herramienta MCP también se asigna a un espacio de nombres
  • Si aún hay colisiones después de la asignación de espacio de nombres, se agrega un sufijo numérico (_2, _3, …)

Por lo tanto, el function_name usado en la llamada del LLM puede diferir del tool_name crudo en el servidor MCP. Esto se maneja transparentemente; la clase de herramienta MCP siempre almacena el tool_name_value original por separado y lo usa al llamar al servidor.

Cómo funcionan las llamadas a herramientas en tiempo de ejecución

Cuando el LLM decide usar una herramienta MCP:

  1. Reutilización de sesión: Discourse busca un ID de sesión MCP en caché para este servidor en el contexto actual del bot (context.mcp_state). Las sesiones se crean por cadena de respuesta del bot y se reutilizan entre llamadas a herramientas hacia el mismo servidor.
  2. Inicializar si es necesario: Si no existe una sesión, se ejecuta un nuevo apretón de manos initialize + notifications/initialized.
  3. Llamar: POST / con { method: "tools/call", params: { name: tool_name, arguments: params } }
  4. Expiración de sesión: Si el servidor devuelve 404 (sesión expirada), Discourse se re-inicializa automáticamente y reintenta una vez.
  5. Normalización de respuesta: Los elementos de contenido MCP de tipo text se concatenan. Los elementos no textuales se serializan en JSON. structuredContent se imprime en JSON con formato.
  6. Resultado de error: Si el servidor devuelve isError: true, el bot recibe un mensaje de error en lugar de un resultado.

La respuesta del servidor puede ser JSON plano o un flujo SSE; Discourse maneja ambos.

Visualización del costo de tokens

En el editor del agente, cada servidor MCP asignado muestra un recuento estimado de tokens. Esto se calcula utilizando el tokenizador OpenAI cl100k_base aplicado a la firma JSON completa de cada herramienta (nombre + descripción + esquema de entrada). Esto es una aproximación; el costo real depende del tokenizador de tu LLM.

El desglose del costo de tokens se muestra para ayudarte a tomar decisiones informadas sobre qué servidores y herramientas asignar a un agente dado.

Solución de problemas

Síntoma Qué verificar
Test connection falla con timeout Aumenta Timeout (seconds). Por defecto es 30. Si el servidor es lento para inicializarse, prueba con 60–120.
Test tiene éxito pero las herramientas no aparecen en el agente Asegúrate de que el servidor esté Enabled y de que el agente lo tenga activado en su sección de servidores MCP.
El estado de OAuth muestra “Needs attention” El último error de OAuth se muestra en el formulario del editor. Causas comunes: token de refresco expirado (haz clic en Reconnect), el servidor devolvió scopes inesperados, o la URL de metadatos del cliente no es accesible desde tu servidor.
Los nombres de las herramientas se ven como myserver__sometool Normal; otra herramienta (integrada o de otro servidor) tenía el mismo nombre. El LLM ve y usa automáticamente este nombre con espacio de nombres.
La salud muestra “error” después de un tiempo El trabajo de actualización en segundo plano no pudo alcanzar el servidor. Revisa /logs en tu sitio y verifica que el servidor MCP sea accesible desde el host de Discourse.
Las herramientas dejaron de funcionar a mitad de la conversación Expiración de sesión. Discourse reintenta automáticamente una vez por llamada a herramienta, pero si el servidor se reinicia constantemente, acorta su TTL de sesión o investiga los registros del lado del servidor.

Para una depuración más profunda, habilita el acceso a las transcripciones de IA mediante ai_bot_debugging_allowed_groups e inspecciona el registro completo de la conversación.

Referencia técnica

Detalles del protocolo MCP

Propiedad Valor
Versión del protocolo 2025-03-26
Transporte HTTP POST (JSON-RPC 2.0)
Soporte SSE Sí (para respuestas en flujo de tools/call)
Gestión de sesiones Encabezado HTTP Mcp-Session-Id
Tamaño máximo de respuesta 5 MB
User-Agent del cliente Discourse AI MCP Client / <version>

Soporte de esquemas JSON

Discourse resuelve las siguientes construcciones de JSON Schema en las definiciones de inputSchema de las herramientas antes de pasarlas al LLM:

  • $ref — resuelto contra $defs / definitions del esquema raíz
  • allOf — fusionado (las propiedades y los arrays requeridos se unen)
  • anyOf / oneOf — se usa la primera variante que no sea null

Archivos de origen relevantes

Temas relacionados

:bulb: La función de Discourse como servidor MCP (discourse/discourse-mcp) es el complemento de esto: permite que clientes externos de IA (Claude Code, Cursor, etc.) lean y escriban en tu sitio de Discourse. Esta guía es la inversa; permite que tus agentes de IA de Discourse llamen a servidores MCP externos.

3 Me gusta
Bring your own MCP!