Conexión de clientes MCP al servidor MCP de PipesHub

Esta guía cubre cómo conectar el servidor MCP remoto de PipesHub a Cursor, Claude Code, Gemini CLI, Codex CLI, Claude.ai (Web) y LibreChat usando credenciales OAuth estáticas o tokens de portador.

PipesHub expone un endpoint MCP remoto sobre Streamable HTTP en /mcp. Los clientes MCP se conectan directamente a este endpoint — sin necesidad de paquetes npm locales ni procesos stdio.

¿Agente de codificación? Comienza en Para agentes de codificación. Instala la habilidad en el repositorio del usuario con npx skills add pipeshub-ai/mcp-server (ver skills/pipeshub). Colaboradores que trabajan en este repositorio: lee AGENTS.md.

¿Buscas la referencia de herramientas? Ver TOOLS.md para descripciones, argumentos y una guía de decisión para cada herramienta que expone el servidor MCP (pipeshub_chat, pipeshub_search, pipeshub_get_record_content, pipeshub_download_record, pipeshub_directory, pipeshub_sources, pipeshub_agents).

¿Usas QM? QM no puede adjuntar un endpoint MCP de terceros — es un servidor MCP para su propio harness, no un cliente. Sigue Usar PipesHub con QM. El paquete de capa de despliegue en qm/ da a los agentes un comando pipeshub dentro de su sandbox; este paquete envía ese comando como un segundo bin.

Requisitos previos

• Una instancia de PipesHub en ejecución (autoalojada o en la nube)

• Una aplicación OAuth creada en PipesHub (ver Paso 1)

Related MCP server: Rocket.Chat MCP Server

Paso 1: Crear una aplicación OAuth en PipesHub

1. Inicia sesión en tu instancia de PipesHub como administrador

2. Navega a Configuración > Configuración de desarrollador > Aplicaciones OAuth

3. Haz clic en Crear aplicación OAuth

4. Completa los detalles de la aplicación:

   • Nombre: por ejemplo, Integración MCP

   • URIs de redirección: Añade todas las URIs de redirección para los clientes que planeas usar:

     Cliente	URI de redirección
     Cursor	cursor://anysphere.cursor-mcp/oauth/callback
     Claude Code	http://localhost:<PORT>/callback (por ejemplo, http://localhost:8080/callback)
     Claude.ai (Web)	https://claude.ai/api/mcp/auth_callback
     Gemini CLI	http://localhost:7777/oauth/callback
     LibreChat	http://localhost:3080/api/mcp/<server-identifier>/oauth/callback

Importante: Los ámbitos en MCP_SCOPES deben coincidir con los ámbitos otorgados a tu aplicación OAuth — una discrepancia resultará en un error de autorización.

5. Guarda la aplicación y copia el ID de cliente y el Secreto de cliente

Personalización de ámbitos predeterminados

Por defecto, PipesHub expone algunos ámbitos predeterminados en su endpoint de descubrimiento /.well-known/oauth-protected-resource/mcp. Puedes personalizar qué ámbitos se exponen configurando la variable de entorno MCP_SCOPES en tu instancia de PipesHub. Esto es útil para clientes como Claude Code que solicitan automáticamente todos los ámbitos expuestos.

Marcadores de posición

Reemplaza estos en todas las configuraciones a continuación:

La URL del endpoint MCP remoto es: PIPESHUB_INSTANCE_URL/mcp

Configuración MCP remota

Cursor admite OAuth estático para servidores MCP remotos mediante el objeto auth en mcp.json.

Configuración

Abre Configuración de Cursor > Herramientas e Integraciones > Nuevo servidor MCP, o edita el archivo .cursor/mcp.json de tu proyecto:

