MCP-инструменты с аутентификацией OAuth

Пример на Python, демонстрирующий, как создать MCP-сервер (Model Context Protocol) с аутентификацией OAuth, объединяющий API-клиент, слой бизнес-логики и защищённые MCP-инструменты.

Возможности

• Процесс аутентификации OAuth: вход в один клик в браузере для получения сессионных токенов

• Многоуровневая архитектура: API-клиент → бизнес-логика → MCP-инструменты

• Безопасный доступ к инструментам: для вызова защищённых инструментов требуется действительный токен

• Простой HTTP-сервер: сервер аутентификации на Flask, работающий на localhost:5000

• Управление токенами: сессионные токены на 24 часа с сохранением

Related MCP server: OAuth MCP Server

Архитектура

src/example/
├── api/
│   ├── api_client.py      # HTTP API client (JSONPlaceholder)
│   └── http_server.py     # Local HTTP server
├── auth/
│   └── manager.py         # OAuth token & state management
├── business/
│   └── service.py         # Business logic layer
├── http/
│   └── auth_server.py     # Flask OAuth auth server
├── mcp/
│   └── server.py          # MCP server with auth
└── main.py

Установка

python -m venv .venv

# Windows:
.venv\Scripts\activate

# Linux/macOS:
source .venv/bin/activate

pip install -r requirements.txt

Быстрый старт

1. Запустите сервер аутентификации

python -m src.example.http.auth_server

Это запускает Flask-сервер на http://localhost:5000 с процессом OAuth:

• Посетите главную страницу

• Нажмите «Click to Authenticate»

• Получите сессионный токен на странице обратного вызова

• Скопируйте и сохраните токен

2. Запустите MCP-сервер

В другом терминале:

python -m src.example.mcp.server

3. Используйте MCP-инструменты

Теперь MCP-сервер требует аутентификации. Сначала получите URL авторизации:

echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python -m src.example.mcp.server

Затем пройдите аутентификацию и используйте инструменты с вашим токеном:

echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"get_user","arguments":{"user_id":1},"auth_token":"YOUR_SESSION_TOKEN"},"id":1}' | python -m src.example.mcp.server

Процесс аутентификации

1. Получение URL авторизации: вызовите инструмент get_auth_url (аутентификация не требуется)

   {"jsonrpc":"2.0","method":"tools/call","params":{"name":"get_auth_url","arguments":{}},"id":1}

2. Открытие ссылки в браузере: пользователь переходит по возвращённому URL авторизации

   • Открывается http://localhost:5000/auth/callback?state=...

   • В браузере отображается страница успеха с сессионным токеном

   • Токен действует в течение 24 часов

3. Использование токена: передавайте auth_token во всех вызовах инструментов

   {"params":{"name":"get_user","arguments":{"user_id":1},"auth_token":"YOUR_TOKEN"}}

Доступные инструменты

Публичные (аутентификация не требуется)

• get_auth_url - получить URL авторизации OAuth

Защищённые (требуется аутентификация)

• get_user - получить пользователя по ID

• list_users - получить список всех пользователей

• create_user - создать нового пользователя

• update_user - обновить имя/email пользователя

• delete_user - удалить пользователя

Конфигурация

Задайте переменные окружения:

export PORT=5000                           # Auth server port
export FLASK_SECRET_KEY=your-secret-key    # Flask secret (change in production!)

Тестирование

Запустите тесты с помощью pytest:

pytest -v
pytest --cov=src           # With coverage
pytest tests/test_auth.py  # Auth tests only

Запустите скрипт оболочки

sh test-auth-flow.sh
========================================
  MCP Auth Server - Complete Flow Test
========================================
Base URL: https://claude-ia-mcp-tools-auth-staging.up.railway.app

Step 1: Start Auth Flow
GET /auth/start
Status: 401
Auth URL: https://claude-ia-mcp-tools-auth-staging.up.railway.app/auth/callback?state=Xukdt6MwHba0n0UfkOX3lAAanm7MJhSyzomyCJCxj1M

State Token: Xukdt6MwHba0n0UfkOX3lAAanm7MJhSyzomyCJCx...

Step 2: Complete Auth Callback
GET /auth/callback?state=Xukdt6MwHba0n0UfkOX3lAAanm7MJhSyzomyCJCxj1M
Status: 200
Session Token: 7Y6SaanfrLmiOXoE2kUvTbdEfawIMSJyGDaNFPf1...

Step 3: Verify Token with Auth Status
GET /auth/status -H 'Authorization: Bearer 7Y6SaanfrLmiOXoE2kUvTbdEfawIMSJyGDaNFPf1-Bg'
Response:
{"authenticated":true,"user_id":"user_1b25e4982c9904b8"}

========================================
         TEST RESULTS
========================================
State Token:     Xukdt6MwHba0n0UfkOX3lAAanm7MJhSyzomyCJCxj1M
Session Token:   7Y6SaanfrLmiOXoE2kUvTbdEfawIMSJyGDaNFPf1-Bg
Authenticated:   true
User ID:         user_1b25e4982c9904b8
========================================

Step 4: Test Invalid Token
GET /auth/status -H 'Authorization: Bearer invalid_token_123'
Response: {"authenticated":false,"user_id":null}

SUCCESS: Complete auth flow working correctly!

You can now use this token for MCP:
Authorization: Bearer 7Y6SaanfrLmiOXoE2kUvTbdEfawIMSJyGDaNFPf1-Bg

Развертывание

Для продакшена обновите:

1. FLASK_SECRET_KEY - используйте надёжный случайный ключ

2. Провайдер OAuth - замените на реальный OAuth (Google, GitHub и т.д.)

3. Хранение токенов - используйте базу данных вместо .auth_tokens.json

4. HTTPS - включите SSL/TLS для эндпоинтов аутентификации

Примечания по архитектуре

Этот пример демонстрирует:

• Разделение ответственности: API-клиент, бизнес-логика и MCP-слой независимы

• Многослойный дизайн: компоненты легко тестировать и заменять

• Интеграция аутентификации: токены аутентификации передаются через параметры, а не заголовки

• Обработка ошибок: корректные ответы об ошибках при сбоях аутентификации

API-клиент использует https://jsonplaceholder.typicode.com в качестве демонстрационного API. Замените его своей собственной реализацией API, не изменяя MCP/бизнес-интерфейсы.