MCP tools in the app

The MCP Tools page is the in-app home of your workspace's MCP server: everything needed to connect an agent, manage access tokens, try the nine tools against your real governed data, review call telemetry, and read the tool contract — in five tabs: Connect, Tokens, Tools, Requests, and Reference.

Connect

The Connect tab surfaces the two things every client setup needs. First, your MCP server URL, with a copy button — the endpoint accepts POST requests with bearer authentication, and the same endpoint serves every workspace (your token selects yours). Second, ready-to-paste client config snippets for Claude Code, Cursor, and curl, prefilled with your real endpoint and a mtt_<your-access-token> placeholder to replace with a token from the Tokens tab.

The Metatate Runtime Status card reports the in-app tool surface: whether the canonical tool inventory is fully registered for your workspace, the server name, the registered-tool count, and how many governed tables the current publication serves (shown as "N/A" rather than a fabricated zero when the count cannot be read). It describes in-app registration — connecting an external client always goes through the deployed endpoint.

A quick-starts card suggests the fastest first calls — decision context for a table, then discovery, then an advisory authorization — and a step-by-step guide walks through issuing a token, configuring a client, and trying calls in the workbench first. Nothing governed yet? Load the sample workspace and the quick starts answer immediately.

Tokens

Access tokens are managed here by workspace admins and owners; other members see a pointer to ask an admin instead.

Issue a token with a name and an optional expiry, plus three optional identity fields — agent kind, agent name, and bound role — and one scope choice. The value (mtt_ followed by 64 hex characters) is displayed exactly once, alongside a copy button and a prefilled Claude Code registration command; only a hash is stored, so the value can never be shown again.

The scope choice is the write-lane opt-in. A checkbox on the issue form grants the request scope alongside the always-present read. It is never pre-checked. Without it the token can call the eight read and advisory tools, including check_request; with it the token can also call request_access, the one tool that writes. A token calling a tool it lacks the scope for is refused before its input is even parsed.

Each token row shows its name, display prefix, expiry or "No expiry", its identity summary when it has one, a scopes badge (Read or Read + request), and an Active / Revoked / Expired status. Active rows offer Rotate and Revoke.

Rotate is how you change a token's scopes, because scopes are immutable for the life of a token. Rotation mints a new secret — displayed once, same as issuance — copies the name, expiry, and identity forward, and revokes the old token in the same transaction. The rotate panel pre-fills the request-lane checkbox from the token's current scopes: leave it alone to preserve them, tick it to upgrade, untick it to downgrade. The audit event records both the old and the new scope set, which is the durable evidence of a write-lane grant.

One consequence: rotation mints a new subject identity, so a rotated token cannot see the previous token's access requests or use its granted exceptions. Resolve or re-file after rotating.

Revocation takes effect immediately for new requests, and issue, rotate, and revoke events all land in the workspace Activity log.

Tools

The Tools tab runs real tool calls against your workspace's governed data. Results are advisory and read-only — nothing here mutates governance state.

Authorize a use is a structured surface for the most common question: pick an asset (database, schema, table, optional column), describe the proposed use, optionally state a purpose_key and an ISO-8601 as-of anchor, add transfer context when relevant, and run. A natural-language assist box can prefill the structured fields from a sentence. The result renders as a full decision card: the typed state, the effective decision, cited instructions and policies, purpose-bound access-window details when present, and publication provenance.

Workbench exercises any of the nine canonical tools. Pick a tool, fill its input — an asset picker over your governed catalog and per-tool example buttons make the JSON shape discoverable, and the input stays an editable JSON textarea — then run it. Results are explained in plain language with the raw payload one click away.

The workbench runs in two modes:

• In-app preview (default) — runs against your workspace's published state in-app, under your own member permissions. No token needed; the fastest way to iterate.
• Live endpoint — sends a real tools/call to the deployed MCP endpoint with a token you paste, the exact path an external client uses. Use it to verify a token and reproduce exactly what an agent will see.

Both modes read the same published state and share one answer model, so a call that answers in preview answers identically at the endpoint. Several capabilities are endpoint-only, and the preview refuses them explicitly rather than guessing or silently ignoring them:

• validate_query_context — SQL identifier extraction runs only on the deployed endpoint.
• request_access and check_request — the request lane needs a verified token: the write lane needs the request scope, and status reads are pinned to the calling token's own requests. Stewards see request status in Activity → Review requests instead.
• discover_context's classification-fact filters (domain, sensitivity, pii, compliance_tag) — the preview lists and pages by database and schema.

Switching to live-endpoint mode covers all of them.

One more preview detail matters for access windows: the structured form can supply purpose and as-of context, but in-app preview has no token-bound agent role. It therefore cannot reproduce a role-bound window allow. Use live-endpoint mode with the intended token to verify that case; preview remains the deliberately conservative view.

Requests

The Requests tab is the per-token MCP request log — telemetry about tool calls made with your workspace's tokens. It lives here in the MCP module at /[tenantSlug]/mcp?tab=requests, with its own CSV export at /[tenantSlug]/mcp/requests/export. It is useful for confirming that a client is actually reaching the endpoint and for seeing which tool a failing agent called. Each token row in the Tokens tab has a "View requests" link that deep-links here filtered to that token.

Do not confuse it with Review requests at /[tenantSlug]/activity/review-requests, which is the steward queue for access requests filed by agents. Same word, different surface: this tab is call telemetry, that one is a review workflow. They are separate modules — this telemetry tab is not part of Activity and did not move.

Reference

The Reference tab documents the contract in-app: how the tools work (one canonical tool contract, workspace-scoped bearer auth, advisory posture, closed error codes), the Claude Code plugin install steps, the generic any-MCP-client setup, and a reference list of the tools rendered from the same contract the server registers. The same material, in more depth, lives in the MCP server overview and the per-tool pages such as authorize_use.

In-app testing versus a real agent

Use the Tools tab before wiring an agent: confirm your published state actually answers (a not_enough_published_state here will be the same for every client — see typed answer states), pin down the exact input shape a call needs, and verify a freshly issued token in live-endpoint mode. Then move to a real client — the Claude Code plugin or any MCP client — for end-to-end workflows, and to the cookbook for patterns worth shipping. If your agent needs the request lane, issue it a {read, request} token and read Review requests so someone is watching the inbox. If you are starting from zero, the quick start gets a first publication live so there is something to answer with.