{
  "mcpServers": {
    "pipeshub": {
      "url": "PIPESHUB_INSTANCE_URL/mcp",
      "auth": {
        "CLIENT_ID": "YOUR_CLIENT_ID",
        "CLIENT_SECRET": "YOUR_CLIENT_SECRET",
        "scopes": [
          "org:read", "org:write", "org:admin",
          "user:read", "user:write", "user:invite", "user:delete",
          "usergroup:read", "usergroup:write",
          "team:read", "team:write",
          "kb:read", "kb:write", "kb:delete", "kb:upload",
          "semantic:read", "semantic:write", "semantic:delete",
          "conversation:read", "conversation:write", "conversation:chat",
          "agent:read", "agent:write", "agent:execute",
          "connector:read", "connector:write", "connector:sync", "connector:delete",
          "config:read", "config:write",
          "document:read", "document:write", "document:delete",
          "crawl:read", "crawl:write", "crawl:delete"
        ]
      }
    }
  }
}

Cursor descubrirá automáticamente los endpoints de autorización y token a través de los metadatos /.well-known/oauth-protected-resource/mcp de PipesHub.

Nota: Si se omite el campo scopes, Cursor obtiene /.well-known/oauth-protected-resource/mcp y solicita todos los scopes_supported listados allí. Para limitar el acceso, lista explícitamente solo los ámbitos que necesitas. También puedes controlar qué ámbitos se exponen en el lado del servidor — ver Personalización de ámbitos predeterminados.

Uso de variables de entorno

Usa la interpolación ${env:VAR} de Cursor para mantener los secretos fuera de los archivos de configuración:

{
  "mcpServers": {
    "pipeshub": {
      "url": "${env:PIPESHUB_INSTANCE_URL}/mcp",
      "auth": {
        "CLIENT_ID": "${env:PIPESHUB_CLIENT_ID}",
        "CLIENT_SECRET": "${env:PIPESHUB_CLIENT_SECRET}",
        "scopes": [
          "kb:read", "kb:write",
          "semantic:read", "semantic:write",
          "conversation:read", "conversation:write", "conversation:chat",
          "agent:read", "agent:write", "agent:execute",
          "connector:read", "connector:write",
          "config:read", "user:read"
        ]
      }
    }
  }
}

URI de redirección

Cursor usa una URI de redirección fija para todos los servidores MCP:

cursor://anysphere.cursor-mcp/oauth/callback

Registra esta como la URI de redirección permitida al crear la aplicación OAuth en PipesHub.

Solución de problemas de inicio de sesión OAuth

Si el navegador interno de Cursor no carga la página de inicio de sesión OAuth, copia la URL de autorización del navegador interno y pégala en tu navegador normal para completar el flujo de inicio de sesión.

Claude Code admite servidores MCP HTTP remotos con credenciales OAuth estáticas mediante --client-id, --client-secret y --callback-port.

PipesHub expone el descubrimiento en /.well-known/oauth-protected-resource/mcp, por lo que Claude Code descubre automáticamente los endpoints de autorización y token.

Importante: Claude Code no admite configurar ámbitos específicos. Obtiene /.well-known/oauth-protected-resource/mcp, lee la lista scopes_supported y solicita todos ellos. Tu aplicación OAuth en PipesHub debe tener acceso a todos los ámbitos listados en el endpoint de descubrimiento, de lo contrario la solicitud de autorización fallará. Para limitar los ámbitos expuestos, ver Personalización de ámbitos predeterminados.

Añadir con CLI

claude mcp add --transport http \
  --client-id YOUR_CLIENT_ID \
  --client-secret \
  --callback-port 8080 \
  pipeshub PIPESHUB_INSTANCE_URL/mcp

--client-secret sin valor solicita entrada enmascarada. Para omitir la solicitud, configura la variable de entorno MCP_CLIENT_SECRET:

MCP_CLIENT_SECRET=YOUR_CLIENT_SECRET claude mcp add --transport http \
  --client-id YOUR_CLIENT_ID \
  --client-secret \
  --callback-port 8080 \
  pipeshub PIPESHUB_INSTANCE_URL/mcp

Para que esté disponible en todos los proyectos:

claude mcp add --transport http --scope user \
  --client-id YOUR_CLIENT_ID \
  --client-secret \
  --callback-port 8080 \
  pipeshub PIPESHUB_INSTANCE_URL/mcp

Añadir con JSON

claude mcp add-json pipeshub '{
  "type": "http",
  "url": "PIPESHUB_INSTANCE_URL/mcp",
  "oauth": {
    "clientId": "YOUR_CLIENT_ID",
    "callbackPort": 8080
  }
}' --client-secret

