MCP nativo: Conexiones MCP, servidor de Maestro y cliente (Model Context Protocol)

Visión general

El MCP (Model Context Protocol) es el estándar abierto que permite a asistentes de IA (Claude, IDEs, agentes) usar herramientas y datos de sistemas externos de forma segura. Conversa Labs incorpora MCP nativo, y todo se opera desde pantallas — sin escribir integración.

Hay tres superficies:

• Conexiones MCP de la cuenta (perfiles de acceso) — en lugar de una única configuración de la cuenta, creas N perfiles con nombre. La conexión de Bearer estático de cada perfil tiene su selección de módulos, modo solo lectura, usuario de ejecución (miembro de la cuenta) y URL + secreto bearer propios. Esa conexión estática opera como el usuario de ejecución y solo puede restringir lo que ya puede hacer, nunca ampliarlo. Cuando la instalación habilita OAuth nativo, el mismo perfil también tiene una URL OAuth separada: las herramientas siguen limitadas por el perfil, pero cada llamada opera como el miembro que aprobó el consentimiento OAuth — nunca como el usuario estático del perfil.
• Servidor MCP de Maestro — expone los departamentos de Maestro como herramientas ask_<departamento> a clientes externos, con un token por cuenta. El cliente nunca gana más autonomía de la que el departamento ya tiene configurada.
• Robot como cliente MCP — cada robot puede consumir servidores MCP externos (Linear, Notion, Stripe, GitHub, un ERP interno) como herramientas adicionales, con las mismas reglas de aprobación (HITL), presupuesto de herramientas y auditoría que el resto.

La conexión estática de la cuenta y el servidor de Maestro usan la cabecera estándar Authorization: Bearer <credencial>. Los ejemplos siguientes configuran ese camino estático: en la cuenta, la credencial es el secreto del perfil; en Maestro, el token de Maestro. Son ejemplos de configuración, no una prueba de que todos los productos o versiones estén validados en esta instalación. El OAuth nativo de cuenta es un recurso separado y condicional, con discovery, PKCE y consentimiento en el navegador; no dirijas un cliente OAuth a la URL estática ni supongas compatibilidad sin probarla.

Identidad visual del conector

Durante la inicialización MCP con el protocolo 2025-11-25, el servidor envía el nombre y el título de la instalación, descripción, sitio web e iconos de marca (uno principal y variantes clara/oscura). Las pantallas de inicio de sesión y consentimiento OAuth usan la misma identidad; si la imagen configurada no carga, muestran las iniciales de la instalación. Estos metadatos solo se publican cuando existe un origen canónico público y seguro en HTTPS. Sin él, el servidor omite URL e iconos en vez de exponer una dirección interna o no confiable.

El cliente decide si muestra estos campos y cómo hacerlo. Los clientes que negocian una versión MCP más antigua todavía reciben el nombre técnico del servidor, pero ese protocolo no puede transportar iconos. En el Conector personalizado de Claude, usa el nombre introducido en su configuración: la interfaz puede seguir mostrando ese nombre hasta que use los metadatos del servidor. La apariencia no modifica scopes, consentimiento ni credenciales.

Los endpoints de Cuenta, Plataforma y Super Admin construyen esta instantánea segura en cada inicialización MCP. Después de cambiar White Label o el emisor canónico, la misma instantánea versionada se encola para el endpoint directo de Maestro; la siguiente solicitud autenticada usa la instantánea válida persistida más reciente. Una indisponibilidad temporal de Maestro nunca revierte la marca guardada: el reconciliador programado vuelve a intentarlo. Si el proveedor ya creó un conector, desconéctalo y agrega el servidor de nuevo para forzar otro initialize; esto no rota tokens ni cambia permisos. La URL del icono debe ser un recurso de primera parte de ese mismo origen canónico, público, HTTPS y accesible sin inicio de sesión; un CDN externo u otro host no se publica como metadato de marca MCP. Un cliente de terceros puede conservar el icono en caché u optar por no renderizar metadatos de icono MCP; el servidor no puede sustituir ese comportamiento.

Requisitos previos

