Agent Guide: Integrating with the Library over MCP

On this page

• 1. The first call
• 2. Tiers and command floors
• 3. The canonical error envelope (DEC-1)
• 4. Canonical parameters and pagination
• 5. The 45 umbrellas, grouped by task
• 6. Task recipes
• 7. workflow recipes
• 8. The ux umbrella and the tester protocol
• 9. Pacing and limits an agent should respect
• 10. Where to look next

1. The first call

1.1 _hello — the gateway payload

_hello({}) needs no auth and has no side effects (scripts/mcp-server/umbrellas/_hello.ts:38-47 description). The default payload is built at _hello.ts:216-261 and carries:

Three startup patterns are served by that one call (manifest description): first-time agent → follow startup_hints.first_time / discovery.full_orientation to ux.session_start; returning agent → startup_hints.returning_agent (compact mode); status glance → version + status + current_release are already in the response.

_hello({intent: "<natural language>"}) returns a workflow plan (archetype, tool chain, confidence, recovery hints) — no auth, no side effects. _hello({command:'llm_smoke'}) is admin-only and bills real LLM spend; do not call it casually.

1.2 session_label and agent_info on every call

Two reserved gateway arguments are accepted on every tools/call, consumed and stripped before the target tool's Zod parse (lib/mcp/sessionEnvelope.ts:1-30, lib/server/session-per-call.ts). They are advertised on every tool's wire schema since v0.22.173 (LIB-BUG-1102).

Recommended first call:

health_check({ "session_label": "qa-run-2026-09-22a", "agent_info": { "model": "claude-opus-4", "provider": "anthropic", "version": "1.0", "effort": "high" } })

health_check mode:'quick' echoes a session {session_id, label, agent_info} field when tagging is enabled, so you can confirm attribution (tools/health_check.md).

2. Tiers and command floors

Single source of truth: config/mcp-tiers.config.ts. Hierarchy (each tier inherits the lower ones, header comment lines 11-12):

PUBLIC → FREE → EDUCATION → DEVELOPER → TEAM → ENTERPRISE → ADMIN → SUPER_USER

ANON_DENIED_TOOLS (line 251) removes tools from anonymous callers even when the tier lists them: admin, crawler, generalization, dataset_data, git. So dataset_data is in PUBLIC_TOOLS for a keyed public caller but unreachable anonymously — hold a key before relying on it.

Per-command floors live in config/command-auth.config.ts (header: "the single registry of PER-COMMAND authorization floors"): ADMIN_COMMAND_AUTH (line 35), CRAWLER_COMMAND_AUTH (78), DATASET_ADMIN_COMMAND_AUTH (88), DATASET_LIFECYCLE_COMMAND_AUTH (106), MDM_COMMAND_AUTH (115), and siblings. Umbrella visibility ≠ command permission: e.g. admin is reachable from free tier, but settings_set/flag_set/approval_decide floor at admin. Expect a typed refusal (§3), not silence, when you are under a floor.

Quota telemetry: metered successes carry _meta.usage {used, limit, reset_at}; the window is the UTC civil day and the refusal states the RFC 3339 reset_at (config/quota.config.ts:14-42). No other per-tool rate/pacing config was found under config/ for the MCP surface at v0.22.188 (only quota.config.ts matched); the embed-lane pacing rules are worker-side and not part of the tool contract.

3. The canonical error envelope (DEC-1)

The MCP/JSON-RPC surface uses the compact canonical MCP envelope, not application/problem+json. RFC 9457 problem details are used only on the REST/HTTP surface (lib/server/problem.ts:6; lib/server/processingConfigSchema.ts:141: "DEC-1 invalid_params on MCP, RFC 9457 details on HTTP"; CLAUDE.md DEC-1 / LIB-BUG-318).

Shape (as asserted by lib/mcp/__tests__/errorEnvelope.test.ts:327-328 and produced at lib/mcp/umbrellaErgonomics.ts:1027-1059):

{
  "ok": false,
  "tool": "dataset_lifecycle",
  "error": {
    "code": "confirm_required",
    "message": "…what happened, what was NOT changed, what to do…",
    "retryable": false,
    "issues": [{ "path": ["confirm"], "message": "…", "code": "invalid_literal" }],
    "expected": { "…": "describeExpected(schema, command)" },
    "received": { "…": "redacted echo of your args" },
    "details": { "also_known_as": "alias" },
    "fix": { "tool": "dataset_lifecycle", "command": "delete", "kind": "replayable", "args": { "…": "…" }, "why": "…" }
  }
}

Rules an agent can rely on:

