Descope Auth Server Template

A simple FastMCP server template for Render, with full MCP authentication by Descope.

What's included

• A working MCP server using FastMCP with Streamable HTTP transport
• Full MCP Authorization Support with FastMCP's DescopeProvider and the descope-mcp SDK
• One example tool (hello) that returns "Hello, world!" and enforces tool-level scope requirements (mcp:greet)
• A render.yaml Blueprint for easy deployment

Note: This template deploys on Render's free plan by default. Free services spin down after 15 minutes of inactivity, causing cold starts of 30-60 seconds on the next request. MCP clients may time out during this delay. For reliable use, upgrade to a paid plan in the Render Dashboard — the Starter plan keeps your service running continuously.

Prerequisites

• Python 3.13+
• uv
• A Descope account and project

Descope Setup

1. Log in to the Descope Console.

2. Navigate to Agentic Identity Hub → MCP Servers.

3. Click + MCP Server to create a new MCP server and give it a name.

4. Under MCP Client Registration, enable Client ID Metadata Documents (CIMD) and Dynamic Client Registration (DCR). Optionally, you can restrict allowed domains for clients registering via CIMD (e.g. https://claude.ai) - feel free to leave this field blank.

5. Under MCP Server Scopes, add a scope named mcp:greet and a simple description like "Greet the user".

6. Click Create.

7. Expand the Connect your MCP server to Descope section on the confirmation page

8. Copy the Well-Known URL. It looks like this:

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

   This is your DESCOPE_CONFIG_URL.

Note: Descope issues tokens following Resource Indicators (RFC 8707), as required by the MCP spec. When you're deploying on Render or running locally, you'll need to update the MCP Server URLs section.

Deploying on Render

Ensure that you've completed the Descope Setup step prior to developing locally, as you'll need your DESCOPE_CONFIG_URL.

1. Fork this repository to your GitHub account.

2. Click Deploy to Render (or fork this repo on GitHub and import it as a Blueprint in your Render account).

   Deploy to Render

3. In your Specified Configurations, set the environment variable to the value obtained in the Descope Setup step:

   Key	Value
   DESCOPE_CONFIG_URL	Your Well-Known URL from the Descope Console

4. Click Deploy Blueprint.

5. Once live, copy your Render service URL (e.g. https://<your-project>.onrender.com), append /mcp, and add it to MCP Server URLs in the Descope Console.

You now have a remotely hosted MCP Server with the full auth spec supported!

Local development

Ensure that you've completed the Descope Setup step prior to developing locally, as you'll need your DESCOPE_CONFIG_URL.

First, fork this repo to your GitHub account, then follow the instructions below to set up your environment.

# 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

When you run this locally, your server will run at http://localhost:8000/mcp.

Available tools

Tool	Description	Required scope
hello	Returns "Hello, world!"	mcp:greet

Next steps

Now that you're all set up, there's a few more steps we recommend if you're taking your MCP Server to production.

Add your own tools

Replace or extend the hello tool in server.py with your own logic. For each new tool:

1. Define a new scope in the Descope Console under MCP Server Scopes (e.g. mcp:your-scope).
2. Add the tool using the @mcp.tool() decorator.
3. Call require_scopes(token, ["mcp:your-scope"]) inside the tool body to enforce access control.
4. Add the new tool and its required scope to the Available tools table above.

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

Use a custom domain on Render

By default, your service is reachable at https://<your-project>.onrender.com. To use a custom domain:

1. In the Render Dashboard, go to your service → Settings → Custom Domains.
2. Add your domain and follow the DNS instructions provided.
3. Once the domain is verified, update MCP Server URLs in the Descope Console to use your custom domain (e.g. https://mcp.yourdomain.com/mcp).
4. No code changes are needed - RENDER_EXTERNAL_URL is set automatically by Render and will reflect the primary domain.

Protect all tools with scopes

The require_scopes() check is intentionally opt-in per tool so you can add unauthenticated tools if needed. For a production server, it is good practice to call require_scopes() in every tool. You can also centralize this by writing a helper that wraps validate_token() and require_scopes() and calling it at the top of each tool handler.

How MCP Auth works

1. An MCP client (e.g. Claude Desktop, Cursor) discovers OAuth metadata from /.well-known/oauth-authorization-server when trying to connect to your MCP Server.
2. The client registers dynamically (via CIMD or DCR) to the authorization server and redirects the user to Descope's login / consent flow.
3. After login, Descope issues a signed JWT. The client includes this as a Bearer token on every MCP request.
4. DescopeProvider validates the JWT using Descope's JWKS endpoint before any tool is called.
5. Inside the tool, validate_token() parses the claims and require_scopes() checks that mcp:greet is present, returning an error to the client if not.

Learn more

• Render Blueprints
• MCP Authorization
• FastMCP
• Descope Agentic Identity Hub docs
• Descope MCP SDK