• La función MCP habilitada para la cuenta. Sin la flag, la página Ajustes → MCP simplemente no aparece en el menú (y el interruptor global de la instalación también debe estar activado).
• Perfil de administrador de la cuenta para gestionar las Conexiones MCP (la página y la creación/edición de perfiles son solo para administradores).
• Para la conexión de la cuenta: ningún token personal. Cada perfil (Conexión MCP) genera su propio secreto bearer al crear/rotar — esa es la credencial del cliente. El usuario de ejecución del perfil debe ser miembro de la cuenta. Los tokens de robot (AgentBot) y el token personal de API no son la credencial de la conexión de la cuenta.
• Para la conexión opcional de OAuth nativo de la cuenta: el responsable de la instalación debe habilitar OAuth nativo de MCP, aplicar las migraciones de base de datos de OAuth MCP de esta versión y configurar un emisor público HTTPS válido, además de la función MCP de la cuenta y el interruptor global. Una flag no sustituye la migración del esquema ni prueba el flujo. La URL OAuth es distinta de la conexión estática; el secreto estático del perfil nunca la autentica. Quien aprueba el consentimiento en el navegador debe ser miembro activo de la cuenta.
• El host del emisor debe resolver y enrutar a través de la pasarela pública hacia esta misma instalación. Debe servir los endpoints MCP OAuth y los documentos de Metadatos de Recurso Protegido y discovery del servidor de autorización; una dirección HTTPS sintácticamente válida que enruta a otro lugar no basta.
• Antes de adoptar OAuth nativo en un cliente de terceros, prueba discovery, PKCE y consentimiento en un entorno controlado. Un endpoint basado en estándares no prueba que un producto, aplicación de escritorio o superficie de IA alojada soporte el flujo requerido.
• Para el servidor de Maestro: Maestro aprovisionado en la cuenta. Sin eso, la tarjeta de Maestro se sustituye por un aviso.
• Para conectar un servidor MCP externo por OAuth: el robot ya guardado y el navegador habilitado para abrir ventanas emergentes (la pantalla de consentimiento del proveedor se abre en una ventana).

Paso a paso

1. Abrir la página MCP

Ve a Ajustes → MCP. La pantalla muestra la tarjeta Conexiones MCP de la cuenta (los perfiles de acceso) y la tarjeta Servidor MCP de Maestro.

2. Crear una Conexión MCP (perfil de acceso)

En la tarjeta Conexiones MCP de la cuenta, pulsa Nuevo perfil. Cada perfil es una conexión independiente:

1. Dale un nombre al perfil (por ejemplo claude-code-soporte o bi-solo-lectura) — ayuda a identificar qué cliente usa cada conexión.

2. Elige el usuario de ejecución — un miembro de la cuenta. El perfil se ejecuta como ese usuario: la lista de herramientas efectiva es la intersección de tu selección con el techo del Super Admin y con los permisos de ese usuario. Es decir, un perfil solo restringe — nunca concede más de lo que el usuario ya tiene. Solo pertenecen a este servidor las rutas ancladas en /api/v{N}/accounts/{account}: las rutas personales de perfil, MFA, sesiones y notificaciones quedan fuera de la conexión de la cuenta, incluso cuando el usuario también pertenece a otras cuentas.

3. Elige los módulos que se exponen. Es el mismo selector de siempre: toda la plataforma (más de 100 módulos), organizada en áreas plegables: Conversaciones y atención, Contactos y CRM, Catálogo y ventas, Pagos, Tareas y agenda, WhatsApp, Canales e integraciones, Automatización e IA, Growth y ventas, Informes, Equipo y administración y Contenido. Usa la búsqueda para encontrar un módulo por su nombre o descripción, y el Seleccionar todo de cada área para activarla entera de una vez. Cada fila indica qué hace el módulo y cuántas herramientas agrega (el precio de la casilla); el resumen bajo la búsqueda suma la selección actual y avisa si supera el tope de herramientas — que sigue valiendo por perfil:

   Algunos ejemplos (la lista completa está en pantalla, por área):

   Ejemplo de módulo	Qué expone
   Conversaciones	leer, responder, cambiar estado, asignar, aplicar etiquetas (activado por defecto)
   Contactos	buscar, crear y actualizar contactos (activado por defecto)
   Informes	métricas y análisis (solo lectura)
   Tareas	módulo nativo de tareas
   Ítems de CRM	negocios y pipeline
   Centro de Ayuda	artículos de la base de conocimiento
   Catálogo	productos
   Follow-up	cadencias de follow-up
   Biblioteca de Medios	archivos de medios

   Los toolsets activos de fábrica llevan el distintivo default. Si el Super Admin no liberó un toolset en el techo global, la fila aparece deshabilitada y con el distintivo bloqueado por el super admin — no puedes marcarla.

   Encima de la lista hay atajos de punto de partida: Esencial, Atención, Comercial y Todo. Solo suman módulos a la selección actual — no se quita nada, y ningún módulo desaparece de la lista porque un atajo no lo mencione. Usa uno para empezar y ajusta a mano; los módulos bloqueados por el techo siguen fuera, como siempre.

4. Modo solo lectura: marca la casilla para que el perfil exponga solo herramientas que leen datos (sin crear, actualizar ni borrar).

5. Compatibilidad con la investigación profunda de ChatGPT (opcional): el conector de investigación profunda de ChatGPT exige, por nombre, dos herramientas llamadas search y fetch, y rechaza un servidor que no las tenga. Marca la casilla solo en los perfiles que use ese conector. Las dos herramientas solo describen lo que el perfil ya expone — no otorgan ningún acceso adicional —, pero ocupan sitio en la lista de los demás clientes. Déjalo desactivado para Claude, Claude Code y clientes genéricos.

