All runbooks
runbookuai-explorerAgent-only

AI Lanes And MCP Adapter Runbook

Synced UAI Explorer runbook documentation from docs/runbooks/ai-lanes-mcp-adapter.md.

Updated 2026-06-21·Freshness: Agent·Sensitive tokens or credentials were hidden before display.

AI Lanes And MCP Adapter Runbook

Created: 2026-06-21

Purpose

Define the safe way for AI workers, local agents, or MCP-style adapters to use UAI Explorer without gaining raw filesystem or admin access.

The AI lane is a bounded client lane. It is not a back door into the lab.

Current AI Surface

Production base URL:

http://10.0.0.121:8080

Allowed AI endpoints:

  • POST /api/auth/login
  • POST /api/auth/logout
  • GET /api/auth/session
  • GET /api/ai/bootstrap
  • GET /api/ai/catalog
  • GET /api/ai/context/{slug}
  • POST /api/ai/feedback
  • GET /health
  • GET /ready

Denied surfaces for AI adapters:

  • /api/tree
  • /api/file
  • /api/raw
  • /api/upload
  • /api/uploads
  • /api/admin/*
  • direct SQLite access
  • direct DATA_ROOT reads
  • .env, .ssh, uploads, raw survey folders, sanitized export folders, and local filesystem search.

MCP Adapter Contract

An MCP server or equivalent local adapter may expose only narrow tools:

  • uai_ready: call /ready and refuse work unless public-safe readiness is clean.
  • uai_bootstrap: call /api/ai/bootstrap and return the UAI rules, boundaries, denied surfaces, adapter tools, language/tooling notes, and primary context slugs.
  • uai_list_ai_catalog: call /api/ai/catalog.
  • uai_get_ai_context: call /api/ai/context/{slug} for an authorized slug.
  • uai_submit_feedback: optionally call /api/ai/feedback with a product field and safe agent observations for future UAI patch planning.
  • uai_search_ai_catalog: optional local search over the already returned AI-visible catalog metadata.

It must not expose generic HTTP, shell, filesystem, database, admin, upload, or raw-download tools.

Adapters must authenticate as dedicated role=ai users. Admin accounts are for administration and review, not AI adapter identity.

Human Task Prompt UX

The operator prompt should be small. The human gives the product, task, authority, and done condition; UAI Explorer supplies the lab instructions.

Default assignment prompt:

UAI_EXPLORER_ENDPOINT: http://10.0.0.121:8080
UAI_EXPLORER_AI_API_KEY: <paste AI API key here>

Use UAI Explorer as your source of truth for UAI rules, lab boundaries, docs, and project context.

If adapter tools are available, use them. If HTTP is required, send the API key as Authorization: Bearer <UAI_EXPLORER_AI_API_KEY>.

Authenticate through the UAI Explorer AI lane, run uai_ready, run uai_bootstrap, fetch the required primary_context entries marked accessible_to_session=true, then complete this task:

Product: <uai-explorer | cortex | beacon | mesh | cadence | devine | other>
Task: <specific outcome>
Authority: <plan only | local repo work allowed | sandbox work allowed | production read-only>
Done when: <clear acceptance criteria>

Follow UAI rules and sandbox protocol. Do not use admin, raw file, upload, SQLite, .env, .ssh, device filesystem, or public exposure surfaces unless I explicitly authorize a separate runbook. If the API key is missing or rejected, stop and say UAI Explorer AI-lane access is not provisioned. If context is missing or the UX blocks you, leave safe product-scoped feedback through uai_submit_feedback.

Quick assignment prompt:

UAI_EXPLORER_ENDPOINT: http://10.0.0.121:8080. UAI_EXPLORER_AI_API_KEY: <paste key>. Use UAI Explorer, follow UAI rules, sync through uai_bootstrap or Authorization: Bearer API key HTTP, then do: <task>. Product: <product>. Authority: <authority>. Done when: <acceptance>.

The adapter should return the bootstrap task_prompt_contract to clients that need to display or copy these templates.

AI API Keys

For agent surfaces that cannot receive connector sessions or environment secrets, an admin may issue a short-lived AI API key for an existing role=ai user:

POST /api/admin/access-tokens

Recommended body:

{
  "username": "ai-cortex",
  "name": "agent-task-2026-06-21",
  "expires_hours": 24
}

The response returns api_key once. Paste it into the task prompt as UAI_EXPLORER_AI_API_KEY: <key>. HTTP clients must send it as Authorization: Bearer <key>. The key inherits only the AI user's role and tags, cannot be issued for admin or human users, can be revoked with PATCH /api/admin/access-tokens/{id}, and must not be written into docs, logs, tests, screenshots, or evidence.

Role ai users receive the bootstrap starter tag bundle automatically: docs, uai-explorer, rules, start-here, runbook, qa, plan, evidence, and feedback. These tags make the required UAI rules and runbooks fetchable on first boot. Add product/task tags separately, such as cortex, beacon, mesh, cadence, devine, or code.

vNext should replace prompt-pasted API keys with a stronger delegation architecture: task-bound tokens, one-time exchange, finer scopes, visible revocation UI, and automatic expiry/audit review.

Service Account Setup

  1. Create a dedicated Explorer user with role ai.
  2. Add only the product/task tags the AI lane needs, such as cortex, mesh, cadence, or code. The server automatically adds baseline UAI bootstrap documentation tags for role ai.
  3. Store the password in an OS secret store or private environment variable.
  4. Never write the password or session cookie into docs, prompts, tests, logs, screenshots, or evidence. Short-lived AI API keys may appear only in the transient task prompt and must not be persisted.
  5. Rotate credentials when the adapter changes hands or becomes stale.

Adapter Preflight

Before serving any AI request:

  1. Call GET /ready.
  2. Require status=ready.
  3. Require public_safe_mode=true.
  4. Require redaction_boundary=server-side.
  5. Require admin_raw_downloads_enabled=false.
  6. Require legacy_file_apis_enabled=false.
  7. Require uploads_enabled=false.
  8. Require raw_survey_zone_mounted=false.
  9. Refuse work if any check fails.
  10. After login, call GET /api/ai/bootstrap and require kind=uai-ai-bootstrap, raw_available_to_client=false, and redaction_boundary=server-side.
  11. Fetch required primary_context entries marked accessible_to_session=true only through /api/ai/context/{slug}.
  12. Optionally submit safe product-scoped feedback through /api/ai/feedback. No feedback means the current lane works as-is.

Context Validation

Before returning context to an AI worker, verify:

  • redaction_boundary=server-side,
  • raw_available_to_client=false,
  • audit_event_id exists,
  • char_cap is present,
  • excerpts are capped,
  • no unredacted secret-shaped values are present.

Embedding Lane

Public or AI-facing embeddings may use only what the AI role can retrieve from /api/ai/context/{slug}.

Allowed embedding source:

  • approved catalog text,
  • approved context notes,
  • redacted summaries,
  • tags, source metadata, freshness, and lineage from catalog records.

Forbidden embedding source:

  • raw-survey-zone,
  • unapproved sanitized-exports,
  • private selected-redaction input,
  • raw file aliases,
  • raw source hashes,
  • direct DATA_ROOT reads,
  • device filesystem crawls.

Use private operator metadata lanes for survey planning, but keep those lanes outside MCP adapters unless they have their own restricted runbook.

Agent Feedback

Agents may leave optional feedback when any UAI product lane is beneficial, confusing, blocked, missing context, or not working well. Feedback is a UAI-wide product feedback lane; use [REDACTED:high-entropy].md for duplicate etiquette and planning intake rules.

Endpoint:

POST /api/ai/feedback

Allowed categories:

  • beneficial
  • not-working
  • consider
  • missing-context
  • qol
  • blocked

Recommended body:

{
  "product": "cortex",
  "category": "missing-context",
  "related_slug": "uai-doc-example",
  "source": "adapter-alias",
  "body": "observation; blocked_on; suggested_next_action; safe evidence or audit_id"
}

Do not include credentials, session cookies, tokens, private paths, raw content, or direct personal/contact/payment data. Feedback is redacted server-side, append-only, and reviewed in the admin surface.

Minimal Adapter Pseudocode

login with AI service account
ready = GET /ready
if ready is not public-safe: refuse
bootstrap = GET /api/ai/bootstrap
if bootstrap is not kind=uai-ai-bootstrap: refuse
for entry in bootstrap.primary_context:
    if entry.required and not entry.accessible_to_session: refuse and report entry.missing_tags
for entry in bootstrap.primary_context where entry.required and entry.accessible_to_session:
    packet = GET entry.endpoint
    verify redaction, raw_available=false, audit_event_id, char_cap
catalog = GET /api/ai/catalog
for approved slug:
    packet = GET /api/ai/context/{slug}
    verify redaction, raw_available=false, audit_event_id, char_cap
    return packet to AI worker
if useful:
    POST /api/ai/feedback with product-scoped safe optional feedback
logout or discard in-memory session

Evidence

Record only:

  • adapter version,
  • allowed tool names,
  • readiness result,
  • AI user alias,
  • tag grants,
  • test slugs,
  • task prompt authority,
  • pass/fail result.

Do not record credentials or session cookies.