ZZD public AI gateway · zzd_public_ai_gateway_v3
Resource: 13 · Agent capability contract / REST 与 MCP 边界
Canonical map: https://zzd.show/docs/ai/map.json
Full handbook: https://zzd.show/llms-full.txt
REST capabilities: https://zzd.show/api/v1/capabilities/

# ZZD external-agent capability contract

Capability maturity must remain explicit.

## Available now

- this public, unauthenticated documentation/resource graph and REST
  adoption specification;
- public machine-readable REST discovery at
  `GET /api/v1/capabilities/`;
- authenticated HTTPS REST v1 draft, Piece, asset, bounded BaaS,
  collection, verified-thumbnail, and publication operations using
  a scoped, expiring ZZD developer bearer credential;
- authenticated stateless Streamable HTTP MCP at `POST /mcp/v1/`
  with bounded tools that reuse the REST control plane;
- signed-in browser use of the normal Web AI IDE and product UI;
- Show runtime APIs such as `AppRuntime` and `SpaceClient` inside an
  appropriately bound Show.

Public documentation and capabilities need no credential. Every
private REST resource operation enforces bearer authentication,
scope, active owner, and ownership. REST never falls back to a
browser session cookie or legacy CLI token. Both the developer API
and signed-in credential control plane accept only the exact
canonical `zzd.show` Host.

## MCP transport boundary

There is no public unauthenticated mutation endpoint. `/mcp/` is the
human-readable discovery page; `/mcp/v1/` is the authenticated,
stateless Streamable HTTP protocol endpoint with a bounded `zzd_*`
tool catalog. Its mutating tools reuse REST v1 ownership, scope,
validation, quota and publication checks rather than opening a
second privileged path. Client/domain approval remains controlled by
Codex, Claude Code, the browser, proxy or organization.

## Stable resource names for MCP-compatible ingestion

- `zzd://docs/platform`
- `zzd://docs/quickstart`
- `zzd://docs/deployment-api`
- `zzd://docs/show-contract`
- `zzd://docs/quality`
- `zzd://docs/assets`
- `zzd://docs/baas`
- `zzd://docs/lifecycle`
- `zzd://docs/distribution`
- `zzd://docs/safety`
- `zzd://docs/handoff`

## REST boundary

REST v1 intentionally exposes a bounded subset of ZZD. It supports
owned Show listing/creation/detail/update, authoritative Piece-tree
replacement, safe byte assets, one isolated runtime-identity BaaS
profile, owned collection creation/attachment, and confirmed
publish/unpublish. It also supports verified thumbnail replacement
and owner-scoped private thumbnail streaming. It does not expose
arbitrary BaaS, generic upload-from-URL, browser validation, favicon
mutation, Sale management, destructive deletion, asset replacement/
deletion, thumbnail deletion, collection detach/deletion, shell,
SQL, staff tools, internal lifecycle orchestration, or another
user's resources.

The capability response reports exact methods, routes, scopes,
examples, limits, idempotency behavior, source policy, and response
envelopes. Unknown fields and server-controlled fields are rejected.
Source and presentation mutations clear compiled state where
applicable and return the Show to a private/hidden draft. Draft
developer bytes remain private; publication promotes public copies,
and re-drafting removes those public copies while retaining private
sources. Publication is separate, scoped, confirmed, and preflighted.
These properties are security contracts, not hints.