PRJ-05 — Servidor MCP Seguro (autenticação por API Key)

Servidor MCP (FastMCP, transporte stdio) cujas tools só executam mediante uma API Key válida. As chaves são geradas com secrets.token_urlsafe, hasheadas com bcrypt e guardadas em SQLite; a validação usa bcrypt.checkpw. Senhas de usuário também são hasheadas com bcrypt. Corresponde ao Capítulo 6 do livro Model Context Protocol (Sandeco).

Arquitetura

database.py    → SQLite (tabelas users, api_keys) — grava em data/database.db
repository.py  → UserRepository / APIKeyRepository (SQL parametrizado)
generate_api_key.py → par (segredo, hash bcrypt)
api_key_controller.py → orquestra geração/validação/máscara de chaves
server_seguro.py → tools MCP protegidas (tool_segura, listar_usuarios)
main.py        → CLI de bootstrap (create-user / gen-key / list-users)

Formato da chave pública: sk-{user_id}-{secret} (só o hash do segredo é persistido).

Uso

uv sync

# 1) cria um usuário (senha hasheada com bcrypt)
uv run python src/main.py create-user --name "Giulia" --email giulia@ex.com --password ***

# 2) gera a API Key (exibida UMA vez)
uv run python src/main.py gen-key --user-id 1 --name "chave-dev"

# 3) configure a chave no ambiente
cp .env.example .env   # e cole a full key em GIULIA_AI_API_KEY

# 4) sobe o servidor MCP
uv run python src/server_seguro.py

Com a chave configurada, a tool tool_segura retorna uma saudação com os dados do usuário autenticado; sem chave (ou inválida), toda tool lança API Key inválida.

Segurança

• Segredos hasheados (bcrypt + salt), nunca em texto puro no banco.
• SQL sempre parametrizado (sem injeção).
• Chave exibida uma única vez; no banco fica só a versão mascarada + hash.
• .env e data/*.db fora do controle de versão (ver .gitignore).

Custo da validação

Cada chave guarda dois derivados: o hash bcrypt (o verificador) e um lookup_hash (SHA-256, apenas um índice). A validação localiza a linha exata pelo índice e roda bcrypt.checkpw uma vez. Antes o bcrypt rodava contra todas as chaves do usuário até casar — O(n) numa função que é lenta de propósito.

SHA-256 puro seria fraco para senha, mas o segredo aqui tem 32 bytes de secrets.token_urlsafe: não há dicionário que ataque isso. É o mesmo desenho usado por provedores de API em produção — índice rápido para achar, verificador lento para confirmar. Bancos criados antes da coluna existir são migrados automaticamente, e as chaves antigas continuam válidas.

Limitação: isto não autentica o chamador

A tool lê a chave de os.getenv("GIULIA_AI_API_KEY") — do ambiente do próprio servidor, não de um parâmetro enviado pelo cliente.

Em stdio o servidor MCP é um processo filho do cliente: um processo, um cliente. Não existe "outro chamador" para distinguir — a fronteira de confiança é o sistema operacional, não o protocolo. O que este projeto entrega é credencial bem guardada + um gate de configuração.

Autenticação de chamador só passa a fazer sentido com transporte HTTP, com a chave viajando na requisição. Essa camada não está implementada aqui.

Testes

uv run pytest        # 33 testes, contra SQLite temporário

Cobrem o formato da chave, o não-vazamento do segredo no arquivo do banco, o mascaramento, a validação (incluindo chave de outro usuário), a contagem de chamadas ao bcrypt, a migração do lookup_hash e a revogação.