6. Guarda el perfil. En ese momento el secreto bearer se muestra en texto plano exactamente una vez (formato mcp_...) — cópialo al momento. Solo se guardan el hash y los cuatro últimos caracteres; la plataforma no vuelve a mostrar el secreto.

7. Copia la URL de la conexión. Su forma es https://TU-DOMINIO/api/v1/accounts/ID_DE_CUENTA/mcp/c/ID_PUBLICO, donde ID_PUBLICO es un identificador no secreto (un slug en la URL) — quien autentica es el secreto bearer, no la URL. Esta es la URL de Bearer estático.

Si la instalación habilitó OAuth nativo de MCP, el mismo perfil tiene otro recurso exacto: https://TU-DOMINIO/api/v1/accounts/ID_DE_CUENTA/mcp/oauth/c/ID_PUBLICO. No sustituyas mcp/c por esta ruta en un cliente estático existente y no pegues allí el secreto del perfil. El perfil sigue seleccionando las herramientas, pero las llamadas OAuth se ejecutan como el miembro que aprobó el consentimiento.

Después, cada perfil tiene, en la tarjeta, los botones Editar (cambia nombre, usuario de ejecución, módulos y modo solo lectura), Rotar token (genera un secreto nuevo e invalida el anterior al instante) y Eliminar. Desactivar o eliminar el perfil — o que el usuario de ejecución deje de ser miembro de la cuenta — hace que la conexión deje de responder (401/404).

3. Configurar el servidor MCP de Maestro

1. En la tarjeta Servidor MCP de Maestro, mira el estado: Token configurado o Aún sin token.
2. Pulsa Generar token (o Rotar token si ya existe uno).
3. El token en texto plano se muestra exactamente una vez — cópialo al momento. No se vuelve a mostrar. Rotar invalida el token anterior de inmediato.
4. Copia la URL del endpoint de Maestro (termina en /mcp).
5. Un cliente externo con esa URL + token ve una herramienta ask_<departamento> por cada departamento activo de la cuenta.

Si Maestro no está configurado en la cuenta, la tarjeta se sustituye por un aviso — aprovisiona Maestro antes.

4. Conectar un cliente MCP con Bearer estático

Esta sección configura solo la conexión de Bearer estático: usa Streamable HTTP, la URL estática del perfil del paso 2 (o la URL de Maestro del paso 3) y la credencial en la cabecera Authorization: Bearer .... En la cuenta es el secreto del perfil (el mcp_... revelado al crear o rotar); en Maestro es el token de Maestro. Los formatos de configuración de clientes cambian fuera de esta documentación; valida la versión exacta en un entorno controlado. Ningún snippet siguiente configura OAuth nativo.

Claude Code — desde la terminal:

claude mcp add --transport http helpdesk \
  https://TU-DOMINIO/api/v1/accounts/ID_DE_CUENTA/mcp/c/ID_PUBLICO \
  --header "Authorization: Bearer SECRETO_DEL_PERFIL"

O en el .mcp.json del proyecto:

{
  "mcpServers": {
    "helpdesk": {
      "type": "http",
      "url": "https://TU-DOMINIO/api/v1/accounts/ID_DE_CUENTA/mcp/c/ID_PUBLICO",
      "headers": { "Authorization": "Bearer SECRETO_DEL_PERFIL" }
    }
  }
}

Cursor — en ~/.cursor/mcp.json (global) o .cursor/mcp.json (proyecto):

{
  "mcpServers": {
    "helpdesk": {
      "url": "https://TU-DOMINIO/api/v1/accounts/ID_DE_CUENTA/mcp/c/ID_PUBLICO",
      "headers": { "Authorization": "Bearer SECRETO_DEL_PERFIL" }
    }
  }
}

VS Code (modo agente) — en .vscode/mcp.json:

{
  "servers": {
    "helpdesk": {
      "type": "http",
      "url": "https://TU-DOMINIO/api/v1/accounts/ID_DE_CUENTA/mcp/c/ID_PUBLICO",
      "headers": { "Authorization": "Bearer SECRETO_DEL_PERFIL" }
    }
  }
}

MCP Inspector — para depurar la conexión y ver la lista cruda de herramientas:

npx @modelcontextprotocol/inspector

En el panel: Transport Type = Streamable HTTP, URL = la URL de la conexión y, en Authentication, indica el Bearer Token — el secreto del perfil para la conexión de la cuenta, o el token de Maestro para el servidor de Maestro (o una cabecera Authorization con el valor Bearer <credencial>). Pulsa Connect y luego List Tools.