Successful responses are { "ok": true, … } (paginated shape in §4).

4. Canonical parameters and pagination

Contract: docs/contracts/canonical-params.md (audited by npm run audit:param-canonicalization).

Paginated list envelope (canonical-params.md §2.3):

{ "ok": true, "data": { "items": [], "total_count": 1247, "has_more": true, "next_cursor": "opaque-or-null", "next_offset": 100 } }

total_count is required for offset pagination, best-effort for cursor pagination. Loop on has_more, feeding back next_cursor or next_offset — never compute the next page yourself. Note that older umbrellas (dataset_admin.settings_get {id}, dataset_snapshot.list {id}) still take id; the alias policy in §3 of the contract keeps both accepted through the v0.22.x cascade.

5. The 45 umbrellas, grouped by task

Every umbrella is called as <umbrella>({command: '<cmd>', ...args}) except _hello, health_check, workspace_info (no discriminator). Command lists are the manifest's commands[]; "most used" picks are the commands the umbrella description itself leads with. Full per-command parameter tables: docs/versions/v0.22.188/tools/<umbrella>.md, or live via ux.docs_get({topic:'<tool>.<command>'}).

5.1 Gateway and session

5.2 Discover and read datasets

5.3 Bring data in

5.4 Manage, transform, govern datasets

5.5 Master data and stewardship

5.6 Analytics, evidence, reporting

5.7 Platform, identity, engineering

6. Task recipes

Parameter names below are copied from the v0.22.188 per-tool tables; confirm:true marks irreversible steps (§4).

6.1 Catalogue a new database

1. connection({command:'create', …}) — store the credential once (write-only; test afterwards).
2. data_catalog({command:'provider_create', kind, name, connection_id, role, scan_cadence, sample_policy}) — register the provider over the connection.
3. data_catalog({command:'provider_test', provider_id}), then data_catalog({command:'crawler_create', provider_id, purpose, name, scope}).
4. data_catalog({command:'scan_run', crawler_project_id, acknowledge_sweep?, reason?}) — inspect failures with crawler_run.errors_list {run_id}.
5. Browse: assets_list {provider_id, kind, q} → asset_get {asset_id} → columns_list {asset_id} → profile_get {asset_id, sections}.
6. Optionally bind to master data: bind_inbound {asset_id, entity_type_id, field_map, role}.

Saved recipe: workflow.get {id:'W35'} ("map what exists in a connected database").

6.2 Find PII in an estate

• Catalogue-level: dataset_catalog({command:'search', has_pii:true, compliance_level?, semantic_type?}) and dataset_catalog({command:'catalog_stats'}) (PII/PHI counts, needs-classification counts).
• Field-level: dataset_catalog({command:'fields_search', field_query, semantic_type}).
• Connected systems: data_catalog.profile_get {asset_id} and the provider summary, which separates columns_with_format_label (shape detections) from columns_with_secret_label (credentials) and reports columns_with_stored_samples + sample_disclosure (tools/data_catalog.md). columns_search {provider_id, q} for name-based sweeps.
• Re-classify stale datasets: dataset_analysis.submit_batch {scope:'vocabulary_stale', dry_run:true} first, then real.
• Mask what you find: generalization.preview → generalization.apply (view-mode), or dataset_admin.masking_set {id, mode, confirm}. Masking is OFF by default and legally-required only (STANDARD-009).

Saved recipes: W14 (catalog-wide PII field inventory), W38 (apply compliance masking and verify).

6.3 Build a derivative dataset

• Join: dataset_admin({command:'join_create', sources, join_type, join_keys, output_name, qualify?, where_clause?, output_format?, visibility?, auto_analyze?}).
• Union: dataset_admin({command:'union_create', sources, output_name, dedup?, dedup_key?, survivorship?}).
• The derivative is born with strictest-of-parents governance (compliance_level/has_pii/has_phi) and masked parent columns stay masked (tools/dataset_admin.md). dataset_transform materialises nothing — it is a JSON utility (docs/audit writeup 05).
• File-level derivative pipelines: file_repo.derivative_create. Track the async job with job.get.

6.4 Search documents with RAG

1. rag({command:'corpus_create', name, description?, topic_id?, tags?, visibility?, hierarchical_split?}) → returns a corpus dataset_id.
2. rag({command:'corpus_add', dataset_id, files? | file_ids? | from_urls? | from_connection?}).
3. rag({command:'status', dataset_id}) until indexed; corpus_docs {dataset_id, cursor, limit} to list.
4. rag({command:'search', dataset_id, query, top_k?, max_chunks_per_doc?, filters?}).
5. Cross-store discovery without knowing the owner umbrella: search({command:'query', q}).

