## 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:

```bash
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:

```json
{
  "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):

```json
{
  "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`:

```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:

```bash
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**:

```bash
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:

```bash
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](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

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.

| Cliente | Requisitos externos | Pasos de prueba controlada | Revocación | Estado |
|---|---|---|---|---|
| **Claude.ai — Conector personalizado** | Plan Claude con conectores personalizados (Free: uno); en Team/Enterprise Owner/Primary Owner lo registra antes; emisor HTTPS público alcanzable desde la nube de Claude y preflight aprobado | Usa la URL OAuth exacta, mantén Advanced settings opcional/sin secreto y completa navegador/PKCE/consentimiento | Revoca en **Ajustes → Perfil → Conexiones MCP** y confirma que la llamada siguiente falla | ⏳ sin validar |
| **Claude Desktop** | Claude Desktop actualizado y cuenta con conectores personalizados; el servidor también debe ser alcanzable desde la nube de Claude, no solo desde la máquina local | Configura solo la URL OAuth exacta y registra versión, sistema y callback/error seguro | Revoca el mismo grant y prueba otra llamada | ⏳ sin validar |
| **Codex** | La organización/producto es elegible para MCP remoto y su método actual de conexión está disponible | Añade solo la URL OAuth exacta en el flujo actual del producto; nunca uses un secreto Bearer como secreto de cliente | Revoca el grant y confirma la denegación posterior | ⏳ sin validar |
| **ChatGPT / GPT Platform** | Plan/workspace elegible, administrador o Developer Mode cuando aplique y autorización explícita para la prueba | Usa el flujo de connector/app realmente disponible, la URL OAuth exacta y consentimiento en navegador | Revoca el grant y confirma la denegación posterior | ⏳ sin validar |

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](/hc/ajuda/articles/api-developers-dashboard-apps-sdk-rest-mcp-es)
- [Referencia de la API (Swagger/OpenAPI)](/hc/ajuda/articles/api-developers-swagger-reference-es)
- [Tokens REST, webhooks y autenticación](/hc/ajuda/articles/api-developers-rest-tokens-webhooks-es)
- [Bots y el canal de API](/hc/ajuda/articles/api-developers-agent-bots-and-api-channel-es)