MCP Database Server

Pilar: Protocolos, Interoperabilidade & APIs
Status: Mes 1 - essencial

Servidor MCP em Python para expor schemas, queries seguras e stored procedures a clientes LLM.

Problema

LLMs precisam consultar bancos corporativos sem receber credenciais amplas nem liberdade para executar SQL destrutivo.

MVP

• Servidor MCP com FastMCP
• Listagem de schemas permitidos
• Queries somente leitura
• Allowlist de stored procedures
• Auditoria de chamadas

Arquitetura

• MCP server (mcp.server.MCPServer, tools registrados via @mcp.tool())
• Schema registry (allowlist de tabelas/colunas, db.py)
• Read-only authorizer (sqlite3.Connection.set_authorizer, security.py)
• Audit logger (trilha em memoria de cada chamada de tool, audit.py)

Diagrama

flowchart LR
    A0[MCP client] --> A1[MCP server: list_tables / describe_table / run_readonly_query]
    A1 --> A2[SQLite authorizer: allowlist + read-only]
    A2 --> A3[SQLite: invoices]
    A1 --> A4[Audit log]

Stack

• Python
• mcp (SDK oficial do Model Context Protocol)
• SQLite (sqlite3 da stdlib, com set_authorizer para o controle de acesso)
• unittest
• Docker Compose

Como executar

Implementacao real com o SDK oficial do MCP. O controle de acesso nao usa regex sobre o SQL (facil de burlar) - usa o set_authorizer do proprio SQLite, que aprova ou nega cada tabela/coluna lida e cada tipo de statement antes de qualquer linha rodar. Para rodar o servidor MCP:

python3.12 -m venv .venv && source .venv/bin/activate
pip install -e .
python -m mcp_database_server   # sobe o servidor MCP via stdio
python -m unittest discover -s tests

Testes

• test_security.py: authorizer bloqueia INSERT/UPDATE/DELETE/DROP/ALTER, ATTACH, tabelas fora do allowlist (ex.: sqlite_master) e statements empilhados (SELECT 1; DROP TABLE ...).
• test_server.py: logica de cada tool chamada direto (sem protocolo), incluindo que toda chamada gera um evento de auditoria.
• test_integration.py: sobe python -m mcp_database_server como subprocesso de verdade e conversa com ele via mcp.client.stdio + ClientSession - prova que o servidor fala MCP, nao so que as funcoes Python funcionam.

Riscos e decisoes

• SQL injection e permissao excessiva: resolvido via set_authorizer no nivel do driver, nao regex.
• Uma unica conexao SQLite nao e thread-safe; o MCP server despacha cada tool call numa worker thread, entao ServerState.lock serializa o acesso (bug real encontrado e corrigido durante a implementacao, coberto por test_integration.py).
• Ferramentas MCP retornam ValueError com mensagem clara para o cliente LLM em vez de vazar stack trace.

Proximos passos

• Trocar SQLite por PostgreSQL via SQLAlchemy quando o dado for real.
• Adicionar autenticacao/allowlist por cliente (hoje qualquer client MCP conectado tem acesso as tools).
• Persistir o audit log fora do processo (hoje e so em memoria).