Servidor MCP remoto con GitHub OAuth

Servidor de Protocolo de Contexto de Modelo (MCP) + Github OAuth

Este es un servidor de Protocolo de contexto de modelo (MCP) que admite conexiones MCP remotas, con Github OAuth integrado.

Puedes implementarlo en tu cuenta de Cloudflare y, tras crear tu propia aplicación cliente OAuth de GitHub, tendrás un servidor MCP remoto completamente funcional que puedes usar como base. Los usuarios podrán conectarse a tu servidor MCP iniciando sesión con su cuenta de GitHub.

Puede utilizar esto como un ejemplo de referencia sobre cómo integrar otros proveedores de OAuth con un servidor MCP implementado en Cloudflare, utilizando la biblioteca workers-oauth-provider .

El servidor MCP (con tecnología de Cloudflare Workers ):

Actúa como servidor OAuth para sus clientes MCP
Actúa como cliente OAuth para su servidor OAuth real (en este caso, GitHub)

Empezando

Clone el repositorio directamente e instale las dependencias: npm install .

Alternativamente, puede utilizar la línea de comando a continuación para crear el servidor MCP remoto en su máquina local:

npm create cloudflare@latest -- my-mcp-server --template=cloudflare/ai/demos/remote-mcp-github-oauth

Para producción

Crear una nueva aplicación OAuth de GitHub :

Para la URL de la página de inicio, especifique https://mcp-github-oauth.<your-subdomain>.workers.dev
Para la URL de devolución de llamada de autorización, especifique https://mcp-github-oauth.<your-subdomain>.workers.dev/callback
Anote su ID de cliente y genere un secreto de cliente.
Establece secretos a través de Wrangler

wrangler secret put GITHUB_CLIENT_ID
wrangler secret put GITHUB_CLIENT_SECRET
wrangler secret put COOKIE_ENCRYPTION_KEY # add any random string here e.g. openssl rand -hex 32

Configurar un espacio de nombres KV

Cree el espacio de nombres KV: wrangler kv:namespace create "OAUTH_KV"
Actualice el archivo Wrangler con el ID de KV

Implementar y probar

Implemente el servidor MCP para que esté disponible en su dominio workers.dev wrangler deploy

Pruebe el servidor remoto usando Inspector :

npx @modelcontextprotocol/inspector@latest

Ingresa https://mcp-github-oauth.<your-subdomain>.workers.dev/sse y haz clic en "Conectar". Una vez completado el proceso de autenticación, verás que las herramientas funcionan:

¡Ahora tienes un servidor MCP remoto implementado!

Control de acceso

Este servidor MCP utiliza GitHub OAuth para la autenticación. Todos los usuarios autenticados de GitHub pueden acceder a herramientas básicas como "add" y "userInfoOctokit".

La herramienta "generateImage" está restringida a usuarios específicos de GitHub enumerados en la configuración ALLOWED_USERNAMES :

// Add GitHub usernames for image generation access
const ALLOWED_USERNAMES = new Set([
  'yourusername',
  'teammate1'
]);

Acceda al servidor MCP remoto desde Claude Desktop

Abra Claude Desktop y vaya a Configuración -> Desarrollador -> Editar configuración. Esto abre el archivo de configuración que controla los servidores MCP a los que Claude puede acceder.

Reemplace el contenido con la siguiente configuración. Al reiniciar Claude Desktop, se abrirá una ventana del navegador con su página de inicio de sesión de OAuth. Complete el proceso de autenticación para otorgarle a Claude acceso a su servidor MCP. Tras otorgarle acceso, podrá usar las herramientas.

{
  "mcpServers": {
    "math": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp-github-oauth.<your-subdomain>.workers.dev/sse"
      ]
    }
  }
}

Una vez que las Herramientas (bajo 🔨) aparezcan en la interfaz, puedes pedirle a Claude que las use. Por ejemplo: "¿Podrías usar la herramienta matemática para sumar 23 y 19?". Claude debería invocar la herramienta y mostrar el resultado generado por el servidor MCP.

Para el desarrollo local

Si desea iterar y probar su servidor MCP, puede hacerlo en el desarrollo local. Para ello, deberá crear otra aplicación OAuth en GitHub:

Para la URL de la página de inicio, especifique http://localhost:8788
Para la URL de devolución de llamada de autorización, especifique http://localhost:8788/callback
Anote su ID de cliente y genere un secreto de cliente.
Cree un archivo .dev.vars en la raíz de su proyecto con:

GITHUB_CLIENT_ID=your_development_github_client_id
GITHUB_CLIENT_SECRET=your_development_github_client_secret

Desarrollar y probar

Ejecute el servidor localmente para que esté disponible en http://localhost:8788 wrangler dev

Para probar el servidor local, introduzca http://localhost:8788/sse en el Inspector y pulse Conectar. Una vez que siga las instrucciones, podrá ver "Herramientas".

Uso de Claude y otros clientes MCP

Al usar Claude para conectarse a su servidor MCP remoto, es posible que vea algunos mensajes de error. Esto se debe a que Claude Desktop aún no es compatible con servidores MCP remotos, por lo que a veces genera confusión. Para verificar si el servidor MCP está conectado, pase el cursor sobre el icono 🔨 en la esquina inferior derecha de la interfaz de Claude. Debería ver sus herramientas disponibles allí.

Uso de Cursor y otros clientes MCP

Para conectar Cursor con su servidor MCP, elija Type : "Comando" y en el campo Command , combine los campos de comando y argumentos en uno (por ejemplo npx mcp-remote https://<your-worker-name>.<your-subdomain>.workers.dev/sse ).

Tenga en cuenta que si bien Cursor admite servidores HTTP+SSE, no admite la autenticación, por lo que aún deberá usar mcp-remote (y usar un servidor STDIO, no uno HTTP).

Puede conectar su servidor MCP a otros clientes MCP como Windsurf abriendo el archivo de configuración del cliente, agregando el mismo JSON que se utilizó para la configuración de Claude y reiniciando el cliente MCP.

¿Cómo funciona?

Proveedor de OAuth

La biblioteca del proveedor OAuth sirve como una implementación completa del servidor OAuth 2.1 para los trabajadores de Cloudflare. Gestiona las complejidades del flujo OAuth, incluyendo la emisión, validación y gestión de tokens. En este proyecto, cumple una doble función:

Autenticación de clientes MCP que se conectan a su servidor
Administrar la conexión a los servicios OAuth de GitHub
Almacenamiento seguro de tokens y estado de autenticación en el almacenamiento KV

MCP duradero

Durable MCP extiende la funcionalidad base de MCP con los objetos duraderos de Cloudflare, proporcionando:

Gestión de estado persistente para su servidor MCP
Almacenamiento seguro del contexto de autenticación entre solicitudes
Acceso a información de usuario autenticado a través de this.props
Compatibilidad con disponibilidad condicional de herramientas según la identidad del usuario

Control remoto MCP

La biblioteca remota de MCP permite que su servidor exponga herramientas que pueden ser invocadas por clientes de MCP, como el Inspector. Esta biblioteca:

Define el protocolo de comunicación entre los clientes y su servidor.
Proporciona una forma estructurada de definir herramientas.
Maneja la serialización y deserialización de solicitudes y respuestas.
Mantiene la conexión de eventos enviados por el servidor (SSE) entre los clientes y su servidor

Remote MCP Server with GitHub OAuth