HTTP OAuth MCP Server

Servidor MCP HTTP + SSE con OAuth

Introducción

Este repositorio proporciona una implementación de referencia para crear un servidor MCP remoto que admita los transportes HTTP y SSE transmitibles, autorizados con OAuth según la especificación MCP.

Tenga en cuenta que el servidor MCP en este repositorio está lógicamente separado de la aplicación que maneja los transportes SSE + HTTP del informe y de OAuth.

Como resultado, puede bifurcar fácilmente este repositorio y conectar su propio servidor MCP y credenciales OAuth para un servidor MCP SSE/HTTP + OAuth que funcione con su propia funcionalidad.

¿Pero por qué?

¡Excelente pregunta! La especificación MCP añadió la especificación de autorización basada en OAuth el 25 de marzo de 2025. Actualmente, al 1 de mayo de 2025:

• El SDK de Typescript contiene muchos de los componentes básicos para lograr un servidor MCP autorizado por OAuth con HTTP transmisible, pero no existe documentación ni tutorial sobre cómo construir dicho servidor.
• El SDK de Python no contiene ni una implementación del transporte HTTP transmisible ni una implementación de los bloques de construcción OAuth que están presentes en el SDK de Typescript.
• El transporte HTTP Streamable no es compatible con las aplicaciones host MCP como Cursor y Claude Desktop, aunque se puede integrar directamente en agentes escritos en JavaScript mediante la clase StreamableHttpClientTransport del SDK JS/TS.

En Naptha AI , realmente queríamos construir un servidor MCP autorizado por OAuth en el transporte HTTP transmitible y no pudimos encontrar ninguna implementación de referencia, así que decidimos construir uno nosotros mismos.

Dependencias

Bun , un entorno de ejecución de JavaScript rápido e integral, es el entorno de ejecución y gestor de paquetes recomendado para este repositorio. Se han realizado pruebas de compatibilidad limitadas con npm + tsc .

Descripción general

Este repositorio proporciona lo siguiente:

1. Un servidor MCP, que puedes reemplazar fácilmente con el tuyo propio
2. Una aplicación express.js que administra los transportes HTTP SSE y Streamable y la autorización OAuth.

Esta aplicación expresa es donde conectas tus credenciales y el servidor MCP.

Tenga en cuenta que si bien esta aplicación expresa implementa los puntos finales OAuth necesarios, incluidos /authorize y el punto final de metadatos del servidor de autorización ( RFC8414 ), no implementa un servidor de autorización OAuth.

Este ejemplo redirige OAuth a un servidor OAuth ascendente que admite el registro dinámico de clientes ( RFC7591 ). Para usar este ejemplo, necesitará su propio servidor de autorización. Recomendamos usar Auth0 ; consulte la sección "Configuración de OAuth" más adelante.

Configurando su servidor

Notas sobre OAuth y el registro dinámico de clientes

Para usar este ejemplo, necesita un servidor de autorización OAuth. ¡No lo implemente usted mismo! Para crear nuestra demostración, usamos Auth0 ; es una excelente opción, aunque existen muchas otras.

La especificación MCP exige compatibilidad con una característica poco común de OAuth, concretamente RFC7591 , el registro dinámico de clientes. Esta especificación especifica que los clientes y servidores MCP deben ser compatibles con el protocolo de registro dinámico de clientes, de modo que los clientes MCP (independientemente de dónde se encuentre su transporte de clientes) puedan obtener ID de cliente sin necesidad de registrar usuarios. Esto permite que los nuevos clientes (agentes, aplicaciones, etc.) se registren automáticamente en los nuevos servidores. Puede encontrar más información al respecto en la sección de autorización de la especificación MCP . Sin embargo, esto significa que, lamentablemente, no es posible acceder directamente a un proveedor como Google o GitHub, que no admiten el registro dinámico de clientes (requieren que los registre en su interfaz de usuario).

Esto te deja con dos opciones:

1. Elija un proveedor OAuth ascendente como Auth0 que le permita usar IDP de OIDC como Google y GitHub para la autenticación, y que admita el registro dinámico de clientes, o
2. Implemente usted mismo el registro dinámico de clientes en la aplicación (es decir, la aplicación Express se convierte no solo en un simple proxy OAuth, sino en un servidor OAuth completo o parcialmente completo). Cloudflare implementó algo similar para sus servidores Workers OAuth MCP, con lo que podríamos ampliar este proyecto más adelante. Puede encontrarlo aquí .

Para simplificar, hemos optado por la primera opción utilizando Auth0.

