Plantilla de servidor MCP con autenticación Descope

Una plantilla de servidor FastMCP sencilla para Render, con autenticación MCP completa mediante Descope.

Qué incluye

• Un servidor MCP funcional que utiliza FastMCP con transporte HTTP Streamable

• Soporte completo de autorización MCP con el DescopeProvider de FastMCP y el SDK descope-mcp

• Una herramienta de ejemplo (hello) que devuelve "Hello, world!" y aplica requisitos de ámbito a nivel de herramienta (mcp:greet)

• Un Blueprint render.yaml para una fácil implementación

Nota: Esta plantilla se implementa en el plan gratuito de Render de forma predeterminada. Los servicios gratuitos se desactivan tras 15 minutos de inactividad, lo que provoca arranques en frío de 30 a 60 segundos en la siguiente solicitud. Los clientes MCP pueden agotar el tiempo de espera durante este retraso. Para un uso fiable, actualice a un plan de pago en el panel de control de Render: el plan Starter mantiene su servicio funcionando continuamente.

Related MCP server: MCP Server Template

Requisitos previos

• Python 3.13+

• uv

• Una cuenta y proyecto de Descope

Configuración de Descope

1. Inicie sesión en la Consola de Descope.

2. Navegue a Agentic Identity Hub → MCP Servers.

3. Haga clic en + MCP Server para crear un nuevo servidor MCP y asígnele un nombre.

4. En MCP Client Registration, habilite Client ID Metadata Documents (CIMD) y Dynamic Client Registration (DCR). Opcionalmente, puede restringir los dominios permitidos para los clientes que se registren a través de CIMD (por ejemplo, https://claude.ai); puede dejar este campo en blanco.

5. En MCP Server Scopes, añada un ámbito llamado mcp:greet y una descripción sencilla como "Saludar al usuario".

6. Haga clic en Create.

7. Expanda la sección Connect your MCP server to Descope en la página de confirmación.

8. Copie la Well-Known URL. Se ve así:

   https://api.descope.com/v1/apps/agentic/.../.well-known/openid-configuration

   Esta es su DESCOPE_CONFIG_URL.

Nota: Descope emite tokens siguiendo los indicadores de recursos (RFC 8707), tal como requiere la especificación MCP. Cuando implemente en Render o ejecute localmente, deberá actualizar la sección de URLs del servidor MCP.

Implementación en Render

Asegúrese de haber completado el paso de Configuración de Descope antes de desarrollar localmente, ya que necesitará su DESCOPE_CONFIG_URL.

1. Haga un fork de este repositorio en su cuenta de GitHub.

2. Haga clic en Deploy to Render (o haga un fork de este repositorio en GitHub e impórtelo como un Blueprint en su cuenta de Render).

   

3. En sus configuraciones especificadas, establezca la variable de entorno con el valor obtenido en el paso de Configuración de Descope:

   Clave	Valor
   DESCOPE_CONFIG_URL	Su Well-Known URL de la consola de Descope

4. Haga clic en Deploy Blueprint.

5. Una vez activo, copie la URL de su servicio de Render (por ejemplo, https://<your-project>.onrender.com), añada /mcp al final y agréguela a MCP Server URLs en la consola de Descope.

¡Ahora tiene un servidor MCP alojado de forma remota con la especificación de autenticación completa soportada!

Desarrollo local

Asegúrese de haber completado el paso de Configuración de Descope antes de desarrollar localmente, ya que necesitará su DESCOPE_CONFIG_URL.

Primero, haga un fork de este repositorio en su cuenta de GitHub y luego siga las instrucciones a continuación para configurar su entorno.

# Install dependencies
uv sync

# Set required environment variables
export DESCOPE_CONFIG_URL="<your URL from Descope>"
export SERVER_URL="http://localhost:8000"

# Run the server
uv run server.py --transport http --port 8000

Cuando ejecute esto localmente, su servidor se ejecutará en http://localhost:8000/mcp.

Herramientas disponibles

Próximos pasos

Ahora que todo está configurado, le recomendamos algunos pasos más si va a llevar su servidor MCP a producción.

Añada sus propias herramientas

Reemplace o amplíe la herramienta hello en server.py con su propia lógica. Para cada nueva herramienta:

1. Defina un nuevo ámbito en la consola de Descope en MCP Server Scopes (por ejemplo, mcp:your-scope).

2. Añada la herramienta usando el decorador @mcp.tool().

3. Llame a require_scopes(token, ["mcp:your-scope"]) dentro del cuerpo de la herramienta para aplicar el control de acceso.

4. Añada la nueva herramienta y su ámbito requerido a la tabla de Herramientas disponibles anterior.

@mcp.tool()
def my_tool() -> str:
    token = validate_token()
    require_scopes(token, ["mcp:your-scope"])
    return "your result"

Use un dominio personalizado en Render

De forma predeterminada, su servicio es accesible en https://<your-project>.onrender.com. Para usar un dominio personalizado:

1. En el panel de control de Render, vaya a su servicio → Settings → Custom Domains.

2. Añada su dominio y siga las instrucciones de DNS proporcionadas.

3. Una vez verificado el dominio, actualice MCP Server URLs en la consola de Descope para usar su dominio personalizado (por ejemplo, https://mcp.yourdomain.com/mcp).

4. No se necesitan cambios en el código: RENDER_EXTERNAL_URL es configurado automáticamente por Render y reflejará el dominio principal.

Proteja todas las herramientas con ámbitos

La comprobación require_scopes() es intencionalmente opcional por herramienta para que pueda añadir herramientas sin autenticación si es necesario. Para un servidor de producción, es una buena práctica llamar a require_scopes() en cada herramienta. También puede centralizar esto escribiendo un asistente que envuelva validate_token() y require_scopes() y llamándolo al principio de cada manejador de herramientas.

Cómo funciona la autenticación MCP

1. Un cliente MCP (por ejemplo, Claude Desktop, Cursor) descubre los metadatos de OAuth desde /.well-known/oauth-authorization-server al intentar conectarse a su servidor MCP.

2. El cliente se registra dinámicamente (a través de CIMD o DCR) en el servidor de autorización y redirige al usuario al flujo de inicio de sesión/consentimiento de Descope.

3. Después de iniciar sesión, Descope emite un JWT firmado. El cliente incluye esto como un token Bearer en cada solicitud MCP.

4. DescopeProvider valida el JWT usando el endpoint JWKS de Descope antes de que se llame a cualquier herramienta.

5. Dentro de la herramienta, validate_token() analiza las reclamaciones y require_scopes() comprueba que mcp:greet esté presente, devolviendo un error al cliente si no lo está.

Más información

• Render Blueprints

• Autorización MCP

• FastMCP

• Documentación de Descope Agentic Identity Hub

• SDK de Descope MCP