Windsurf — misma idea: servidor remoto con la URL de la conexión y headers con Authorization: Bearer SECRETO_DEL_PERFIL (o el token de Maestro).

En todos, el cliente ejecuta initialize, luego tools/list (lista las herramientas expuestas) y finalmente tools/call para ejecutar una. Si el cliente muestra menos herramientas de las esperadas, es el tope de exposición: usa search_tools para encontrar cualquier otra herramienta (devuelve su esquema) y call_tool para ejecutarla. Nada queda inalcanzable — solo fuera de la lista.

4a. Conectar el recurso OAuth nativo de la cuenta (condicional)

Esta es una ruta de conexión separada, disponible solo cuando OAuth nativo de MCP está habilitado en la instalación y la función/perfil MCP de la cuenta están disponibles. No convierte la conexión de Bearer estático y no es una alternativa para un secreto de perfil perdido.

1. Configura el cliente con la URL exacta del recurso OAuth: https://TU-DOMINIO/api/v1/accounts/ID_DE_CUENTA/mcp/oauth/c/ID_PUBLICO.
2. Comienza por los Metadatos de Recurso Protegido de ese recurso, no por una URL de host adivinada: https://TU-DOMINIO/.well-known/oauth-protected-resource/mcp/oauth/accounts/ID_DE_CUENTA/connections/ID_PUBLICO. Solo anuncian el servidor de autorización canónico mientras el recurso esté disponible.
3. Descubre el servidor de autorización en https://TU-DOMINIO/.well-known/oauth-authorization-server/oauth/mcp (o usa el emisor anunciado por los metadatos). El servidor usa Authorization Code público, PKCE S256 obligatorio, vínculo al recurso exacto y ningún secreto de cliente. Los metadatos de discovery declaran authorization_response_iss_parameter_supported: valida el emisor canónico devuelto en el parámetro iss en los callbacks de éxito y de error redireccionable. El handoff firmado del navegador acepta como máximo 1.024 bytes combinados entre sus valores de autorización persistidos (incluidos client_id, redirect_uri, resource y state). Mantén state corto y opaco; no intentes ampliar el flujo con URL o estados demasiado grandes.
4. Un cliente público puede usar Client ID Metadata público verificado (CIMD). Registro Dinámico de Clientes (DCR) es condicional y está apagado por defecto: solo aparece en discovery después de que un Super Admin habilite Dynamic Client Registration en MCP Settings. Si está apagado, discovery omite registration_endpoint y el registro devuelve 404 — eso no es una falla de OAuth. Cuando está activado, el operador revisa el cliente en MCP OAuth clients y puede desactivarlo; la desactivación confirmada, con razón y reautenticación, es irreversible y revoca la familia de consentimiento/tokens. DCR sigue siendo un camino de prueba gobernado, no una promesa de compatibilidad de proveedor. Nunca envíes a este flujo un secreto de perfil, token personal de API, credencial de Super Admin o secreto de cliente.
5. En el navegador, cuando una sesión activa del panel de la cuenta o de la Consola de Super Admin pertenece a un miembro de la cuenta destino, el servidor la valida y reutiliza: vas directamente a revisar el consentimiento sin escribir de nuevo la contraseña. La aprobación sigue siendo obligatoria. Una identidad Super Admin entra en este flujo solo cuando también tiene membresía en la cuenta, y el grant/token permanece limitado a la cuenta, al perfil y a los scopes — no hereda autoridad global. Si la sesión falta, caducó, no es válida o pertenece a otra cuenta, aparece el formulario manual y exige una identidad de miembro válida. mcp:read es el alcance de lectura; las herramientas de escritura también requieren mcp:write y un perfil que no sea de solo lectura. offline_access solicita explícitamente un refresh token rotativo.
6. En Ajustes → Perfil → Conexiones MCP, un miembro revisa y revoca sus propias conexiones aprobadas. Un administrador de cuenta revisa todos los grants de la cuenta y debe elegir una razón cerrada cuando revoca mediante el flujo administrativo. La revocación invalida la familia de credenciales conectada.

4b. Verificar el recurso público antes de conectar un cliente OAuth

Antes de abrir Claude.ai, Claude Code u otro cliente remoto, un operador puede verificar el contrato público sin proporcionar ninguna credencial:

ruby scripts/mcp_oauth_preflight.rb \
  --base-url https://TU-DOMINIO \
  --account-id ID_DE_CUENTA \
  --profile-public-id ID_PUBLICO

Para la autoridad separada de Super Admin, usa:

ruby scripts/mcp_oauth_preflight.rb \
  --base-url https://TU-DOMINIO \
  --super-admin