[!NOTA]
Dado que esta implementación utiliza como proxy el servidor OAuth de origen, el método predeterminado de reenviar el token de acceso desde el servidor OAuth al cliente expondría el token de acceso de origen del usuario al cliente de destino y al host MCP. Esto no es adecuado para muchos casos de uso, por lo que este método reimplementa algunas clases de @modelcontextprotocol/typescript-sdk para solucionar este problema.

Tenga en cuenta que, al usar el proxy del servidor de autorización ascendente, no devolvemos el token de autenticación del usuario final al cliente/host de MCP; en su lugar, emitimos el nuestro y permitimos que el cliente/host lo use para autorizar con nuestro servidor. Esto evita que un cliente o host malintencionado abuse del token o que se abuse de él si se filtra.

Configuración de OAuth con Auth0

Para comenzar con Auth0:

1. Crea una cuenta Auth0 en Auth0.com .
2. Crea al menos una conexión a un proveedor de identidad (IDP), como Google o GitHub. Puedes aprender a hacerlo aquí .
3. Promueva la conexión a una conexión a nivel de dominio . Dado que cada cliente MCP registra nuevos clientes OAuth, no puede configurar sus conexiones IDP por aplicación/cliente. Esto significa que sus conexiones deben estar disponibles para todas las aplicaciones de su dominio. Puede aprender cómo hacerlo aquí .
4. Habilite el registro dinámico de clientes (auth0 también lo llama "registro dinámico de aplicaciones"). Puede aprender cómo hacerlo aquí .

Una vez configurado todo esto, necesitará la siguiente información:

• su ID de cliente de Auth0
• su secreto de cliente Auth0
• su dominio de inquilino Auth0

Asegúrate de completar esta información en tu .env . Copia .env.template y actualiza los valores con tus configuraciones y secretos.

Ejecutando el servidor

Este repositorio incluye dos servidores independientes:

• Una implementación sin estado del servidor HTTP con capacidad de transmisión en src/app.stateless.ts . Esto solo admite el transporte HTTP con capacidad de transmisión y, en teoría, es adecuado para implementaciones sin servidor.
• Una implementación con estado de SSE y HTTP con capacidad de transmisión en src/app.stateful.ts . Esta aplicación ofrece ambos transportes, pero conserva el estado en memoria incluso al usar la estrategia de almacenamiento redis (las conexiones deben persistir en memoria), por lo que no es adecuada para implementaciones sin servidor ni para escalado horizontal trivial.

Puedes ejecutar cualquiera de ellos con bun :

Poniéndolo todo junto

Para probar nuestro servidor MCP con soporte HTTP y OAuth transmitible, tiene un par de opciones.

Como se mencionó anteriormente, el SDK de Python MCP no admite estas funciones, por lo que actualmente puede conectar nuestro servidor remoto a un host MCP como Cursor o Claude Desktop, o directamente a una aplicación TypeScript/JavaScript, pero no a una de Python.

Conectando su servidor a su host MCP (Cursor / Claude)

Dado que la mayoría de los hosts MCP no admiten HTTP transmitible (que es superior a SSE en varios sentidos) ni OAuth, recomendamos usar el paquete npm mcp-remote que manejará la autorización OAuth y conectará el transporte remoto a un transporte STDIO para su host.

El comando se verá así:

Tiene un par de opciones para la opción --transport :

• http-first (predeterminado): intenta primero el transporte HTTP y recurre a SSE si el HTTP falla con un error 404
• sse-first : intenta primero el transporte SSE, vuelve a HTTP si SSE falla con un error 405
• http-only : solo utiliza transporte HTTP, falla si el servidor no lo admite
• sse-only : solo utiliza transporte SSE, falla si el servidor no lo admite

[!NOTA] Si inicia la versión sin estado del servidor con src/app.stateless.ts , el transporte SSE no estará disponible, por lo que deberá usar --transport http-only . No se espera que el transporte SSE funcione si utiliza este punto de entrada.

Conectando su servidor a su agente

Puedes conectar tu servidor HTTP Streamable a un agente en JS/TS mediante StreamableHTTPClientTransport . Sin embargo, esto no funcionará con servidores protegidos por OAuth. En su lugar, debes usar el encabezado Authorization en el lado del cliente, con un token de acceso válido en el lado del servidor.

Puedes implementar esto con credenciales de cliente, claves API u otra herramienta. Este patrón no es compatible con este repositorio, pero se vería así con el SDK de Vercel AI :