Descope 인증을 포함한 MCP 서버 템플릿

Descope를 통한 완전한 MCP 인증을 지원하며 Render에서 사용할 수 있는 간단한 FastMCP 서버 템플릿입니다.

포함된 내용

• Streamable HTTP 전송을 사용하는 FastMCP 기반의 작동하는 MCP 서버

• FastMCP의 DescopeProvider 및 descope-mcp SDK를 통한 완전한 MCP 권한 부여 지원

• "Hello, world!"를 반환하고 도구 수준의 범위 요구 사항(mcp:greet)을 적용하는 예제 도구(hello) 하나

• 간편한 배포를 위한 render.yaml 블루프린트

참고: 이 템플릿은 기본적으로 Render의 무료 플랜에 배포됩니다. 무료 서비스는 15분 동안 활동이 없으면 중단되며, 다음 요청 시 30~60초의 콜드 스타트가 발생합니다. 이 지연 시간 동안 MCP 클라이언트의 시간이 초과될 수 있습니다. 안정적인 사용을 위해서는 Render 대시보드에서 유료 플랜으로 업그레이드하십시오. Starter 플랜은 서비스를 지속적으로 실행 상태로 유지합니다.

Related MCP server: MCP Server Template

사전 요구 사항

• Python 3.13+

• uv

• Descope 계정 및 프로젝트

Descope 설정

1. Descope 콘솔에 로그인합니다.

2. Agentic Identity Hub → MCP Servers로 이동합니다.

3. + MCP Server를 클릭하여 새 MCP 서버를 만들고 이름을 지정합니다.

4. MCP Client Registration에서 Client ID Metadata Documents (CIMD) 및 **Dynamic Client Registration (DCR)**을 활성화합니다. 선택적으로 CIMD를 통해 등록하는 클라이언트에 대해 허용된 도메인(예: https://claude.ai)을 제한할 수 있습니다. 이 필드는 비워두어도 됩니다.

5. MCP Server Scopes에서 mcp:greet라는 범위와 "사용자에게 인사하기"와 같은 간단한 설명을 추가합니다.

6. Create를 클릭합니다.

7. 확인 페이지에서 Connect your MCP server to Descope 섹션을 확장합니다.

8. Well-Known URL을 복사합니다. 다음과 같은 형태입니다:

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

   이것이 귀하의 DESCOPE_CONFIG_URL입니다.

참고: Descope는 MCP 사양에서 요구하는 대로 Resource Indicators(RFC 8707)를 따르는 토큰을 발행합니다. Render에 배포하거나 로컬에서 실행할 때 MCP 서버 URL 섹션을 업데이트해야 합니다.

Render에 배포하기

로컬에서 개발하기 전에 DESCOPE_CONFIG_URL이 필요하므로 Descope 설정 단계를 완료했는지 확인하십시오.

1. 이 저장소를 귀하의 GitHub 계정으로 포크합니다.

2. Deploy to Render를 클릭합니다(또는 GitHub에서 이 저장소를 포크하고 Render 계정에서 블루프린트로 가져옵니다).

   

3. 지정된 구성에서 환경 변수를 Descope 설정 단계에서 얻은 값으로 설정합니다:

   키	값
   DESCOPE_CONFIG_URL	Descope 콘솔에서 얻은 Well-Known URL

4. Deploy Blueprint를 클릭합니다.

5. 라이브 상태가 되면 Render 서비스 URL(예: https://<your-project>.onrender.com)을 복사하여 /mcp를 추가하고 Descope 콘솔의 MCP Server URLs에 추가합니다.

이제 전체 인증 사양이 지원되는 원격 호스팅 MCP 서버가 준비되었습니다!

로컬 개발

로컬에서 개발하기 전에 DESCOPE_CONFIG_URL이 필요하므로 Descope 설정 단계를 완료했는지 확인하십시오.

먼저 이 저장소를 귀하의 GitHub 계정으로 포크한 다음, 아래 지침에 따라 환경을 설정하십시오.

# 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

로컬에서 실행하면 서버는 http://localhost:8000/mcp에서 실행됩니다.

사용 가능한 도구

다음 단계

이제 모든 설정이 완료되었습니다. MCP 서버를 프로덕션 환경으로 가져가려는 경우 권장되는 몇 가지 추가 단계가 있습니다.

나만의 도구 추가

server.py의 hello 도구를 자신의 로직으로 교체하거나 확장하십시오. 각 새 도구에 대해:

1. Descope 콘솔의 MCP Server Scopes 아래에 새 범위를 정의합니다(예: mcp:your-scope).

2. @mcp.tool() 데코레이터를 사용하여 도구를 추가합니다.

3. 도구 본문 내에서 require_scopes(token, ["mcp:your-scope"])를 호출하여 액세스 제어를 적용합니다.

4. 새 도구와 필수 범위를 위의 사용 가능한 도구 표에 추가합니다.

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

Render에서 사용자 지정 도메인 사용

기본적으로 서비스는 https://<your-project>.onrender.com에서 액세스할 수 있습니다. 사용자 지정 도메인을 사용하려면:

1. Render 대시보드에서 서비스 → Settings → Custom Domains로 이동합니다.

2. 도메인을 추가하고 제공된 DNS 지침을 따릅니다.

3. 도메인이 확인되면 Descope 콘솔의 MCP Server URLs를 업데이트하여 사용자 지정 도메인(예: https://mcp.yourdomain.com/mcp)을 사용하도록 합니다.

4. 코드 변경은 필요하지 않습니다. RENDER_EXTERNAL_URL은 Render에 의해 자동으로 설정되며 기본 도메인을 반영합니다.

모든 도구를 범위로 보호

require_scopes() 확인은 도구별로 선택 사항이므로 필요한 경우 인증되지 않은 도구를 추가할 수 있습니다. 프로덕션 서버의 경우 모든 도구에서 require_scopes()를 호출하는 것이 좋습니다. 또한 validate_token()과 require_scopes()를 래핑하는 헬퍼를 작성하고 각 도구 핸들러의 상단에서 호출하여 이를 중앙 집중화할 수도 있습니다.

MCP 인증 작동 방식

1. MCP 클라이언트(예: Claude Desktop, Cursor)는 MCP 서버에 연결하려고 할 때 /.well-known/oauth-authorization-server에서 OAuth 메타데이터를 검색합니다.

2. 클라이언트는 권한 부여 서버에 동적으로 등록(CIMD 또는 DCR을 통해)하고 사용자를 Descope의 로그인/동의 흐름으로 리디렉션합니다.

3. 로그인 후 Descope는 서명된 JWT를 발행합니다. 클라이언트는 모든 MCP 요청에 이를 Bearer 토큰으로 포함합니다.

4. DescopeProvider는 도구가 호출되기 전에 Descope의 JWKS 엔드포인트를 사용하여 JWT를 검증합니다.

5. 도구 내부에서 validate_token()은 클레임을 구문 분석하고 require_scopes()는 mcp:greet가 존재하는지 확인하며, 그렇지 않은 경우 클라이언트에 오류를 반환합니다.

더 알아보기

• Render Blueprints

• MCP Authorization

• FastMCP

• Descope Agentic Identity Hub docs

• Descope MCP SDK