MCP 서버 템플릿 (Python)

Render용 최소한의 Model Context Protocol 서버 템플릿입니다. 포크해서 자신만의 도구를 추가하고 배포하세요.

포함된 내용

• MCP Python SDK를 사용하는 작동하는 MCP 서버 (Streamable HTTP 전송)

• MCP_API_TOKEN을 통한 Bearer 토큰 인증 (배포 시 자동 생성)

• 패턴을 보여주는 예제 도구 하나 (hello)

• Render의 상태 확인을 위한 /health 엔드포인트

• 원클릭 배포를 위한 render.yaml Blueprint

• AI 코딩 어시스턴트가 새 도구를 만들어 줄 수 있게 하는 AGENTS.md

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

Related MCP server: MCP Server Template (Python)

로컬에서 시작하기

git clone https://github.com/render-examples/mcp-server-python.git
cd mcp-server-python
pip install -r requirements.txt
python server.py

서버는 http://localhost:10000에서 시작됩니다. MCP 엔드포인트는 /mcp에 있습니다.

테스트 실행

pip install -r requirements.txt
pytest

인증

서버는 Bearer 토큰을 사용하여 요청을 인증합니다. Render의 Blueprint는 첫 배포 시 임의의 MCP_API_TOKEN을 자동 생성합니다.

배포 후 토큰을 찾으려면 Render 대시보드 > 서비스 > Environment로 이동하여 MCP_API_TOKEN 값을 복사하세요.

클라이언트는 Authorization 헤더에 토큰을 포함해야 합니다:

Authorization: Bearer YOUR_TOKEN

MCP_API_TOKEN이 설정되지 않은 경우(예: 로컬 개발 중) 인증이 비활성화되고 모든 요청이 허용됩니다.

토큰 관리

초기 배포 후 토큰은 직접 관리할 수 있습니다:

• 토큰 회전 — Render 대시보드의 Environment에서 MCP_API_TOKEN을 업데이트하세요. 서비스는 새 값으로 자동 재시작됩니다.

• 새 토큰 생성 — 다음 중 하나를 사용하세요:

  • openssl rand -base64 32

  • python3 -c "import secrets; print(secrets.token_urlsafe(32))"

  • 비밀번호 관리자 생성기 (1Password, Bitwarden 등)

• 토큰을 소스 제어에 커밋하지 마세요. 환경 변수나 .env 파일을 사용하세요 (이 파일들은 .gitignore에 포함됩니다).

• 다중 사용자 또는 프로덕션 환경에서는 OAuth 2.1로 업그레이드하는 것을 고려하세요.

MCP 서버에 연결하기

Render에 배포한 후 MCP 엔드포인트는 다음 주소에서 사용할 수 있습니다:

https://your-service-name.onrender.com/mcp

Cursor

프로젝트의 .cursor/mcp.json에 추가하세요:

{
  "mcpServers": {
    "my-mcp-server": {
      "url": "https://your-service-name.onrender.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Claude Desktop

Claude Desktop 구성에 추가하세요:

{
  "mcpServers": {
    "my-mcp-server": {
      "type": "streamable-http",
      "url": "https://your-service-name.onrender.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Codex

codex mcp add --transport streamable-http \
  --url https://your-service-name.onrender.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN" \
  my-mcp-server

또는 .codex/config.toml에 추가하세요:

[mcp_servers.my-mcp-server]
url = "https://your-service-name.onrender.com/mcp"
http_headers = { Authorization = "Bearer YOUR_TOKEN" }

도구 추가하기

server.py에서 함수에 @mcp.tool() 데코레이터를 사용하여 도구를 추가하세요:

@mcp.tool()
def fetch_weather(city: str, units: str = "celsius") -> str:
    """Get the current weather for a city."""
    # your implementation here
    return f"Weather for {city}"

docstring은 도구 설명이 되며, MCP 클라이언트는 이를 LLM에 표시합니다. 항상 명확하게 작성하세요.

이 저장소에는 AGENTS.md 파일이 포함되어 있습니다. AI 코딩 어시스턴트(Cursor, Copilot, Codex, Windsurf 등)를 사용하는 경우 "새 도구 추가"라고 요청하면 AGENTS.md의 규칙을 자동으로 따릅니다.

프로젝트 구조

server.py              MCP server with example tool and health check
requirements.txt       Python dependencies
render.yaml            Render Blueprint for deployment
.env.example           Environment variable reference
tests/test_server.py   Test suite (auth, health, tool calls)
pyproject.toml         pytest configuration
AGENTS.md              Instructions for AI coding assistants
CLAUDE.md              Pointer to AGENTS.md for Claude Code

자세히 알아보기

• MCP 사양

• MCP Python SDK

• Render Blueprints