Documentation

Overview

Agents need catalog context: the right datasets, their lineage, the queries that feed them. Handing an agent an admin token to the whole metadata graph is reckless — one bad instruction and it reads, or writes, everything. DataCards takes the model the card industry settled on decades ago and applies it to metadata access: the data steward stays the owner, and the agent gets a card, a scoped authority to draw from the catalog.

• Your DataHub is the account. Nothing is copied or exported; the agent always reads the live catalog through the server.
• The card is a policy. Terms compiled to an enforceable rule set: allowed domains / platforms / entity types / entity URNs / glossary terms, lineage depth, call budget per fixed window, lifetime cap, usage count, expiry, and write-back scope.
• The agent holds the card, not the keys. What the agent gets is an MCP endpoint URL. Behind it, every call is checked against the card's terms and metered on a ledger — the agent never holds credentials to the catalog.
• Revoke kills it instantly. Freeze or revoke a card (or its whole sub-card tree) and every tool call stops, server-side immediately.

DataCards is a fork of GlassPay — an agentic spending-card system — re-aimed at metadata. The same enforcement shape applies: typed refusals instead of silent failures, a metered ledger, sub-card attenuation, and OpenTelemetry traces for every tool call. It plugs into any DataHub deployment through the standard GraphQL API.

How a Data Call Happens

One agent tool call, end to end:

