> ## Documentation Index
> Fetch the complete documentation index at: https://wondeya.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Conectar un cliente

> Apunta Claude, ChatGPT, Claude Code o cualquier cliente de MCP al servidor de wondeya

El servidor MCP de wondeya habla Streamable HTTP en `https://api.wondeya.com/mcp` y se autentica con **OAuth 2.1**. No creas ni pegas una credencial: apuntas un cliente a la URL, este descubre que el endpoint necesita OAuth, tu navegador se abre en wondeya y apruebas una pantalla de consentimiento. Como el inicio de sesión es un flujo de navegador, los asistentes de navegador se conectan igual que los agentes de código.

## Cómo funciona la conexión

Todo cliente sigue los mismos tres pasos, la mayoría invisibles:

<Steps>
  <Step title="Agrega el servidor por su URL">
    `https://api.wondeya.com/mcp`, como servidor **HTTP** (Streamable HTTP). Sin encabezado, sin token.
  </Step>

  <Step title="Inicia sesión cuando se abra el navegador">
    El cliente descubre que el endpoint necesita OAuth, se registra a sí mismo y abre wondeya en tu navegador. Inicia sesión si aún no lo hiciste.
  </Step>

  <Step title="Aprueba la pantalla de consentimiento">
    Una sola pantalla nombra al cliente, el **espacio de trabajo** al que se ligará la conexión, a ti y los permisos que solicita. Apruébala y el cliente queda conectado.

    La conexión se liga al espacio de trabajo **activo en tu sesión** en ese momento. Para conectar a un espacio de trabajo distinto, primero cambia de espacio de trabajo en la consola y luego inicia la conexión.
  </Step>
</Steps>

<Note>
  **Otorga los permisos más acotados que resuelvan la tarea.** Una conexión con solo `landings:read` y `knowledge:read` puede auditar un espacio de trabajo y no puede cambiar nada. Tu rol limita lo que puedes otorgar: un propietario o administrador puede otorgar lectura y escritura; un miembro puede otorgar solo lectura. [La introducción a MCP](/docs/es/mcp/introduction) lista cada permiso y lo que desbloquea.
</Note>

## Asistentes de navegador: Claude y ChatGPT

Agrega wondeya como **conector personalizado**, usando la misma URL. En la configuración de conectores del asistente, agrega un conector cuya URL sea `https://api.wondeya.com/mcp`; te enviará a wondeya para iniciar sesión y aprobar, y luego listará las herramientas. Este es el flujo para el que existe OAuth: sin encabezado que configurar, nada que guardar en tu máquina.

## Claude Code

Agrégalo con la CLI (sin encabezado esta vez, porque el handshake de OAuth lo reemplaza):

```bash theme={null}
claude mcp add --transport http wondeya https://api.wondeya.com/mcp
```

Ejecuta `/mcp` dentro de Claude Code y elige autenticarte: abre tu navegador para el inicio de sesión y el consentimiento, y luego muestra el servidor como conectado con sus herramientas. También puedes declararlo en el `.mcp.json` de un proyecto:

```json theme={null}
{
  "mcpServers": {
    "wondeya": {
      "type": "http",
      "url": "https://api.wondeya.com/mcp"
    }
  }
}
```

## Cualquier otro cliente que soporte MCP por HTTP

Editores y agentes como Cursor, Windsurf, VS Code, opencode y Codex toman la misma forma: un servidor HTTP en la URL, **sin** encabezado `Authorization`. Cuando el cliente llega por primera vez al endpoint, dispara el inicio de sesión en el navegador, y una vez que apruebas, él mismo guarda el token.

```json theme={null}
{
  "mcpServers": {
    "wondeya": {
      "type": "http",
      "url": "https://api.wondeya.com/mcp"
    }
  }
}
```

Las dos cosas que importan en todas partes son la URL y el transporte (HTTP, no stdio). Si tu cliente no puede ejecutar el flujo OAuth de navegador, usa el puente stdio de más abajo; este realiza el handshake por ti.

## Clientes que solo hablan stdio

Puentea el endpoint HTTP hacia un proceso stdio con `mcp-remote`, que ejecuta el handshake de OAuth en tu máquina y cachea el token:

```json theme={null}
{
  "mcpServers": {
    "wondeya": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.wondeya.com/mcp"]
    }
  }
}
```

La primera ejecución abre tu navegador para iniciar sesión y aprobar; después de eso el puente reutiliza el token cacheado y reenvía al mismo endpoint.

## Gestionar y revocar una conexión

Cada conexión aparece listada en la consola en **Configuración → Aplicaciones conectadas**, con los permisos que tiene. Revócala ahí; la revocación surte efecto en la siguiente solicitud, y el cliente debe iniciar sesión de nuevo para reconectarse. No hay caché que esperar a que expire.

## Comprueba que funciona

Pídele a tu cliente que liste las herramientas del servidor. Todo cliente de MCP tiene una manera de mostrarlas, y `tools/list` es la respuesta autoritativa sobre lo que ofrece este servidor. Deberías ver las herramientas de agente, site key, proyecto, página, conocimiento, imagen, marca, tema y uso.

Una buena primera solicitud, porque es de solo lectura y prueba toda la cadena: **«lista las páginas en mi espacio de trabajo de wondeya».**

## Solución de problemas

| Qué ves | Qué significa |
| - | - |
| El navegador nunca se abre | Tu cliente no está ejecutando el flujo OAuth. Confirma que está configurado como servidor **HTTP** (no stdio) y que no hay ningún encabezado `Authorization` obsoleto configurado. Los clientes que no pueden hacer OAuth deberían usar el puente `mcp-remote`. |
| `401` con `wondeya.oauth.unauthorized` | No hay token válido: la conexión nunca se aprobó, o se revocó o expiró. Reconéctate y aprueba la pantalla de consentimiento. Toda causa responde igual a propósito. |
| Una herramienta responde `wondeya.oauth.insufficient_scope` | La conexión es válida pero no se le otorgó el permiso que esa herramienta necesita. Reconéctate y aprueba el permiso faltante. Verifica también tu rol, ya que un miembro puede otorgar solo lectura. |
| Un permiso aparece atenuado en la pantalla de consentimiento | Tu rol no puede otorgarlo. Un propietario o administrador otorga escritura; un miembro otorga solo lectura. |
| `405` al conectar | Tu cliente envió `GET` o `DELETE`. Este servidor es sin estado y acepta solo `POST`: elige el transporte Streamable HTTP, no SSE. |
| `429` | Superaste el límite por minuto de esta superficie. Reduce el ritmo del bucle; una ráfaga de handshakes más llamadas a herramientas es esperable, un bucle de reintentos apretado no. |
| El cliente se conecta pero no muestra herramientas | Está hablando con otra cosa. Confirma que la URL termina en `/mcp`. |
| Una herramienta responde con `isError` | Es un rechazo de negocio, no una conexión rota: lee el `code` del documento de problema y actúa en consecuencia. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.