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; as únicas ações com efeitos são pedir um diagnóstico RCA (cria um relatório IA), propor uma ação que uma pessoa aprova na app (propose_action) e registar que o agente se absteve de um dataset untrusted (get_trust_decision com consumer_name).

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.

As duas tools das políticas (backend/app/mcp_policies.py) só leem e existem também no modo HTTP. Servem para um agente saber que regras se aplicam e onde há exceções em vigor. Levam ids de políticas, datasets e exceções, mas de pessoas só o nome do dono da política: nem quem pediu ou decidiu uma exceção, nem ids de contas. Com domínios restritos, as rotas das políticas são só de admins: um token recebe 403, e a tool devolve-o como error com o status_code, como as outras recusas (o mesmo para uma política que não existe, 404).

A tool das tarefas (backend/app/mcp_tasks.py) também só lê e existe nos dois modos. Mostra só o que a pessoa vê e pode decidir no ecrã de origem, e de pessoas não leva ids nem nomes (nem a conta ausente por quem se decide, nem o produtor de uma proposta de contrato, que fica sem detalhe). O modo HTTP só aceita tokens, por isso lá a lista vem sempre vazia: a caixa de uma pessoa lê-se em stdio, com o email e a password dela. Decide-se na app, no ecrã de origem (link_to).

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()))