Ámbito de proyecto (.mcp.json)

Crea un archivo .mcp.json en la raíz de tu proyecto. Este puede ser confirmado en el control de versiones (los secretos se mantienen fuera mediante variables de entorno):

{
  "mcpServers": {
    "pipeshub": {
      "type": "http",
      "url": "${PIPESHUB_INSTANCE_URL}/mcp",
      "oauth": {
        "clientId": "${PIPESHUB_CLIENT_ID}",
        "callbackPort": 8080
      }
    }
  }
}

Configura las variables de entorno antes de lanzar Claude Code:

export PIPESHUB_INSTANCE_URL="https://app.pipeshub.com"
export PIPESHUB_CLIENT_ID="your-client-id"

Nota: El secreto de cliente se almacena en el llavero del sistema, no en archivos de configuración. Se te pedirá que lo ingreses cuando te autentiques por primera vez mediante /mcp.

Autenticarse

Después de añadir el servidor, ejecuta /mcp dentro de Claude Code y sigue el flujo de inicio de sesión en el navegador. Los tokens se almacenan de forma segura y se renuevan automáticamente.

Verificar

claude mcp list
claude mcp get pipeshub

Gemini CLI admite servidores MCP remotos con OAuth mediante dynamic_discovery (el predeterminado), que descubre automáticamente los endpoints de autorización y token desde /.well-known/oauth-protected-resource/mcp de PipesHub.

Opción A: Archivo de configuración

Edita ~/.gemini/settings.json:

{
  "mcpServers": {
    "pipeshub": {
      "url": "PIPESHUB_INSTANCE_URL/mcp",
      "oauth": {
        "clientId": "YOUR_CLIENT_ID",
        "clientSecret": "YOUR_CLIENT_SECRET",
        "scopes": [
          "org:read", "org:write", "org:admin",
          "user:read", "user:write", "user:invite", "user:delete",
          "usergroup:read", "usergroup:write",
          "team:read", "team:write",
          "kb:read", "kb:write", "kb:delete", "kb:upload",
          "semantic:read", "semantic:write", "semantic:delete",
          "conversation:read", "conversation:write", "conversation:chat",
          "agent:read", "agent:write", "agent:execute",
          "connector:read", "connector:write", "connector:sync", "connector:delete",
          "config:read", "config:write",
          "document:read", "document:write", "document:delete",
          "crawl:read", "crawl:write", "crawl:delete"
        ]
      }
    }
  }
}

Nota: Ajusta la lista scopes para que coincida con lo que se otorgó a tu aplicación OAuth. Si solo necesitas un subconjunto de herramientas, puedes limitar los ámbitos en consecuencia.

Opción B: Comando CLI

gemini mcp add --transport http pipeshub PIPESHUB_INSTANCE_URL/mcp

Luego edita ~/.gemini/settings.json para añadir el bloque oauth como se muestra arriba.

Autenticarse

Dentro de Gemini CLI, usa los comandos /mcp auth:

# List servers and their auth status
/mcp auth

# Authenticate with PipesHub (opens browser for login)
/mcp auth pipeshub

# Re-authenticate if tokens expire
/mcp auth pipeshub

En la primera conexión, Gemini detectará automáticamente la respuesta 401, descubrirá los endpoints OAuth y abrirá un navegador para el inicio de sesión. Los tokens se almacenan de forma segura en ~/.gemini/mcp-oauth-tokens.json y se renuevan automáticamente.

Gestionar servidores

# List all configured servers
gemini mcp list

# Remove the server
gemini mcp remove pipeshub

# Temporarily disable/enable
gemini mcp disable pipeshub
gemini mcp enable pipeshub

Propiedades de configuración OAuth

Nota: OAuth requiere un navegador local. No funcionará en entornos sin interfaz gráfica, SSH remoto sin reenvío X11, o contenedores sin acceso a navegador.

