Безопасная система агентов MCP

Сервер и клиент MCP для тикетов поддержки и клиентских аккаунтов, созданные и защищённые сквозным образом: аутентификация по подписанным токенам, два независимых рубежа защиты от prompt-инъекций и подмены инструментов, документированная модель угроз и обязательный контроль человеком для единственного разрушительного вызова инструмента. Разработано для лабораторной работы «Secure an MCP-Based Agent System».

Архитектура

flowchart TD
    HOST["Host application"] --> CLIENT["client.py\n(fastmcp.Client + elicitation_handler)"]
    CLIENT <-->|"Streamable HTTP\nAuthorization: Bearer <signed JWT>"| SERVER

    subgraph Server["server.py — FastMCP('SecureAgentServer')"]
        AUTH["JWTVerifier (HS256)\nissuer + audience + signature checked"]
        G1["Guardrail 1: sanitize_untrusted_text()\napplied to ticket body/subject"]
        G2["Guardrail 2: verify_tool_manifest()\nchecked at startup, refuses to start on mismatch"]
        TOOLS["Tools: search_tickets, lookup_customer_account,\nclose_ticket (elicitation-gated)"]
        AUTH --> TOOLS
        TOOLS --> G1
    end
    G2 -.->|startup check| SERVER

    TOOLS --> TICKETS[("data/tickets.json\n(untrusted customer text)")]
    TOOLS --> CUSTOMERS[("data/customers.json\n('internal API')")]

Related MCP server: permitd MCP Server

Настройка

pip install -r requirements.txt

# 1. Set the JWT signing secret (never commit the real value; see .env.example)
export MCP_JWT_SECRET="a-long-random-secret-at-least-32-characters"

# 2. Generate the pinned tool-integrity manifest (a deliberate, manual step —
#    see docs/threat-model.md Risk #2)
python generate_manifest.py

# 3. Run the server
python server.py

# 4. In another terminal (same MCP_JWT_SECRET exported)
python client.py --auto-confirm   # non-interactive demo
python client.py                  # interactive: real yes/no confirmation prompts

Воспроизведение мер безопасности

Модель угроз

Полное описание, включающее 5 выявленных рисков с мерами смягчения и явно указанными замечаниями об остаточных рисках, а не замолчаянных: docs/threat-model.md.

Что намеренно вынесено за рамки, сказано прямо

• mint_token.py заменяет реального провайдера удостоверений OAuth 2.1 — в продакшене нужно настоящее выпуск/перевыпуск/отзыв токенов, а не локальный скрипт.

• Нет ограничения скорости или усиления на сетевом уровне (завершение TLS, WAF) — это демонстрация безопасности на прикладном уровне, а не полное руководство по защите развёртывания.

• Основанная на regex-часть рубежа 1 явно вспомогательная, работающая по принципу best-effort — см. риск № 1 в docs/threat-model.md о том, почему именно обёртка разделителем является основной действующей мерой.

Без секретов в репозитории

MCP_JWT_SECRET считывается из окружения (см. .env.example) и никогда не захардкожен и не коммитится. tool_manifest.json намеренно находится в коммите — это зафиксированный хэш-манифест (вроде lockfile), а не секрет.