corpus_promote/corpus_demote flip personal↔internal visibility and carry a disclosure; corpus_doc_remove and reindex need confirm. Guide: ux.docs_get {topic:'rag_skill_pack'}.

6.5 File a bug

artifact({command:'bug_submit', title, description, severity, umbrella, sprint?, discovered_by?, reproducer?, affected_versions?, related_bugs?, metadata?}) → returns the LIB-BUG-n id (IDs come only from the writer; next_id {type:'BUG'} previews without consuming). Then bug_get {id}, bug_update {id, status, severity, metadata, body_append}, bug_list {umbrella, status, severity, limit, cursor}.

6.6 Check platform health

health_check({}) (quick: DB latency, migrations.applied/latest/pending/pending_files, worker heartbeat); workspace_info({}) for capacity; job.stats for queue state; admin: health_check {mode:'full'|'worker'}, mcp_log.stats. Saved recipe: W28 (health sweep with a saved report).

6.7 Run a saved REST endpoint through the vault

1. connection.create the credential (never readable back).
2. rest({command:'endpoint_create', name, url, method, headers?, body_template?, auth_type, auth_connection_id, variables?, catalog?}).
3. rest({command:'execute', endpoint_id, overrides?, auto_save?, dataset_id?}) — executed server-side; the response, not the secret, is returned. auto_save/dataset_id land it as a dataset (recipe W22).
4. rest({command:'responses_diff', execution_id_1, execution_id_2}) before trusting a changed response (recipe W25).

7. workflow recipes

87 executable recipes live as JSON in library/workflows/ (loaded by lib/mcp/workflowRegistry.ts:86-91, ids W01…), each validated against the live tool surface by audit:workflow-recipe-integrity. Use workflow.list {archetype?, domain?, complexity?, destructive?, accessible_only?} (tier-filtered via requiredTierFor, workflowRegistry.ts:180), workflow.get {id}, workflow.run {id, params, confirm} and workflow.save {id, definition}. ux.help {view:'patterns'} projects the top recipes per category from the same registry. Examples: W01 ingest-URL-and-analyze, W07 snapshot-before-destructive, W17 assess an unknown file end-to-end, W22 wire a REST API into a dataset, W35 map a connected database, W40 assemble a compliance-audit evidence pack.

8. The ux umbrella and the tester protocol

DEV-GOV-TESTING protocol for QA agents (docs/governance/DEV-GOV-TESTING.md §4):

• T-5 — Declare session_label = the run's identity and agent_info {model, provider, version, effort} on the FIRST call (health_check or _hello) and carry session_label on EVERY subsequent call (line 34). T-5a: one principal per role tier — do not mix keys in one run (line 36).
• T-6 — Self-report per BLOCK as structure inside ONE ux.run_report {narrative: {blocks: [{block, …}], final_summary}}; the verb is capped at 5 reports per session (RUN_REPORT_CONFIG.rowCaps.maxReportsPerSession, line 37-38).
• T-7 — File findings through artifact.bug_submit with the root cause as you read it; set severity via bug_update; never edit the prompt doc (line 41).
• The release test prompt itself is fetched with ux.docs_get {topic:'test_prompt', version:'vX.Y.Z'} (§3 of the standard).

9. Pacing and limits an agent should respect

• Daily call limits per tier (§2) with _meta.usage telemetry on success and an RFC 3339 reset_at on refusal (config/quota.config.ts).
• session_label aggregation window for cross-checks is PT24H (ISO 8601); a longer run should use a fresh label (session-tagging.config.ts labelAggregation).
• dataset_data.query is cost-guardrailed; force:true overrides (manifest description). data_catalog.crawler_create and crawler.project_create/project_update accept rate_limit_rps / max_requests_per_run so you declare the outbound crawl pace (rest.endpoint_create carries no such parameter — pace REST executions yourself).
• Destructive verbs do nothing without confirm:true; the refusal ships a fix you can replay (§3).
• Tool weights and token estimates per tool are declared in config/mcp-tiers.config.ts (TOOL_WEIGHTS 460-533, TOKEN_ESTIMATES from 538); TOOL_ENTRY_SIZE_BUDGET_BYTES = 100_000 (line 664) bounds each advertised tool entry.

10. Where to look next

Measured against the release named in the text. Raw Markdown: /ontology/documentation/agent-guide-mcp.md. This page is also served as raw Markdown at the same URL with a .md suffix, for agents and search tools that prefer plain text. Every capability statement cites the source file and line it was measured from.