Codex CLI (OpenAI Codex) se conecta a servidores MCP remotos sobre Streamable HTTP, configurado con una tabla [mcp_servers.<name>] en ~/.codex/config.toml (o .codex/config.toml en la raíz de tu proyecto para limitarlo por proyecto). El transporte HTTP de Codex se autentica con un token de portador leído de una variable de entorno, así que pasa un token de portador JWT de PipesHub.

[mcp_servers.pipeshub]
url = "PIPESHUB_INSTANCE_URL/mcp"
bearer_token_env_var = "PIPESHUB_BEARER_TOKEN"

bearer_token_env_var es el nombre de la variable de entorno que contiene el token — expórtala antes de lanzar Codex:

export PIPESHUB_BEARER_TOKEN="YOUR_BEARER_TOKEN"

El token es el JWT crudo, sin la palabra clave Bearer.

O añádelo con la CLI:

codex mcp add pipeshub \
  --url PIPESHUB_INSTANCE_URL/mcp \
  --bearer-token-env-var PIPESHUB_BEARER_TOKEN

--bearer-token-env-var toma el nombre de la variable de entorno que contiene el token, no el valor del token en sí.

Verificar

# List configured MCP servers
codex mcp list

# Inside the Codex TUI, view server status and available tools
/mcp

Claude.ai admite conectores personalizados mediante servidores MCP remotos. Esto te permite usar las herramientas de PipesHub directamente en la interfaz web de Claude.ai sin configuración local.

Nota: Esta función está actualmente en beta. Los usuarios del plan gratuito están limitados a un conector personalizado.

Para usuarios individuales (planes Pro / Max)

1. Ve a claude.ai y navega a Configuración > Conectores

2. Haz clic en Añadir conector personalizado en la parte inferior de la sección de Conectores

3. Ingresa la URL del servidor MCP:

   PIPESHUB_INSTANCE_URL/mcp

4. Haz clic en Configuración avanzada e ingresa tus credenciales OAuth:

   • ID de cliente OAuth: YOUR_CLIENT_ID

   • Secreto de cliente OAuth: YOUR_CLIENT_SECRET

5. Haz clic en Añadir

6. Serás redirigido a la página de inicio de sesión de PipesHub para autenticarte y otorgar permisos

7. Después de autenticarte, el conector estará activo y las herramientas de PipesHub estarán disponibles en tus conversaciones de Claude.ai

Para planes de equipo / empresa

Los propietarios de la organización deben primero añadir el conector:

1. Navega a Configuración de la organización > Conectores

2. Haz clic en Añadir conector personalizado

3. Ingresa la URL del servidor MCP: PIPESHUB_INSTANCE_URL/mcp

4. Haz clic en Configuración avanzada e ingresa el ID de cliente OAuth y el Secreto de cliente

5. Haz clic en Añadir

Los miembros del equipo pueden entonces conectarse:

1. Ve a Configuración > Conectores

2. Encuentra el conector de PipesHub (marcado con una etiqueta "Personalizado")

3. Haz clic en Conectar para autenticarte mediante el inicio de sesión OAuth de PipesHub

URI de redirección

Claude.ai usa la siguiente URI de redirección para OAuth:

https://claude.ai/api/mcp/auth_callback

Registra esta como una URI de redirección permitida en tu aplicación OAuth de PipesHub.

Notas de seguridad

• Solo conéctate a servidores MCP de confianza

• Revisa los permisos solicitados durante el flujo de autenticación OAuth

• Claude.ai interactúa con PipesHub en tu nombre usando el token OAuth otorgado — tu contraseña nunca se comparte

LibreChat admite servidores MCP remotos con autenticación OAuth mediante su interfaz de conectores personalizados. Esto te permite conectar las herramientas de PipesHub a cualquier modelo disponible en tu instancia de LibreChat.

Configuración

1. Inicia sesión en tu instancia de LibreChat

2. Navega al panel de configuración de MCP Servers

3. Haz clic en Add para crear un nuevo conector MCP personalizado

4. Rellena los detalles del conector:

   • Name: Pipeshub (o cualquier nombre que prefieras)

   • MCP Server URL: PIPESHUB_INSTANCE_URL/mcp

   • Transport: Selecciona Streamable HTTPS

   • Authentication: Selecciona OAuth

