Coloque servidores MCP detrás de la puerta de enlace MCP de Casdoor, de extremo a extremo

Esta guía describe un ejemplo completo: una empresa publica un servidor MCP para sus empleados, quienes lo utilizan desde ChatGPT, Claude, Cursor y VS Code. Casdoor es tanto la puerta de enlace frente al servidor como el servidor de autorización que inicia sesión a los usuarios. El propio servidor MCP no necesita código OAuth 2.0.

---

Resultados del aprendizaje

• Prepare una organización para que los clientes MCP se registren e inicien sesión allí.
• Registre un servidor MCP en Casdoor y decida quién puede usarlo y qué herramientas.
• Conecte los cuatro clientes MCP comunes.
• Sirva a varias organizaciones desde una instancia de Casdoor.
• Verifique, audite y revoque el acceso.

Requisitos

• Una instancia de Casdoor accesible desde Internet mediante HTTPS, por ejemplo, https://auth.example.com. Los conectores personalizados de ChatGPT y Claude lo llaman desde la nube.
• Un servidor MCP que hable el transporte HTTP Streamable, por ejemplo, https://tickets.example.com/mcp, protegido opcionalmente por un token bearer estático
• Acceso de administrador global a la consola de administración de Casdoor

---

El ejemplo

Acme ejecuta un servidor MCP para su sistema de tickets. Acme quiere:

• Que los empleados inicien sesión con su cuenta de Acme, a través de los métodos de inicio de sesión que Acme ya configuró en Casdoor.
• Que solo el equipo de soporte pueda usar el servidor.
• Que nadie pueda llamar a la herramienta delete_ticket a través de un cliente de IA.
• Que el token de API propio del servidor nunca salga de Casdoor.
• Que un administrador pueda ver y revocar cada cliente.

Paso 1: preparar la organización

1. En la consola de administración de Casdoor, vaya a User Management > Organizations y abra acme.
2. Active Use organization issuer. La organización se convierte en su propio servidor de autorización, con el emisor https://auth.example.com/orgs/acme y el documento de descubrimiento https://auth.example.com/.well-known/oauth-authorization-server/orgs/acme. Los clientes MCP que lo descubren se registran en acme e inician sesión a los usuarios en la página de inicio de sesión de acme.
3. Active Enable dynamic client registration. Esto permite a los clientes identificarse con un documento de metadatos del ID de cliente (Claude, VS Code, ChatGPT) o registrarse ellos mismos (Cursor, clientes antiguos). Solo un administrador global puede cambiar este interruptor.
4. Guarde la organización.

Sin Use organization issuer, la puerta de enlace nombra al emisor global de Casdoor como servidor de autorización, y los clientes se registran en built-in. Actívelo para todas las organizaciones distintas de built-in que publiquen servidores MCP.

Paso 2: decidir quién puede usar el servidor

La puerta de enlace permite el acceso a los usuarios de la organización del servidor que pueden iniciar sesión en la aplicación del servidor.

1. Vaya a Identity > Applications y agregue una aplicación en acme, por ejemplo, app-tickets. No necesita URLs de redirección: los clientes MCP no inician sesión en ella, solo lleva las reglas de acceso.
2. Para permitir el acceso solo al equipo de soporte, vaya a Authorization > Permissions y agregue un permiso en acme:
   • Resource type: Application
   • Resources: app-tickets
   • Groups o Roles: el equipo de soporte
   • Actions: Read, Effect: Allow

Sin ningún permiso en la aplicación, cualquier usuario de acme puede usar el servidor. Los administradores de acme y los administradores globales siempre pueden usarlo.

Paso 3: registrar el servidor MCP

1. Vaya a LLM AI > MCP Servers y añada un servidor en acme:

   Campo	Value
   Name	tickets
   URL	https://tickets.example.com/mcp
   Application	app-tickets
   Access token	El token de API del servidor de tickets, si lo necesita

