BeryX MCP server

BeryX exposes data quality to AI agents through the Model Context Protocol (Claude Desktop, Claude Code, or any MCP client). The server is a bridge to the HTTP API — it authenticates as a normal user (workspace and RBAC respected) and is read-only on the sources; the only action with effects is requesting an RCA diagnosis (it creates an AI report).

Available tools

The four traversal tools (card #173) are deterministic: they call no LLM, so they work with BYOK, with AI turned off and without a key. The assistant chat uses the same functions (backend/app/domain/lineage/traversal.py) and the same summaries. Caps: 40 datasets and 60 edges (truncated: true when they are hit), names only — never the owner, the email or the URL of an exposure. A dataset in a restricted domain the caller has no access to appears as "Dataset restrito" (restricted dataset), with an opaque id (restrito-N) instead of the real one and without columns. An edge with one end in another workspace is ignored.

Resources (read-only, application/json)

Unified context per dataset (card #146)

get_dataset_context / datasets://{dataset_id}/context call GET /api/v1/datasets/{id}/context and return, in a single read, what used to require 6–8 calls. No LLM; limited to 6,000 characters (JSON) — when it does not fit, it cuts knowledge first and then schema and sets truncated: true with truncated_fields. Each section includes available; without data (e.g. a dataset with no scan) it comes with available: false and a reason instead of an error.

No sample value, email or URL leaves (free text is sanitised — [email], [url]).

The resources reuse the DataVaultClient and the summarize_* functions shared with the chat — tools and resources return exactly the same data.

Data product readiness

get_domain_readiness / domains://{domain_id}/readiness?use_case= proxy GET /api/v1/domains/{id}/readiness and return the API JSON as is (the chat tool returns the same, read directly from the session). An agent or pipeline that asks "is the Sales data product ready for RAG?" makes one call instead of N. States, codes and the CI gate: CI_QUALITY_GATE.md.

Readiness uses, per dataset, the same reading as the Trust API (#150) — the two responses never contradict each other — but has its own vocabulary (it aggregates per product):

LangChain example — check the product's readiness before indexing (alongside the per-document gate in RAG_GATE.md):

from beryx import BeryX

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

Installation

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

Configuration (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": "…"
      }
    }
  }
}

In Claude Code: claude mcp add datavault -- /caminho/backend/.venv/bin/python -m app.mcp_server (with the same environment variables).

Streamable HTTP mode (remote)

Production server — https://mcp.praxis.lbostuff.tech/mcp

The remote MCP is published (card #311): Cloud Run service datavault-mcp, managed TLS, nothing to install. All you need is a dvk_ API token (Team → API tokens, admins only) — from any machine, without this repository:

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

In another MCP client with HTTP support (Cursor, VS Code, Codex, Claude Desktop via mcp-remote), the app's Connect your agent page generates the exact configuration — see AGENTES_CODIGO.md. Generic format:

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

Test with the MCP Inspector: npx @modelcontextprotocol/inspector → Streamable HTTP transport, URL https://mcp.praxis.lbostuff.tech/mcp, header Authorization: Bearer dvk_….

Authentication: every request must carry Authorization: Bearer dvk_…. Without a token, or with a session JWT, the response is 401. The token is validated against the API itself (revocation and workspace respected) and is forwarded on every call: each customer sees only their own workspace. If the API does not respond, 503. OAuth 2.1 comes in a later slice (MCPV2).

Read-only surface: over HTTP the server is stateless and does not expose diagnose_issue — and dvk_* tokens are read-only on the API (any method other than GET returns 403), so no tool or resource writes.

Host and origin (anti-DNS-rebinding): the SDK's protection only switches on by itself with a bind on localhost. The server validates the Host header itself, before authentication, against an allowlist: the host of DATAVAULT_MCP_PUBLIC_URL plus those of DATAVAULT_MCP_ALLOWED_HOSTS (comma-separated; in production, the deterministic run.app URL). Outside the list: 421. A request with Origin (browser) only passes if the origin is https:// on a host in the list (http:// only on loopback); otherwise 403. With a bind on 0.0.0.0 and an empty allowlist, the server refuses to start. With a bind on loopback, 127.0.0.1/localhost/::1 are accepted as in the SDK.

Known limits:

• Revocation up to 60 s: positive token validations are cached per instance for 60 s (by hash — the token is never stored or logged). A revoked token may keep working until then.
• Shared per-IP rate limit: the API applies a per-IP limit (1,200 requests/min per instance, DATAVAULT_API_RATE_LIMIT_IP_REQUESTS) and another per token (300/min). All MCP clients reach the API from the egress IPs of datavault-mcp, so they share the per-IP limit; the per-token limit remains each client's own. The MCP does not forward X-Forwarded-For (it would be spoofable). Each tool makes 1–3 requests to the API.
• Cold start: min-instances 0 — the first request after a period without traffic takes a few seconds.

Operations (deploy)

deploy/gcp_deploy.sh (section 5e) creates the service from the backend image (mcp extra in CONNECTOR_EXTRAS) with python -m app.mcp_server --transport http --host 0.0.0.0 --port 8080:

The api receives DATAVAULT_MCP_PUBLIC_URL=https://mcp.${DOMAIN}/mcp, and that is what makes GET /ide/agent-config and the "Connect your agent" page generate the real configuration. CD updates the datavault-mcp image with the backend's. deploy/validate_prod.sh (step 16c, deploy/check_mcp_remote.sh) proves from outside, on every deploy: the advertised URL responds, without a token → 401, initialize and tools/list with a disposable dvk_ token (created, used and revoked) include get_verdict and get_trust_decision, and a Host outside the allowlist → 421 (via the service's legacy *.a.run.app URL, which reaches the container but is not on the list).

Your own server (self-hosted / development)

To run HTTP mode locally (endpoint /mcp):

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

Also configurable via the environment: DATAVAULT_MCP_TRANSPORT=http, DATAVAULT_MCP_HOST, DATAVAULT_MCP_PORT. Exposed on another machine (bind 0.0.0.0, behind TLS), set DATAVAULT_MCP_PUBLIC_URL to the public URL — it is the Host allowlist. In the app, the same setting on the api makes "Connect your agent" point to it; when it is empty, the configs point to http://127.0.0.1:8765/mcp and the page shows the command above.

Recommendation (stdio, with DATAVAULT_EMAIL/DATAVAULT_PASSWORD): create a member user dedicated to the MCP (POST /auth/users, admins only) — members cannot delete connections or invite users.

Example questions for the agent

• "Which dataset has the worst score and how much does it cost us per month?"
• "Can the clientes dataset be published?" (uses get_verdict)
• "Can I use gold.clientes in an agent? Who is the owner and what has gone wrong before?" (uses get_dataset_context)
• "Can my agent read gold.clientes now? And for RAG?" (uses get_trust_decision — the answer also says how long it is valid for)
• "What is known about the reliability of gold.encomendas? Who is the owner and is there unmasked PII?" (uses get_trust_facts)
• "How many CRM customers do not exist in the ERP?" (uses match_datasets)
• "Has this happened before? How did we resolve it last time?" (uses search_knowledge)
• "Are there open critical issues? Diagnose the most recent one."
• "What deduplication suggestions do we have with ready-made SQL?"