El verificador acepta solo un origen HTTPS público con nombre DNS (rechaza IP literal y host interno), no sigue redirecciones y comprueba los Metadatos de Recurso Protegido exactos, emisor y audiencia, discovery, Client ID Metadata (CIMD), PKCE S256, el parámetro de respuesta iss, scopes y el desafío 401 de un tools/list JSON-RPC sin Bearer. Cuando discovery anuncie DCR, también comprueba el endpoint exacto; la ausencia explícita porque el gate está apagado es un estado válido. Continúa con la prueba controlada solo cuando termine con RESULT: PASS. Si falla, corrige la publicación antes de conectar cualquier cliente. Ese resultado confirma la publicación del servidor; no prueba que un proveedor externo sea compatible.

No registra un cliente, no abre consentimiento, no intercambia/revoca un token y no cambia un perfil, grant o credencial. La instancia remota puede agregar su telemetría de auditoría normal sin secretos para discovery y el desafío 401; es observabilidad, no un cliente OAuth creado por el verificador.

Claude.ai — Conector personalizado

Después de que un operador habilite OAuth MCP y Ajustes → MCP muestre la Dirección de conexión OAuth del perfil, usa el área de conectores de Claude correspondiente a tu plan:

Usa este recorrido como prueba controlada de la versión de Claude disponible para tu organización. No ofrezcas la conexión a otras personas hasta registrar discovery, consentimiento, tools/list, una lectura y una revocación correcta.

El conector remoto de Claude alcanza el servidor desde la infraestructura en la nube de Claude, incluso cuando usas Claude Desktop. Por tanto el emisor debe ser HTTPS público y alcanzable fuera de una VPN/red privada; que solo sea accesible desde tu navegador no basta. Los conectores personalizados remotos están disponibles en Claude, Cowork y Claude Desktop en los planes Free, Pro, Max, Team y Enterprise; Free está limitado a un conector personalizado. Consulta también la guía actual de conectores remotos de Claude.

1. En Team/Enterprise, Owner o Primary Owner va a Organization settings → Connectors → Add → Custom → Web y registra la URL MCP remota. Luego cada miembro va a Customize → Connectors y pulsa Connect. En Free/Pro/Max, usa Customize → Connectors → + → Add custom connector en tu propia cuenta (Free permite un conector).
2. Dale un nombre claro, por ejemplo Conversa Labs — Soporte, y pega la Dirección de conexión OAuth en URL MCP remota. No uses la URL Bearer estática.
3. Advanced settings es opcional. En este servidor de cliente público, nunca rellenes Client Secret ni uses token Bearer, secreto del perfil o credencial de Super Admin en ningún campo. Si la versión de Claude necesita DCR, habilítalo explícitamente antes mediante Super Admin; de lo contrario debe usar CIMD o un cliente ya provisionado.
4. Añade el conector, inicia sesión como miembro activo de la cuenta y lee/aprueba el consentimiento. Claude actúa como esa persona, limitado por el perfil, sus propios roles y los scopes.

El callback lo controla el cliente y es información de registro, no una URL que debas sustituir manualmente en el recurso MCP. Registra la versión de Claude y el callback recibido en la prueba; no pongas tokens, códigos ni parámetros de callback en la evidencia.

Para desconectar, revoca el grant en Ajustes → Perfil → Conexiones MCP (o, como administrador, desde la misma vista de cuenta). No rotes un token bearer estático: es otro tipo de conexión y no desconecta Claude OAuth.

No marques un producto de terceros como compatible solo porque ofrece MCP u OAuth. Valida producto, versión, redirección y resultado del consentimiento de punta a punta antes de permitirlo a usuarios.

Matriz de conectores externos — prueba controlada

Todas las filas siguientes están sin validar en esta instalación. La matriz explica cómo preparar un intento seguro; no declara soporte del proveedor. Empieza siempre con mcp:read, initialize, tools/list y una lectura sobre datos de prueba. Prueba una escritura solo después de autorización explícita.

El recurso OAuth de Super Admin es otro plano de autoridad y usa otra URL; nunca sustituyas la URL de Cuenta anterior por /super_admin/mcp/oauth. Sigue el artículo de Operador y realiza una prueba separada. Registra versión, plan/entitlement, resultado de discovery, consentimiento, tools/list, lectura, evento de auditoría, revocación y la llamada denegada — sin copiar tokens, códigos, verificadores ni URLs con parámetros de autorización.

Claude Code: la autorización local usa un callback loopback con puerto efímero. La política de redirect RFC 8252 restringida para ese callback ya tiene matcher y prueba HTTP locales; una URL fija localhost/127.0.0.1 no representa por sí sola el puerto real. Esto no prueba compatibilidad: el E2E externo sigue bloqueado hasta disponer de emisor HTTPS público, Inspector y evidencia del cliente real.

5. Dar servidores MCP externos a un robot (el robot como cliente)