5. Introduce tus credenciales OAuth:

   • Client ID: YOUR_CLIENT_ID

   • Client Secret: YOUR_CLIENT_SECRET

   • Authorization URL: PIPESHUB_INSTANCE_URL/api/v1/oauth2/authorize

   • Token URL: PIPESHUB_INSTANCE_URL/api/v1/oauth2/token

   • Scope: openid email (o ámbitos adicionales según sea necesario)

6. Marca I trust this application

7. Haz clic en Add para guardar el conector

8. Después de añadirlo, LibreChat generará un Redirect URI que se mostrará en el panel de configuración del conector (junto al botón de copiar). Sigue este formato:

   http://localhost:3080/api/mcp/<server-identifier>/oauth/callback

9. Copia el Redirect URI y regístralo como URI de redirección permitida en tu aplicación OAuth de PipesHub (consulta Paso 1)

10. Vuelve al conector de LibreChat y haz clic en Update para iniciar el flujo OAuth: serás redirigido a la página de inicio de sesión de PipesHub para autenticarte y conceder permisos

Redirect URI

LibreChat genera el redirect URI después de que se cree el conector. El URI sigue este formato:

http://localhost:3080/api/mcp/<server-identifier>/oauth/callback

Donde <server-identifier> es el identificador único asignado por LibreChat (visible en la parte superior de la configuración del conector como "Unique Server Identifier"). Debes copiar este URI y añadirlo a los URI de redirección permitidos de tu aplicación OAuth de PipesHub antes de autenticarte.

Nota: Si tu instancia de LibreChat se ejecuta en un host o puerto diferente, el URI lo reflejará (por ejemplo, https://chat.example.com/api/mcp/pipeshub/oauth/callback).

Scopes

LibreChat te permite especificar los scopes de OAuth en el campo Scope. Usa una lista separada por espacios:

openid email

Para solicitar scopes específicos de PipesHub, añádelos al campo de scope:

openid email org:read kb:read kb:write semantic:read conversation:read conversation:write conversation:chat agent:read agent:execute

Nota: Los scopes que solicites deben coincidir con los scopes concedidos a tu aplicación OAuth en PipesHub. Consulta Customizing Default Scopes para más detalles.

Servidor MCP Local (Stdio)

En lugar de conectarte al endpoint MCP remoto de PipesHub, puedes ejecutar el servidor MCP localmente como un proceso stdio usando el paquete npm @pipeshub-ai/mcp. Esto es útil cuando prefieres una configuración local o necesitas trabajar en entornos donde las conexiones HTTP directas al endpoint MCP remoto no son prácticas.

Requisitos previos

• Node.js 18+ instalado

• Una URL de instancia de PipesHub

• Credenciales de autenticación: ya sea un Bearer token (JWT) o un OAuth Client ID + Secret

Marcadores de posición

Reemplaza estos valores en todas las configuraciones siguientes:

Configúralo en la configuración de Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "pipeshub": {
      "command": "npx",
      "args": [
        "@pipeshub-ai/mcp",
        "start",
        "--server-url",
        "PIPESHUB_INSTANCE_URL",
        "--bearer-auth",
        "YOUR_BEARER_TOKEN"
      ]
    }
  }
}

Con credenciales OAuth:

{
  "mcpServers": {
    "pipeshub": {
      "command": "npx",
      "args": [
        "@pipeshub-ai/mcp",
        "start",
        "--server-url",
        "PIPESHUB_INSTANCE_URL",
        "--client-id",
        "YOUR_CLIENT_ID",
        "--client-secret",
        "YOUR_CLIENT_SECRET",
        "--token-url",
        "/api/v1/oauth2/token"
      ]
    }
  }
}

Abre Cursor Settings > Tools and Integrations > New MCP Server, o edita el archivo .cursor/mcp.json de tu proyecto:

{
  "mcpServers": {
    "pipeshub": {
      "command": "npx",
      "args": [
        "@pipeshub-ai/mcp",
        "start",
        "--server-url",
        "PIPESHUB_INSTANCE_URL",
        "--bearer-auth",
        "YOUR_BEARER_TOKEN"
      ]
    }
  }
}