2. Guarde el servidor y luego seleccione Sync bajo Tool. Casdoor obtiene la lista de herramientas del servidor.

3. Bloquee delete_ticket y guarde. La pasarela responde a una llamada a una herramienta bloqueada, o a una herramienta que no está en la lista, con un error y no la reenvía.

4. Copie la Base URL: https://auth.example.com/api/server/acme/tickets. Esta es la URL que los usuarios añaden a sus clientes MCP.

La pasarela elimina el encabezado Cookie y el encabezado Authorization del usuario de cada solicitud, y envía el Access token del servidor en su lugar. Casdoor nunca devuelve el token en sus respuestas de API.

nota

Para un servidor de una organización distinta de built-in, la URL debe ser una dirección pública de Internet: la pasarela se niega a alcanzar direcciones privadas y de bucle local en nombre de un inquilino. Para publicar un servidor MCP en su red interna, regístrelo en built-in.

Paso 4: verificar la cadena de descubrimiento

Cada cliente MCP sigue la misma cadena. Verifíquela con curl antes de conectar un cliente:

curl -i -X POST https://auth.example.com/api/server/acme/tickets

Casdoor responde HTTP 401 y nombra los metadatos del recurso protegido de este servidor:

WWW-Authenticate: Bearer realm="casdoor", resource_metadata="https://auth.example.com/.well-known/oauth-protected-resource/api/server/acme/tickets"

curl https://auth.example.com/.well-known/oauth-protected-resource/api/server/acme/tickets