1. The agent calls a tool on its MCP connection (say search). The connection URL encodes a secret card id.
2. The server loads the card and its ancestor chain. Every card in the chain must be alive: not frozen, not revoked, not expired — a liveness check.
3. The call is validated against every ancestor's budget (each costs 1 unit): the fixed-window period cap, the lifetime cap, and the usage count. Refusals are typed and structured, not generic errors.
4. The request is scoped before it ever leaves the server: search filters (domains, platforms, entity types, glossary terms) are injected into the upstream GraphQL query, and lineage is capped at the card's depth. Direct URN reads are gated against the fetched entity's facts.
5. On success the ledger records one debit against the card (idempotent on a retry key, so a flaky network can't double-charge), an OpenTelemetry span closes with the tool name and card id, and the response carries the remaining budget so the agent can pace itself.

Enforcement & Refusals

A refused call is not an error blob — it is a structured refusal naming the violated term, so the agent can explain itself and adapt. The MCP response carries isError: true and a JSON body like this:

{
  "status": "refused",
  "code": "over_period_limit",
  "message": "this call exceeds the period budget (498/500 used)",
  "detail": {
    "card_id": "card_8f2c",
    "remaining_this_period": 2,
    "period_resets_at": 1786646400
  }
}

The refusal codes the engine emits:

Issuing a Card

The steward issues a card from the dashboard: name the agent's mission, compose the scope (domains, platforms, entity types, specific URNs, glossary terms), set the budget (calls per window, lifetime cap, expiry), and choose whether the card may write documents back. Issuing is one REST call:

POST /api/cards
Authorization: Bearer <DATACARDS_ADMIN_TOKEN>

{
  "name": "revenue-analyst",
  "terms": {
    "scope": {
      "domains": ["urn:li:domain:finance"],
      "entityTypes": ["DATASET", "DASHBOARD"],
      "glossaryTerms": ["urn:li:glossaryTerm:revenue"],
      "lineageDepth": 2
    },
    "budget": { "period": { "amount": 500, "seconds": 86400 } },
    "mutations": "documents",
    "expiry": 1789488000
  }
}

→ 201 {
  "card_id": "card_8f2c",
  "card_url": "https://datacards.example/c/secret…/mcp",
  "terms": { …compiled terms… }
}

The response's card_url is the only thing the agent ever needs. Paste it into Claude Code, Cursor, or any MCP client — the server surfaces the tool list from the card's terms.

Card Terms

The terms vocabulary (the terms_json in the engine's card table):

Every card needs at least one budget cap (budget.period and/or budget.lifetime); scope is optional and an absent scope means full-catalog reads — still budgeted, still expiring, still revocable. All URNs are normalized (lowercased, deduped) at compile time and validated before a card is stored.

Sub-Cards & Attenuation

An agent with a card can delegate downward: issue_subcard mints a tighter card for a sub-agent. Sub-cards are the enforcement surface's attenuation rules, applied at issue time:

• Scope is subset-only and restriction-inheriting. A child may not name a domain, platform, entity, glossary term, or depth the parent doesn't already have — and any restriction the parent carries that the child omits is inherited, so a sub-card can never be wider than its parent.
• Budget inherits capped to remaining. Omitted child budgets inherit the parent's cap, clamped to what's actually left. Explicit caps must fit inside both the parent's cap and its remaining budget.
• Mutations only narrow. A child can take documents → none, never the reverse. Write-back is never silently inherited.
• Expiry never extends. A child's expiry cannot outlive the parent's.
• Every child call draws down ancestors. The ledger walks the whole chain, so a sub-agent can never exceed a budget its parent didn't approve.

A parent can kill any direct sub-card with revoke_subcard — descendants die with it. The steward's dashboard can freeze, revoke, or delete any card in the tree.

Connecting an Agent

The agent connects with the card URL, exactly like any other MCP server:

claude mcp add datacards --transport http https://datacards.example/c/card_8f2c_<secret>/mcp

At initialize the server reports its tool list — derived from this card's terms. A read-only card never sees save_document; a card with subcards: false never sees issue_subcard. The tool list is the permission surface. The server also embeds instructions that route the agent to the right tool for its first move, and most clients index that text for tool search.

MCP Tools

Every call is wrapped in an mcp_tool_<name> OpenTelemetry span with the tool name, card id, error flag, and refusal code as attributes — the activity feed in the dashboard and your OTLP collector read the same events.

Auth & Connection URLs

Two auth surfaces, deliberately different:

• Stewards (the dashboard) sign in with the server's admin token (DATACARDS_ADMIN_TOKEN), sent as a bearer token on every API call — or with a self-hosted OAuth 2.1 authorization-code flow when configured.
• Agents (MCP) authenticate with the card URL's secret. The server resolves the card, checks liveness, and answers only within the card's terms. No agent ever sees a DataHub credential.

Observability

Every tool call is a trace, every refusal is a trace event with its code, every ledger write is a metric. The server ships OpenTelemetry with configurable OTLP export (SigNoz, Grafana, Jaeger — any collector). What you get:

• Traces: mcp_tool_<name> spans with card id, error flag, refusal code, and latency. See which agents burned budget on what, and where.
• Metrics: access counts, refusal counts by code, budget consumption per card.
• Logs: structured access events with card, tool, target URN, and status — the raw audit trail for every card, queryable in the dashboard's activity feed.

REST API

The dashboard speaks to the same HTTP surface you can curl:

Every response carries the card's remaining budget where relevant, and every mutation is recorded in the same access log the agents produce — the steward's dashboard shows humans and agents on one ledger.

Self-Hosting

Three processes, one DATAHUB_GMS_URL pointing at your DataHub GMS:

• datacards-api — the Hono server: REST API, MCP endpoint, OAuth, OTLP export. Storage is a SQLite file (set DATACARDS_DB_PATH); budget windows and ledger are computed there.
• datacards dashboard — the Next.js app (admin token login, card deck, terms composer, activity feed). Set NEXT_PUBLIC_DATACARDS_API and the server's admin token.
• DataHub — your existing GMS. The server only ever talks to it through GraphQL, with scopes injected upstream.

# server
DATACARDS_ADMIN_TOKEN=…          # steward bearer token (the dashboard login)
DATAHUB_GMS_URL=https://datahub.example/graphql
DATACARDS_PUBLIC_MCP_BASE=https://datacards.example   # mints card URLs
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 # optional
DATACARDS_DB_PATH=./datacards.db