Con credenciales OAuth:

{
  "mcpServers": {
    "pipeshub": {
      "command": "npx",
      "args": [
        "@pipeshub-ai/mcp",
        "start",
        "--server-url",
        "PIPESHUB_INSTANCE_URL",
        "--client-id",
        "YOUR_CLIENT_ID",
        "--client-secret",
        "YOUR_CLIENT_SECRET",
        "--token-url",
        "/api/v1/oauth2/token"
      ]
    }
  }
}

claude mcp add pipeshub -- npx -y @pipeshub-ai/mcp start \
  --server-url PIPESHUB_INSTANCE_URL \
  --bearer-auth YOUR_BEARER_TOKEN

Con credenciales OAuth:

claude mcp add pipeshub -- npx -y @pipeshub-ai/mcp start \
  --server-url PIPESHUB_INSTANCE_URL \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET \
  --token-url /api/v1/oauth2/token

gemini mcp add pipeshub -- npx -y @pipeshub-ai/mcp start \
  --server-url PIPESHUB_INSTANCE_URL \
  --bearer-auth YOUR_BEARER_TOKEN

Con credenciales OAuth:

gemini mcp add pipeshub -- npx -y @pipeshub-ai/mcp start \
  --server-url PIPESHUB_INSTANCE_URL \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET \
  --token-url /api/v1/oauth2/token

Ejecuta el servidor MCP como un proceso stdio local, autenticado con el Client ID y Secret de una aplicación OAuth (la concesión client_credentials). Edita ~/.codex/config.toml (o .codex/config.toml en la raíz de tu proyecto):

[mcp_servers.pipeshub]
command = "npx"
args = [
  "-y",
  "@pipeshub-ai/mcp",
  "start",
  "--server-url",
  "PIPESHUB_INSTANCE_URL/api/v1",
  "--client-id",
  "YOUR_CLIENT_ID",
  "--client-secret",
  "YOUR_CLIENT_SECRET",
  "--token-url",
  "/api/v1/oauth2/token",
]

Notas:

• --server-url debe incluir /api/v1.

• --token-url /api/v1/oauth2/token es obligatorio.

O autentícate con un token Bearer JWT en su lugar:

[mcp_servers.pipeshub]
command = "npx"
args = [
  "-y",
  "@pipeshub-ai/mcp",
  "start",
  "--server-url",
  "PIPESHUB_INSTANCE_URL/api/v1",
  "--bearer-auth",
  "YOUR_BEARER_TOKEN",
]

Abre Command Palette > MCP: Open User Configuration y luego añade:

{
  "mcpServers": {
    "pipeshub": {
      "command": "npx",
      "args": [
        "@pipeshub-ai/mcp",
        "start",
        "--server-url",
        "PIPESHUB_INSTANCE_URL",
        "--bearer-auth",
        "YOUR_BEARER_TOKEN"
      ]
    }
  }
}

Abre Windsurf Settings > Cascade > Manage MCPs > View raw config y luego añade:

{
  "mcpServers": {
    "pipeshub": {
      "command": "npx",
      "args": [
        "@pipeshub-ai/mcp",
        "start",
        "--server-url",
        "PIPESHUB_INSTANCE_URL",
        "--bearer-auth",
        "YOUR_BEARER_TOKEN"
      ]
    }
  }
}

Para ejecutar el servidor MCP local desde un repositorio clonado en lugar del paquete npm:

git clone https://github.com/pipeshub-ai/pipeshub-ai.git
cd pipeshub-ai
npm install
npm run build
node ./bin/mcp-server.js start --server-url PIPESHUB_INSTANCE_URL --bearer-auth YOUR_BEARER_TOKEN

Para la configuración del cliente MCP, reemplaza npx @pipeshub-ai/mcp con node ./bin/mcp-server.js:

{
  "mcpServers": {
    "pipeshub": {
      "command": "node",
      "args": [
        "./bin/mcp-server.js",
        "start",
        "--server-url",
        "PIPESHUB_INSTANCE_URL",
        "--bearer-auth",
        "YOUR_BEARER_TOKEN"
      ]
    }
  }
}