1. Ve a Ajustes → Robots, abre el robot y busca la sección Servidores MCP.
2. Pulsa Añadir servidor y completa:
   • Nombre técnico — letras minúsculas, números y _, empezando por letra (2 a 33 caracteres), por ejemplo github. Prefija las herramientas de ese servidor.
   • URL del servidor MCP (la que publica el proveedor).
   • Transporte: Streamable HTTP (recomendado) o SSE (legado).
   • Timeout en segundos.
3. Autenticación: elige el tipo — ninguna, bearer, header, query, basic u OAuth. En los tipos con secreto, indica el nombre del secreto — nunca el valor. El valor queda en la bóveda de secretos y nunca se envía al modelo. El tipo OAuth no tiene campo de secreto: la credencial se obtiene en el paso 6.
4. Cabeceras adicionales (opcional): pares clave/valor, solo si el servidor las exige.
5. Marca Exigir aprobación (HITL) para que toda llamada a las herramientas de ese servidor pase por aprobación humana.
6. Pulsa Descubrir: la plataforma se conecta al servidor en ese momento y lista sus herramientas antes de guardar. Los servidores grandes (Linear, Notion) devuelven decenas de herramientas con descripciones largas — usa la búsqueda y Seleccionar todo / Limpiar para curar sin recorrer toda la lista; el contador indica cuántas marcaste. Puedes seleccionar un subconjunto (allowlist) — si no seleccionas ninguna, quedan disponibles todas las herramientas de ese servidor.
7. Guarda el robot. Las herramientas se descubren y almacenan al guardar; el turno del agente nunca hace descubrimiento de red.

Para que el descubrimiento resuelva secretos ya almacenados, guarda el robot primero y luego pulsa Descubrir.

6. Conectar un servidor externo por OAuth (botón Conectar)

Algunos servidores (Notion, por ejemplo) solo aceptan OAuth — no existe clave estática. En esos casos:

1. En el servidor MCP del robot, elige Autenticación → OAuth. Los campos de secreto desaparecen — no hay nada que rellenar.
2. Guarda el robot (la conexión se guarda por robot + nombre del servidor).
3. Pulsa Conectar. Se abre inmediatamente una ventana de autorización neutra; mantenla abierta. Cuando la plataforma recibe la dirección del proveedor, esa ventana navega a la pantalla de consentimiento en un contexto aislado: el proveedor no puede acceder a la pestaña del Studio. Inicia sesión y autoriza.
4. La ventana se cierra sola al terminar y el estado pasa a Conectado (con la validez y el alcance, cuando el proveedor los informa). Si permanece abierta después de la confirmación del proveedor, ciérrala para que el Studio pueda consultar el estado. Si el navegador bloquea la ventana, permite popups para este sitio e inténtalo de nuevo.
5. Pulsa Descubrir y sigue normalmente: las herramientas del servidor ya valen para el robot.
6. Desconectar olvida las credenciales de ese par robot + servidor. Para cambiar de cuenta en el proveedor: desconecta y conecta de nuevo.

Las credenciales OAuth quedan cifradas en Maestro, atadas al par robot + servidor. Nunca se guardan en Conversa Labs, nunca aparecen en pantallas ni registros y nunca se envían al modelo.

Configuración y opciones

• Perfiles (Conexiones MCP) de la cuenta: cada perfil tiene nombre, usuario de ejecución estático, selección de toolsets, modo solo lectura, URL estática (con public_id) y secreto bearer propio (revelado una sola vez, rotable). La selección estática efectiva es siempre selección ∩ techo del Super Admin ∩ permisos del usuario de ejecución.

• OAuth nativo de cuenta (condicional): el recurso OAuth es la URL separada /mcp/oauth/c/ID_PUBLICO. Usa la superficie de herramientas del perfil, pero al miembro que consintió, no al usuario estático. Sus grants son visibles/revocables en Ajustes → Perfil → Conexiones MCP; los grants existentes siguen visibles para revocación si el servidor se deshabilita después.

• Modo solo lectura: por perfil, expone solo herramientas de lectura.

• Compatibilidad con la investigación profunda de ChatGPT: por perfil, añade las dos herramientas search y fetch que ese conector exige por nombre. Solo describen lo que el perfil ya expone. Cuestan dos plazas del límite de herramientas (el servidor reserva cuatro en vez de dos cuando está activo), así que déjalo desactivado para Claude y clientes genéricos.

• Límite de herramientas: hay un tope por servidor (512), aplicado por perfil — recorta la lista, no el acceso. Las meta-herramientas search_tools (descubre, con el esquema) y call_tool (ejecuta por nombre) alcanzan todo lo que el perfil habilitó, respetando el modo solo lectura, los permisos del usuario de ejecución y el techo del Super Admin.

• Token de Maestro: uno por cuenta, revelado una sola vez, rotable en cualquier momento.

• Servidores externos por robot: nombre técnico, URL, transporte, timeout, autenticación, cabeceras extra, aprobación (HITL) y allowlist de herramientas.

