custodyops-mcp-python

Python MCP 서버의 최소 구현으로, Streamable HTTP를 통해 FastAPI + fastmcp를 사용하며 Render에 HTTPS로 배포할 준비가 되어 있습니다. ping 도구와 두 개의 데모 도구(get_positions, list_upcoming_corporate_actions)를 제공하며, 이를 귀하의 커스터디 데이터에 대한 읽기 전용 어댑터로 교체할 수 있습니다.

Streamable HTTP를 사용하는 이유? 이는 원격/호스팅 MCP 서버에 권장되는 전송 방식으로, 양방향 스트리밍을 단일 POST /mcp 엔드포인트로 단순화하여 클라우드 배포를 간편하게 만듭니다. 자세한 내용은 MCP HTTP 빠른 시작 및 SDK 문서에서 표준 패턴을 확인하세요.

기능

• POST /mcp에서 Streamable HTTP 엔드포인트 제공

• AUTH_TOKEN을 통한 Bearer 인증

• 가동 시간 확인을 위한 /health 엔드포인트

• 최소한의 코드로, 더 많은 MCP 도구로 쉽게 확장 가능

• render.yaml을 통해 Render에 원클릭 배포

Related MCP server: MCP Ping-Pong Server

빠른 시작 (로컬)

python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scriptsctivate
pip install -r requirements.txt
export AUTH_TOKEN=devtoken123
export PORT=3000
uvicorn app:app --host 0.0.0.0 --port $PORT

cURL로 테스트:

# tools/list
curl -s -X POST http://localhost:3000/mcp   -H "Content-Type: application/json"   -H "Authorization: Bearer devtoken123"   -d '{"jsonrpc":"2.0","id":"1","method":"tools/list","params":{}}' | jq

# tools/call ping
curl -s -X POST http://localhost:3000/mcp   -H "Content-Type: application/json"   -H "Authorization: Bearer devtoken123"   -d '{"jsonrpc":"2.0","id":"2","method":"tools/call","params":{"name":"ping","arguments":{}}}' | jq

또는 도우미 스크립트 실행:

chmod +x scripts/test_locally.sh
AUTH_TOKEN=devtoken123 PORT=3000 ./scripts/test_locally.sh

Render에 배포 (HTTPS)

1. 이 저장소를 GitHub에 포크 또는 푸시합니다.

2. Render에서: New → Web Service → Connect repo.

3. render.yaml의 설정을 검토합니다(Python 환경, 무료 플랜). Render가 HTTPS를 자동으로 프로비저닝합니다.

4. Render Environment에서 AUTH_TOKEN을 설정합니다(블루프린트를 사용하면 자동 생성됨).

5. 배포 → 공개 MCP 엔드포인트: https://<your-app>.onrender.com/mcp.

원격 테스트:

APP_URL=https://<your-app>.onrender.com AUTH_TOKEN=<token> ./scripts/test_remote.sh

Claude Desktop에서 사용 (원격 MCP)

claude_desktop_config.json에 릴레이 항목을 추가합니다:

{
  "mcpServers": {
    "custodyops-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://<your-app>.onrender.com/mcp"],
      "env": { "AUTH_TOKEN": "<same-token>" }
    }
  }
}

앱을 다시 시작한 후 Claude에게 사용 가능한 도구 목록을 요청하세요.

실제 커스터디 데이터로 확장

데모 도구를 데이터 마트 또는 API에 대한 읽기 전용 어댑터로 교체하세요. 응답은 작고 타입이 명확하게 유지하고, 가능한 경우 필드 출처를 추가하세요.

예시 스켈레톤:

@mcp_tool
def get_positions(account_id: str) -> str:
    rows = query_positions(account_id)  # your adapter
    return json.dumps(rows)

보안 참고 사항

• AUTH_TOKEN을 비밀로 유지하고 정기적으로 교체하세요. 엔터프라이즈 사용의 경우 OAuth/JWT로 전환하고 계정별 권한 부여를 추가하세요.

• HTTP 전송을 사용하면 일반 로깅으로 충분하지만, 민감한 데이터는 삭제하고 요청 ID를 추가하세요.

라이선스

MIT