Para depurar con MCP Inspector:

npx @modelcontextprotocol/inspector node ./bin/mcp-server.js start --server-url PIPESHUB_INSTANCE_URL --bearer-auth YOUR_BEARER_TOKEN

Ayuda de CLI

Para obtener una lista completa de los argumentos del servidor:

npx @pipeshub-ai/mcp --help

Cómo Funciona

Arquitectura

AI Client (Cursor / Claude Code / Gemini CLI / Codex CLI / Claude.ai / LibreChat)
        │
        │  HTTP POST (JSON-RPC)
        │  Authorization: Bearer <token>
        ▼
  PIPESHUB_INSTANCE_URL/mcp
        │
        │  StreamableHTTP Transport
        │  (stateless, per-request MCP server)
        ▼
  PipesHub API (curated tool set — see TOOLS.md)

Descubrimiento de Recursos Protegidos por OAuth

PipesHub expone el descubrimiento de recursos protegidos por OAuth en:

PIPESHUB_INSTANCE_URL/.well-known/oauth-protected-resource/mcp

Esto devuelve automáticamente todos los endpoints OAuth:

• Authorization: PIPESHUB_INSTANCE_URL/api/v1/oauth2/authorize

• Token: PIPESHUB_INSTANCE_URL/api/v1/oauth2/token

• Revocation: PIPESHUB_INSTANCE_URL/api/v1/oauth2/revoke

• JWKS: PIPESHUB_INSTANCE_URL/.well-known/jwks.json

Solución de Problemas

"Incompatible auth server: does not support dynamic client registration"

Esto significa que el cliente está intentando un registro dinámico en lugar de usar tus credenciales preconfiguradas. Asegúrate de haber pasado --client-id y --client-secret (Claude Code) o el objeto auth (Cursor) correctamente.

La autenticación falla / error de redirección

• Asegúrate de que el Redirect URI en tu aplicación OAuth coincida exactamente con el que usa el cliente:

  • Cursor: cursor://anysphere.cursor-mcp/oauth/callback

  • Claude Code: http://localhost:<callbackPort>/callback

  • Claude.ai: https://claude.ai/api/mcp/auth_callback

  • Gemini CLI: http://localhost:7777/oauth/callback

  • LibreChat: http://localhost:3080/api/mcp/<server-identifier>/oauth/callback

• Asegúrate de que la aplicación OAuth esté activa (no suspendida) en PipesHub

No se puede acceder al endpoint MCP

• Verifica que el endpoint sea accesible: curl -X POST PIPESHUB_INSTANCE_URL/mcp (debería devolver 401, no un error de conexión)

• Comprueba que tu instancia de PipesHub tenga MCP habilitado

Depuración con MCP Inspector

npx @modelcontextprotocol/inspector

Luego conéctate a PIPESHUB_INSTANCE_URL/mcp con un token Bearer para probar el endpoint directamente.

Preguntas Frecuentes

1. Actualiza la variable de entorno MCP_SCOPES en tu instancia de PipesHub para incluir los nuevos scopes que quieras exponer a través del endpoint de descubrimiento.

2. Actualiza los scopes de la aplicación OAuth en PipesHub: ve a Settings > Developer Settings > OAuth Apps, selecciona tu aplicación OAuth y añade o elimina scopes según sea necesario.

3. Vuelve a autenticar el cliente: los tokens existentes llevan los scopes antiguos, por lo que necesitas reautenticarte para obtener un token nuevo con los scopes actualizados. Por ejemplo:

   • Cursor: Elimina y vuelve a añadir el servidor MCP, o borra el token OAuth en caché y vuelve a conectarte.

   • Claude Code: Ejecuta /mcp y completa el flujo de inicio de sesión en el navegador de nuevo.

   • Gemini CLI: Ejecuta /mcp auth pipeshub para reautenticarte.

   • Codex CLI: Actualiza PIPESHUB_BEARER_TOKEN con un token nuevo y reinicia Codex.

   • Claude.ai: Desconecta y vuelve a conectar el conector en Settings > Connectors.