• Tipos de autenticación (servidor externo):

  Tipo	Cómo funciona	Cuándo usarlo
  ninguna	no se envía nada	servidores realmente públicos (raro)
  bearer	envía Authorization: Bearer <secreto>	el caso más común — el secreto guarda la clave de API
  header	envía una cabecera con el nombre que elijas y el valor del secreto	el proveedor usa un esquema propio
  query	envía el secreto como parámetro en la URL	proveedores heredados
  basic	usuario + contraseña (dos secretos)	servidores internos
  OAuth	botón Conectar → consentimiento en el proveedor	el proveedor solo acepta OAuth (Notion)

• Presupuesto de herramientas: las herramientas de cada servidor externo cuentan en el presupuesto de herramientas del robot — demasiados servidores revientan el límite.

• Protección SSRF: las direcciones privadas/internas están bloqueadas al añadir un servidor externo.

Casos de uso

• Operar la bandeja de entrada desde Claude Code o un IDE: listar conversaciones, responder, resolver.
• Un perfil por cliente: cada IDE, script o socio recibe su propia conexión, con alcance mínimo y — en los clientes de lectura — el modo solo lectura activado.
• Traer los informes de la cuenta a un asistente mediante un perfil solo lectura, ejecutado por un usuario de perfil restringido.
• Revocar un único cliente: rota (o elimina) el perfil de ese cliente — los demás perfiles siguen funcionando.
• Dar a un robot acceso a un sistema interno (ERP, base de conocimiento) mediante un servidor MCP externo, con aprobación humana en las acciones sensibles.
• Dejar que el robot abra incidencias en Linear o lea una base en Notion durante la atención.
• Dejar que el equipo de datos pregunte ask_riesgo / ask_financiero y reciba los hallazgos del departamento sin abrir el panel.

Consejos, límites y buenas prácticas

• Qué autenticación elegir en cada servidor externo popular (la mayoría responde 401 con un desafío OAuth, pero también acepta una clave de API normal en Authorization: Bearer — dejarlo en ninguna es la causa número 1 de que falle el descubrimiento):

  Servidor MCP externo	Autenticación a elegir
  Linear	bearer + secreto con la clave de API
  Stripe	bearer + secreto con la clave restringida
  GitHub	bearer + secreto con un token personal (PAT)
  Atlassian (Jira/Confluence)	bearer + secreto con el token de API
  Sentry	header con nombre Authorization y un secreto cuyo valor sea Sentry-Bearer TU_TOKEN
  Notion	OAuth (botón Conectar) — no acepta clave estática
  Servidor interno propio	lo que exija el servidor

• Secreto estático frente a consentimiento OAuth: el secreto estático del perfil lleva los permisos del usuario de ejecución estático — nunca más de lo que ya tiene. Un grant OAuth nativo opera como el miembro que consintió y queda vinculado al recurso OAuth exacto. Trata ambos como credenciales y no los intercambies entre las dos URLs.

• Un perfil por cliente: así das alcance mínimo a cada uno y puedes rotar/eliminar un perfil para cortar solo a ese cliente, sin tocar a los demás.

• Solo lectura primero: empieza cada perfil con el modo solo lectura activado y habilita la escritura por toolset a medida que confías en el cliente.

• Menos es más: expón solo los toolsets que el cliente realmente usa — listas enormes de herramientas empeoran las decisiones del modelo.

• Copia el secreto del perfil al momento: no se vuelve a mostrar. ¿Lo perdiste? Rota el token del perfil (el anterior se invalida al instante) y actualiza el cliente que lo usaba.

• Secretos por referencia: en servidores MCP externos, nunca pegues el valor del secreto en el campo — indica la clave del secreto.

• Copia el token de Maestro al momento: no se vuelve a mostrar. ¿Lo perdiste? Rota (y actualiza los clientes que usaban el anterior).

• Aprobación (HITL): para servidores externos que escriben en sistemas críticos, marca Exigir aprobación.

Solución de problemas