{
  "resource": "https://auth.example.com/api/server/acme/tickets",
  "authorization_servers": ["https://auth.example.com/orgs/acme"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["openid", "profile", "email", "offline_access"]
}

curl https://auth.example.com/.well-known/oauth-authorization-server/orgs/acme

En este documento, verifique:

• issuer es https://auth.example.com/orgs/acme, el mismo valor que en authorization_servers.
• client_id_metadata_document_supported es true, y registration_endpoint termina en ?organization=acme.
• token_endpoint_auth_methods_supported contiene none, y code_challenge_methods_supported contiene S256.

Paso 5: conectar los clientes

Cada usuario añade la URL de la pasarela a su cliente e inicia sesión con su cuenta de Acme.

Cliente	Dónde añadir el servidor	Cómo se identifica	Guía
ChatGPT	Plugins > + > Add custom MCP server	CIMD https://chatgpt.com/oauth/client.json	Conectar ChatGPT
Claude Desktop, claude.ai	Customize > Connectors > Add custom connector	CIMD https://claude.ai/oauth/mcp-oauth-client-metadata	Conectar Claude
Claude Code	claude mcp add --transport http tickets <url>	CIMD https://claude.ai/oauth/claude-code-client-metadata	Conectar Claude
Cursor	~/.cursor/mcp.json	DCR	Conectar Cursor
VS Code	.vscode/mcp.json	CIMD https://vscode.dev/oauth/client-metadata.json	Conectar VS Code

Por ejemplo, en Cursor:

{
  "mcpServers": {
    "tickets": {
      "url": "https://auth.example.com/api/server/acme/tickets"
    }
  }
}

Y en VS Code:

{
  "servers": {
    "tickets": {
      "type": "http",
      "url": "https://auth.example.com/api/server/acme/tickets"
    }
  }
}

Un cliente que utiliza un documento de metadatos de ID de cliente obtiene una aplicación en Casdoor, con su URL como ID de cliente, la etiqueta cimd y un nombre que comienza con cimd_. Un cliente que se registra a sí mismo obtiene una aplicación por registro, con la etiqueta dcr. No crea aplicaciones para los clientes.

Qué protege al servidor

Comprobación	Dónde	Qué sucede de otra manera
El token pertenece a un usuario de acme	Pasarela	HTTP 401
El usuario puede iniciar sesión en app-tickets	Pasarela	HTTP 401
El token fue emitido para este servidor (RFC 8707)	Pasarela	HTTP 401: "El token de acceso es para otro recurso"
La herramienta está en la lista y permitida	Pasarela	Error JSON-RPC, la llamada no se reenvía
El cliente es un cliente que se registró a sí mismo	Todas las API	Sus tokens solo pueden llamar al flujo de inicio de sesión, /api/userinfo, /api/mcp y /api/server/*, nunca a las API de gestión

Los clientes solicitan el token con resource=https://auth.example.com/api/server/acme/tickets, y Casdoor pone esa URL en la reclamación aud. Un token para otro servidor MCP, incluso uno de la misma organización, no funciona aquí, por lo que un servidor malicioso no puede reproducir los tokens que recibe.

Servir varias organizaciones

Una instancia de Casdoor puede publicar servidores MCP para muchas organizaciones, por ejemplo, los clientes de un SaaS. Repita los pasos 1 a 3 para cada organización. Luego:

• Cada organización tiene su propio emisor, página de inicio de sesión, usuarios y permisos. Un usuario de globex no puede iniciar sesión en la página de acme ni usar los servidores de acme.
• Los documentos de metadatos de ID de cliente de ChatGPT, Claude y VS Code tienen una URL cada uno, utilizada por todas las organizaciones. Casdoor mantiene una aplicación compartida por URL en built-in y la sirve como una aplicación de la organización en la que el usuario inicia sesión. Cada organización aún debe activar Enable dynamic client registration para aceptar estos clientes.
• Los tokens llevan el emisor de la organización del usuario, incluso después de una renovación.
• Un cliente que se registra por sí mismo (DCR) se registra en la organización del documento de descubrimiento, mediante el parámetro organization del endpoint de registro.

Comprobar, auditar y revocar

• Clients: Identity > Applications lista los clientes con las etiquetas cimd y dcr. Elimine una aplicación dcr_ para eliminar un registro.
• Tokens: Auditing > Tokens lista cada token con su usuario, aplicación, ámbito y recurso. Elimine un token para desconectar a un cliente inmediatamente.
• Users: Prohíba a un usuario y sus tokens dejarán de funcionar en la puerta de enlace en la siguiente solicitud.
• Tools: Bloquee una herramienta en la página de edición del servidor. El cambio surte efecto en la siguiente llamada.

Permitir que los usuarios empresariales omitan el navegador

Cuando los empleados de una organización inician sesión a través de un proveedor de identidad empresarial como Okta, los clientes que admiten Enterprise-Managed Authorization (Claude Team y Enterprise) pueden obtener el token de la puerta de enlace sin iniciar sesión en el navegador: el proveedor de identidad emite un ID-JAG y Casdoor lo intercambia por un token de acceso. Consulte Enterprise-managed authorization.

Resolución de problemas

La puerta de enlace responde 401 tras el inicio de sesión

• El servidor no tiene una Application. Sin una, solo los administradores pueden usar el servidor. Seleccione una aplicación, consulte Step 2.
• Un permiso en la aplicación excluye al usuario.
• El usuario pertenece a otra organización distinta a la del servidor.
• El cliente solicitó el token para otro recurso. Compruebe la reclamación aud del token: debe ser la URL de la puerta de enlace.

El cliente inicia sesión a los usuarios en la organización incorrecta

Use organization issuer está desactivado, por lo que los metadatos de recursos protegidos nombran al emisor global. Actívelo y vuelva a conectar el cliente.

"no se aceptan los documentos de metadatos de ID de cliente"

Enable dynamic client registration está desactivado para la organización. Casdoor también debe poder acceder a la URL del documento del cliente a través de Internet.

La puerta de enlace responde 502

Casdoor no puede acceder a la URL del servidor. Compruebe la URL y, para una organización distinta de built-in, que sea una dirección pública.

Véase también

• The MCP server of Casdoor
• Registrar clientes dinámicamente
• Usar Casdoor como servidor de autorización de su propio servidor MCP
• Autorización gestionada por la empresa