Servidor MCP do BeryX

O BeryX expõe a qualidade de dados a agentes IA via Model Context Protocol (Claude Desktop, Claude Code, ou qualquer cliente MCP). O servidor é um bridge para a API HTTP — autentica-se como um utilizador normal (workspace e RBAC respeitados) e é read-only sobre as fontes; a única ação com efeitos é pedir um diagnóstico RCA (cria um relatório IA).

Tools disponíveis

As quatro tools de travessia (cartão #173) são determinísticas: não chamam nenhum LLM, por isso funcionam com BYOK, com a IA desligada e sem chave. O chat do assistente usa as mesmas funções (backend/app/domain/lineage/traversal.py) e os mesmos resumos. Tetos: 40 datasets e 60 arestas (truncated: true quando cortam), só nomes — nunca o owner, o email nem o URL de um exposure. Um dataset de um domínio restrito sem acesso aparece como «Dataset restrito», com um id opaco (restrito-N) em vez do real e sem colunas. Uma aresta com uma ponta noutro workspace é ignorada.

Resources (read-only, application/json)

Contexto unificado por dataset (cartão #146)

get_dataset_context / datasets://{dataset_id}/context chamam GET /api/v1/datasets/{id}/context e devolvem, numa só leitura, o que antes exigia 6–8 chamadas. Sem LLM; limitado a 6000 caracteres (JSON) — quando não cabe, corta primeiro knowledge e depois schema e marca truncated: true com truncated_fields. Cada secção traz available; sem dados (ex.: dataset sem scan) vem available: false com reason em vez de erro.

Nenhum valor de amostra, email ou URL sai (texto livre é saneado — [email], [url]).

Os resources reutilizam o DataVaultClient e os summarize_* partilhados com o chat — tools e resources devolvem exatamente os mesmos dados.

Readiness de data products

get_domain_readiness / domains://{domain_id}/readiness?use_case= fazem proxy de GET /api/v1/domains/{id}/readiness e devolvem o JSON da API tal e qual (a tool do chat devolve o mesmo, lido direto da sessão). Um agente ou pipeline que pergunta «o data product Vendas está pronto para RAG?» faz uma chamada em vez de N. Estados, códigos e o gate de CI: CI_QUALITY_GATE.md.

A readiness usa, por dataset, a mesma leitura da Trust API (#150) — as duas respostas nunca se contradizem — mas tem vocabulário próprio (agrega por produto):

Exemplo LangChain — verificar a readiness do produto antes de indexar (ao lado do gate por documento de RAG_GATE.md):

from beryx import BeryX

readiness = BeryX().domain_readiness(VENDAS_DOMAIN_ID, use_case="rag")
if not readiness.ready:  # not_ready: não indexar
    raise RuntimeError(readiness.summary())
vectorstore.add_documents(splitter.split_documents(loader.load()))

Instalação

cd backend
pip install -e ".[mcp]"

Configuração (Claude Desktop / Claude Code)

{
  "mcpServers": {
    "datavault": {
      "command": "/caminho/backend/.venv/bin/python",
      "args": ["-m", "app.mcp_server"],
      "cwd": "/caminho/backend",
      "env": {
        "DATAVAULT_API_URL": "http://localhost:8000",
        "DATAVAULT_EMAIL": "utilizador@empresa.pt",
        "DATAVAULT_PASSWORD": "…"
      }
    }
  }
}

Em Claude Code: claude mcp add datavault -- /caminho/backend/.venv/bin/python -m app.mcp_server (com as mesmas variáveis de ambiente).

Modo Streamable HTTP (remoto)

Servidor de produção — https://mcp.praxis.lbostuff.tech/mcp

O MCP remoto está publicado (cartão #311): serviço Cloud Run datavault-mcp, TLS gerido, sem nada a instalar. Basta um token de API dvk_ (Equipa → Tokens de API, só admins) — a partir de qualquer máquina, sem este repositório:

claude mcp add --transport http datavault https://mcp.praxis.lbostuff.tech/mcp \
  --header "Authorization: Bearer dvk_…"

Noutro cliente MCP com suporte HTTP (Cursor, VS Code, Codex, Claude Desktop via mcp-remote), a página Ligar o teu agente da app gera a configuração exata — ver AGENTES_CODIGO.md. Formato genérico:

{
  "mcpServers": {
    "datavault": {
      "type": "http",
      "url": "https://mcp.praxis.lbostuff.tech/mcp",
      "headers": { "Authorization": "Bearer dvk_…" }
    }
  }
}

Testar com o MCP Inspector: npx @modelcontextprotocol/inspector → transporte Streamable HTTP, URL https://mcp.praxis.lbostuff.tech/mcp, header Authorization: Bearer dvk_….

Autenticação: cada pedido tem de trazer Authorization: Bearer dvk_…. Sem token, ou com um JWT de sessão, a resposta é 401. O token é validado contra a própria API (revogação e workspace respeitados) e é reencaminhado em todas as chamadas: cada cliente vê só o seu workspace. Se a API não responder, 503. OAuth 2.1 chega numa fatia seguinte (MCPV2).

Superfície só de leitura: em HTTP o servidor é stateless e não expõe diagnose_issue — e os tokens dvk_* são read-only na API (qualquer método que não GET dá 403), por isso nenhuma tool ou resource escreve.

Host e origem (anti-DNS-rebinding): a proteção do SDK só se liga sozinha com bind em localhost. O servidor valida ele próprio o header Host, antes da autenticação, contra uma allowlist: o host de DATAVAULT_MCP_PUBLIC_URL mais os de DATAVAULT_MCP_ALLOWED_HOSTS (separados por vírgula; em produção, o URL run.app determinístico). Fora da lista: 421. Um pedido com Origin (browser) só passa se a origem for https:// de um host da lista (http:// só em loopback); senão 403. Com bind em 0.0.0.0 e a allowlist vazia, o servidor recusa arrancar. Com bind em loopback, 127.0.0.1/localhost/::1 são aceites como no SDK.

Limites conhecidos:

• Revogação até 60 s: as validações positivas do token ficam em cache por instância durante 60 s (por hash — o token nunca é guardado nem logado). Um token revogado pode continuar a servir até lá.
• Rate limit por IP partilhado: a API aplica um limite por IP (1200 pedidos/min por instância, DATAVAULT_API_RATE_LIMIT_IP_REQUESTS) e outro por token (300/min). Todos os clientes MCP chegam à API a partir dos IPs de saída do datavault-mcp, por isso partilham o limite por IP; o limite por token continua a ser de cada cliente. O MCP não reencaminha X-Forwarded-For (seria falsificável). Cada tool faz 1–3 pedidos à API.
• Arranque a frio: min-instances 0 — o primeiro pedido depois de um período sem tráfego demora alguns segundos.

Operação (deploy)

deploy/gcp_deploy.sh (secção 5e) cria o serviço a partir da imagem do backend (extra mcp no CONNECTOR_EXTRAS) com python -m app.mcp_server --transport http --host 0.0.0.0 --port 8080:

A api recebe DATAVAULT_MCP_PUBLIC_URL=https://mcp.${DOMAIN}/mcp, e é isso que faz GET /ide/agent-config e a página «Ligar o teu agente» gerarem a configuração real. O CD atualiza a imagem do datavault-mcp com a do backend. O deploy/validate_prod.sh (passo 16c, deploy/check_mcp_remote.sh) prova de fora, a cada deploy: o URL anunciado responde, sem token → 401, initialize e tools/list com um token dvk_ descartável (criado, usado e revogado) têm get_verdict e get_trust_decision, e um Host fora da allowlist → 421 (pelo URL legado *.a.run.app do serviço, que chega ao contentor mas não está na lista).

Servidor próprio (self-hosted / desenvolvimento)

Para correr o modo HTTP localmente (endpoint /mcp):

DATAVAULT_API_URL=http://localhost:8000 \
python -m app.mcp_server --transport http --host 127.0.0.1 --port 8765

Também configurável por ambiente: DATAVAULT_MCP_TRANSPORT=http, DATAVAULT_MCP_HOST, DATAVAULT_MCP_PORT. Exposto noutra máquina (bind 0.0.0.0, atrás de TLS), define DATAVAULT_MCP_PUBLIC_URL com o URL público — é a allowlist do Host. Na app, a mesma setting na api faz «Ligar o teu agente» apontar para ele; vazia, as configs apontam para http://127.0.0.1:8765/mcp e a página mostra o comando acima.

Recomendação (stdio, com DATAVAULT_EMAIL/DATAVAULT_PASSWORD): cria um utilizador member dedicado ao MCP (POST /auth/users, só admins) — os members não podem apagar conexões nem convidar utilizadores.

Exemplos de perguntas ao agente

• «Qual é o dataset com pior score e quanto nos custa por mês?»
• «O dataset clientes pode ser publicado?» (usa get_verdict)
• «Posso usar gold.clientes num agente? Quem é o dono e o que já correu mal?» (usa get_dataset_context)
• «O meu agente pode ler gold.clientes agora? E para RAG?» (usa get_trust_decision — a resposta diz também por quanto tempo vale)
• «O que se sabe sobre a fiabilidade do gold.encomendas? Quem é o owner e há PII sem máscara?» (usa get_trust_facts)
• «Quantos clientes do CRM não existem no ERP?» (usa match_datasets)
• «Isto já aconteceu antes? Como resolvemos da última vez?» (usa search_knowledge)
• «Há issues critical abertos? Diagnostica o mais recente.»
• «Que sugestões de deduplicação temos com SQL pronto?»