• El cliente muestra menos herramientas que los módulos que activé en el perfil: es el tope de exposición del servidor. Las demás siguen siendo accesibles: pide al cliente que use search_tools (encuentra la herramienta y devuelve su esquema) y call_tool (la ejecuta por nombre). Para verlas en la lista, desmarca módulos o pide al operador que suba el tope.
• La tarjeta de Maestro muestra una dirección interna (aviso ámbar): la instalación no declaró la dirección pública de Maestro. Un cliente en la misma máquina conecta; un IDE fuera de la red, no. El operador debe definir MAESTRO_PUBLIC_BASE_URL con la dirección pública de Maestro (y reiniciar la aplicación).
• El cliente conecta por la dirección pública de Maestro y recibe "Invalid Host header" (o un 421): Maestro solo acepta el Host que la instalación declaró. Es el mismo MAESTRO_PUBLIC_BASE_URL — una vez definido, el host público se acepta (la protección contra DNS rebinding sigue activa).
• Un conector aún muestra un icono antiguo o genérico: confirma que el origen canónico público HTTPS y la URL del icono cargan sin autenticación, guarda White Label y vuelve a conectar el proveedor para que ejecute initialize otra vez. El servidor conserva la última marca válida mientras Maestro reintenta tras una indisponibilidad temporal; el proveedor aún puede mantener caché o decidir no mostrar sus metadatos de icono.
• La página MCP no aparece en el menú: la función MCP está apagada para la cuenta (pídeselo al operador) o tu usuario no es administrador.
• 404 en el endpoint de la conexión: la función está apagada para la cuenta, el interruptor global de la instalación está desactivado, o el ID_PUBLICO de la URL no existe (perfil eliminado o desactivado).
• 401 en la conexión de la cuenta: el secreto del perfil es incorrecto o fue rotado (el anterior se invalida al instante), el perfil fue eliminado/desactivado, o el usuario de ejecución dejó de ser miembro de la cuenta. Usa el secreto revelado al crear/rotar el perfil — un token personal de API y un token de robot no son la credencial de esta conexión.
• Un cliente estático intenta iniciar sesión por OAuth: la URL estática de la cuenta termina en /mcp/c/ID_PUBLICO y acepta solo el secreto del perfil en Authorization: Bearer ...; no anuncia un servidor OAuth. Mantén ese cliente en la configuración de Bearer estático.
• El recurso OAuth o discovery devuelve 404: OAuth nativo está deliberadamente dark-shipped. Revisa la habilitación de OAuth nativo, la función/perfil MCP de la cuenta y el emisor público; luego empieza de nuevo por los Metadatos de Recurso Protegido exactos. No sustituyas por un secreto estático ni token de otro plano.
• La URL OAuth devuelve 401: falta el bearer OAuth, caducó, fue revocado o pertenece a otro recurso/plano de autoridad. Lee WWW-Authenticate: apunta a los Metadatos de Recurso Protegido exactos (e incluye invalid_token solo cuando se rechazó un Bearer enviado). Empieza de nuevo desde ese metadato; nunca pegues el secreto estático del perfil en esta URL.
• La URL OAuth devuelve 403: el bearer es válido, pero la llamada pidió una herramienta de escritura sin el scope mcp:write. Pide ese scope en el consentimiento y confirma que el perfil no sea de solo lectura; mcp:write tampoco expone herramientas fuera del perfil.
• La URL OAuth devuelve 413: la solicitud o respuesta JSON-RPC supera 1 MiB. Reduce la carga o usa paginación. Una solicitud grande se rechaza antes de ejecutarse; una respuesta grande se mide solo tras terminar la operación, así que no repitas una escritura a ciegas: revisa primero el recurso o la auditoría.
• Un cliente OAuth todavía no completa el consentimiento: registra cliente y versión, URI de redirección, resultado de discovery y código de error seguro en una prueba controlada. No evites PKCE, vínculo al recurso o consentimiento en navegador; la compatibilidad solo existe tras una prueba de punta a punta.
• Toolset en gris con el distintivo “bloqueado”: el Super Admin no liberó ese toolset en el techo global. Solo él puede liberarlo.
• Perdí el secreto del perfil: genera otro con Rotar token en el perfil — el anterior se invalida al instante.
• Perdí el token de Maestro: genera otro con Rotar token en la tarjeta de Maestro — el anterior se invalida al instante.
• El descubrimiento (“Descubrir”) falla con 401: casi siempre la autenticación sigue en ninguna. Elige bearer y apunta el secreto a la clave de API del proveedor (Sentry usa header; Notion usa OAuth).
• El descubrimiento falla por otro motivo: revisa la URL, el transporte (Streamable HTTP o SSE) y las credenciales; guarda el robot antes si la autenticación usa un secreto almacenado; las direcciones privadas/internas son rechazadas por la protección SSRF.
• El botón Conectar no abre nada: el navegador bloqueó la ventana emergente — habilita los pop-ups para el dominio y vuelve a pulsar.
• Conectado, pero la herramienta falla al cabo de un tiempo: la autorización del proveedor caducó — Desconecta y Conecta otra vez.
• Una herramienta externa falla en ejecución: el error vuelve como texto al agente (que se autocorrige) y nunca tumba el turno.
• ask_<departamento> responde “disabled”: el departamento está desactivado para la cuenta — actívalo en la pantalla del Cerebro (Account Brain).

Ver también

• SDK, API REST y MCP de Dashboard Apps
• Referencia de la API (Swagger/OpenAPI)
• Tokens REST, webhooks y autenticación
• Bots y el canal de API