Proveniência dos resultados (cartão #702)

Os resultados levam texto que vem das fontes e das pessoas do workspace: nomes de datasets e de colunas, tipos declarados na fonte, descrições, títulos de issues, mensagens das regras, entradas da base de conhecimento, relatórios e o SQL das linhas em falha. Esse texto é dado, nunca instrução, e um agente que o leia como ordem sofre uma injeção indireta. Por isso cada tools/call e cada resources/read levam no _meta a chave beryxtech.com/provenance (backend/app/mcp_provenance.py):

Um issue com um pedido no título, em list_issues:

{"_meta": {"beryxtech.com/provenance": {
  "provenance": "untrusted_content",
  "untrusted_fields": ["result[].dataset", "result[].tickets[].key", "result[].title"],
  "suspicious": [{"field": "result[].title", "signals": ["override", "addressed_to_model"]}],
  "notice": "Os campos em untrusted_fields trazem texto das fontes e das pessoas do workspace: …"
}}}

• De sistema só o que o produto gera. Conta como de sistema o texto curto sem espaços numa chave de ids, datas ou enums (id, …_id, …_at, status, severity, kind…), mais os números e os booleanos. Tudo o resto entra marcado, incluindo uma chave que o resumo ainda não conhecia e uma frase do produto com um nome lá dentro («PII sem máscara em camada gold (nif)»).
• Assinala, não apaga. O detetor (backend/app/domain/llm/injection.py) reconhece as marcas de delimitador que o assistente da app neutraliza (cartão #340) e as formas de pedido do golden adversarial. O texto chega como está: o SQL tem de correr e uma descrição tem de se ler igual. É uma heurística, por isso um campo fora de suspicious continua a ser conteúdo de origem.
• As instruções do servidor (a resposta ao initialize) dizem ao agente que os campos de untrusted_fields são dados e que não segue pedidos escritos neles. Um cliente que não passe o _meta ao modelo fica com essa instrução.
• Tetos: até 100 caminhos em untrusted_fields e 100 em suspicious; acima, truncated: true. O call_tool direto do FastMCP, para quem embute o servidor em Python, devolve a forma do SDK, sem o _meta.

Testes: backend/tests/test_mcp_provenance.py (um caso por tool e por resource, os casos do golden de injeção pelo MCP) e backend/tests/test_llm_injection.py.

Propor ações (agentes externos)

Cartão #383. Um agente externo (Claude Code, Cursor, um pipeline) pode propor issues, tickets, regras ou tarefas de governação. Uma pessoa decide na app e o token nunca executa.

1. Um admin cria um token com o scope actions:propose em Equipa → Tokens de API. O token lê como os outros e só escreve em POST /api/v1/assistant/actions/propose. Em stdio, BERYX_TOKEN com esse token substitui o email e a password.
2. O agente chama propose_action. A proposta passa pelas validações do chat: parâmetros do tipo, política do workspace e acesso aos datasets do token. Fica num pedido pending durante 7 dias.
3. Quem tem o papel de aprovação da política vê o pedido em Equipa → Ações da IA, com o selo «Agente externo», o token e o agente, e aprova ou recusa. Os canais que recebem alertas warning do dataset são avisados (datavault.assistant.action_proposed, ver WEBHOOKS.md).

O token propõe como um membro: um tipo que só um admin propõe é recusado. A auto-aprovação da política não se aplica, as ações em lote (bulk_action) ficam no chat, o limite diário da política dá 429 e cada token tem no máximo 20 propostas à espera. Executar, aprovar ou recusar com um token dá sempre 403. A auditoria guarda origin, api_token_id e agent no pedido (assistant_action_requested) e na execução (assistant_action_executed).

Exemplo: o Claude Code abre um ticket a partir de um veredito falhado.

claude mcp add --transport http beryx https://mcp.beryxtech.com/mcp \
  --header "Authorization: Bearer dvk_…"

Pedido ao agente: «Se o veredito de gold.vendas falhou, propõe um ticket no Jira para o issue aberto mais grave.» O agente chama get_verdict e list_issues e, no fim:

{
  "kind": "create_ticket",
  "params": {
    "entity_type": "issue",
    "entity_id": "<id do issue>",
    "title": "Nulos em email bloqueiam o gate de gold.vendas",
    "body": "O veredito falhou com 30% de nulos em email desde o último scan."
  },
  "agent": "Claude Code"
}

A resposta traz o pedido (id, status: pending). O agente acompanha-o com get_action_request ou com datavault://actions/pending. No SDK Python: dv.actions.propose(...) e dv.actions.wait(...) (ver sdk/README.md).

Pré-visualização do pedido (cartão #699)

O propose_action e o get_action_request, enquanto o pedido está pending, devolvem a preview: o que muda se uma pessoa aprovar, calculado no servidor e sem IA. O mesmo estado dá a mesma resposta. Tem quatro partes, cada uma com status: known, unknown (com o reason_code) ou none (não se aplica).

• diff: campo a campo (field, before, after, status). Numa regra, os campos da regra nova; num propose_contract, o contrato que a proposta gravaria face ao ativo, secção a secção. Cada valor mostra até 500 carateres. Dois valores que só diferem depois disso mostram-se a partir de pouco antes da diferença, e não como iguais. Uma linha que não se consegue comparar vem com status: unknown e o reason_code, e não fica de fora. Num termo do glossário, o «antes» é o que estava aprovado. O que o fluxo aprovou vem inteiro do pedido. Aprovado fora do fluxo, vem do histórico, que só guarda a definição até 500 carateres (history_truncated). Uma edição retida compara a proposta com o termo. Um domínio apagado e um owner apagado (RGPD) não entram no diff. Num pedido de um fluxo cujo objeto mudou depois de pedido, o diff sai unknown com object_changed: decidir dá conflito e nada se aplica.
• impact: os datasets do pedido (targets), os que estão a jusante (downstream, até 3 saltos) e os consumidores (consumers): dashboards, exposures do dbt e os agentes e aplicações que consumiram nos últimos 30 dias. Um dataset que o token não vê sai como «Dataset restrito». Um dataset do pedido que já não existe deixa o impacto unknown (dataset_missing).
• baseline: se a aprovação reinicia o histórico de uma regra ou a afinação de um detetor. Nenhum tipo de hoje o faz; uma regra nova começa vazia (starts_empty). Num lote (bulk_action) fica unknown.
• cost: o custo estimado por scan (scan) e de IA (llm). Nenhuma aprovação chama um LLM. Uma regra lê mais da fonte em cada scan em dois casos. O primeiro é quando faz a sua própria consulta (expression, custom_sql, referential, a unique com colunas e a not_null com treat_as_null). O segundo é quando precisa de linhas (pattern, por exemplo) e nenhuma outra regra ativa do dataset as pede. Nesses casos custa, no BigQuery, até o tamanho da tabela ao preço por TiB, em USD. Numa fonte que cobra o tempo de computação (Snowflake, Databricks, Fabric e Redshift) fica unknown com compute_billed. Nas fontes de ficheiros e de APIs fica unknown com price_unknown.

Um pedido sem dataset traz o impacto unknown com reason_code: no_dataset, e não uma lista vazia. A caixa «As minhas tarefas» da app mostra a mesma pré-visualização, e os pedidos dos fluxos de aprovação têm-na em GET /api/v1/approvals/requests/{id}/preview (backend/app/domain/governance/request_preview.py). Exemplo de uma regra num dataset do BigQuery com 2,5 GB:

{
  "subject": "rule",
  "diff": {
    "status": "known",
    "changes": [
      {"field": "rule_type", "before": null, "after": "expression"},
      {"field": "severity", "before": null, "after": "critical"}
    ]
  },
  "impact": {
    "status": "known",
    "targets": [{"name": "gold.vendas", "depth": 0}],
    "downstream": [{"name": "Dataset restrito", "depth": 1, "restricted": true}],
    "consumers": [{"name": "agente-vendas", "type": "agent", "node": "consumer", "depth": 1}]
  },
  "baseline": {"status": "known", "resets": false, "effects": [{"kind": "rule", "effect": "starts_empty"}]},
  "cost": {"status": "known", "items": [
    {"kind": "scan", "status": "known", "amount": 0.0142, "currency": "USD"},
    {"kind": "llm", "status": "none", "reason_code": "no_scan_or_llm"}
  ]}
}

Identidade e governança por agente (cartão #674)

Um token criado com agent_id (POST /api/v1/auth/tokens) é a identidade de um agente registado em /api/v1/compliance/ai-agents. O servidor MCP manda o nome da ferramenta em cada chamada à API, no cabeçalho X-Beryx-MCP-Tool (read_resource nas leituras de resources), e o nome do cliente MCP em X-Beryx-MCP-Client. Com um token de agente, a API aplica a ficha dele em cada pedido (backend/app/api/agent_access.py):

• o kill-switch global e o do agente (suspenso ou retirado) recusam tudo com 403;
• com ferramentas na ficha, uma ferramenta fora da lista recebe 403 agent_tool_not_allowed;
• o X-Beryx-MCP-Tool vem de quem chama, e quem tem o token também chama a API REST sem passar pelo servidor MCP. Por isso a API só aceita a ferramenta numa rota que essa ferramenta chama (backend/app/domain/compliance/ai_agent_tools.py, cartão #741). Noutra rota, ou com um nome que não é de uma ferramenta do servidor, o pedido recebe 403 agent_tool_route_mismatch, também sem ferramentas na ficha. Uma rota que várias ferramentas chamam (o detalhe de um dataset: get_dataset, match_datasets e read_resource) passa com a linha da matriz de qualquer uma;
• um dataset classificado (colunas PII ou confidenciais, ou um CDE) só o lê um agente aprovado, com finalidade declarada e com a checklist de go-live completa (cartão #725), se o dataset lhe estiver ligado (a checklist verificou-o) e por uma ferramenta que a matriz de direitos deixa chegar a dados classificados; os outros recebem 403 agent_classified_denied, com o id no path ou na query, e o mesmo num domínio que tenha um dataset classificado (/domains/{domain_id} incluído);
• com domínios na ficha, um dataset ou um domínio fora deles recebe 403 agent_outside_domains;
• as listagens sem filtro (list_issues(), list_suggestions(), search_knowledge(), GET /datasets, /rules, /search…) deixam de fora os datasets que a ficha não deixa ler e, dos domínios que os têm, o relatório e a certificação do domínio; list_domains() mostra o nome desses domínios, sem datasets nem pontuação. Um dataset desses no corpo de um POST dá 404, como o de um domínio restrito sem concessão, e no gate RAG o corpus também;
• as vistas do workspace inteiro (painéis, grafo do conhecimento, qualidade dos metadados) e as leituras que não filtram por dataset (os dois SSE, o sistema de IA do art. 10.º, as integrações, as listas de referência) recebem 403 agent_workspace_view_denied enquanto a ficha lhe retiver datasets ou domínios. Ficam abertos os pedidos de ação do próprio token (get_action_request() e o resource das ações por aprovar).

Com matriz de direitos, cada ferramenta tem um teto de pedidos por hora (acima dele, 429 agent_tool_limit) e o propose_action só propõe os tipos de ação da matriz (403 agent_action_not_allowed). Ligar outro dataset a um agente aprovado devolve-o a proposto, como mudar a matriz. O kill switch do agente (POST /api/v1/compliance/ai-agents/{agent_id}/kill) revoga os tokens dele: a chamada seguinte dá 401.

Um token de agente tem o scope read ou actions:propose: o config, que aplica o datavault.yaml, é recusado com 422 ai_agent_token_scope. Cada pedido, aceite ou recusado, fica no registo de uso (GET /api/v1/compliance/ai-agents/usage). Um token sem agent_id funciona como antes.

Em nome de uma pessoa (cartão #733)

Quando o agente age por uma pessoa (o analista que pediu ao Claude Code, um assistente interno), o pedido diz quem ela é no cabeçalho X-Beryx-On-Behalf-Of, com o id ou o email de uma conta ativa do workspace do token. O servidor MCP manda-o em cada chamada à API: em stdio, a partir de BERYX_ON_BEHALF_OF (só com BERYX_TOKEN); em HTTP, a partir do mesmo cabeçalho do pedido do cliente MCP (backend/app/mcp_server.py). As regras vivem em backend/app/domain/compliance/ai_agent_on_behalf.py:

• só vale num token de um agente com acts_on_behalf: true na ficha (PATCH /api/v1/compliance/ai-agents/{agent_id}). Num token sem agente, num agente sem a capacidade ou numa sessão de utilizador dá 403 agent_on_behalf_not_allowed;
• uma pessoa que não é uma conta ativa deste workspace (de outro workspace, desativada ou que não existe) dá 403 agent_on_behalf_unknown;
• o pedido passa só com o que o agente E a pessoa podem. Um dataset ou um domínio no path ou na query que o token lê e a pessoa não (de outra equipa no modo isolado, por exemplo) dá 403 agent_on_behalf_denied. As listagens deixam de fora o que a pessoa não vê, e as vistas do workspace inteiro fecham-se quando a pessoa não vê tudo o que o token vê;
• em nome de um Leitor, o propose_action é recusado pela política (um Leitor não propõe ações) e as outras escritas do token, que um Leitor não faz na app, dão 403 agent_on_behalf_denied;
• o cabeçalho só estreita: é uma declaração do agente, não uma prova da pessoa. A concessão da pessoa num domínio restrito não abre ao token o que ele, sozinho, não lê (um token não tem equipas), e um dataset invisível ao token continua a dar 404;
• o registo de uso guarda a pessoa (on_behalf_of_user_id), e os eventos de auditoria trust_decision_checked e ai_output_checked juntam-na ao token. Uma proposta guarda o agente registado e a pessoa (ai_agent e on_behalf_of no pedido; ai_agent e on_behalf_of_user_id na auditoria), e Equipa → Ações da IA mostra «Proposto por em nome de ».

Sem o cabeçalho, nada muda.

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.beryxtech.com/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.beryxtech.com/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.beryxtech.com/mcp",
      "headers": { "Authorization": "Bearer dvk_…" }
    }
  }
}

Testar com o MCP Inspector: npx @modelcontextprotocol/inspector → transporte Streamable HTTP, URL https://mcp.beryxtech.com/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, fora das exceções da API), por isso nenhuma tool ou resource escreve, exceto propose_action: com um token de scope actions:propose cria uma proposta que uma pessoa aprova na app (ver «Propor ações»). A outra escrita é o registo de uma abstenção pelo get_trust_decision com consumer_name, só com ids e rótulos.

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)
• «Posso correr este SQL no meu agente? SELECT … FROM gold.encomendas e JOIN gold.clientes c …» (usa check_sql_trust — diz a decisão de cada tabela e qual manda)
• «Quantos clientes do CRM não existem no ERP?» (usa match_datasets)
• «Isto já aconteceu antes? Como resolvemos da última vez?» (usa search_knowledge)
• «Que políticas aprovadas se aplicam aos dados de vendas e quanto se cumprem? Há exceções que acabam este mês?» (usa get_policy e list_waivers)
• «O que tenho por decidir? Há alguma coisa vencida?» (usa list_my_tasks, com as minhas credenciais)
• «Há issues critical abertos? Diagnostica o mais recente.»
• «Que sugestões de deduplicação temos com SQL pronto?»