mcp: real tools over the SDK — management, schema, ingest, jobs, annotation, releases (the Part III §4 list), confirm:true on destructive ops

[JArmandoAnaya]

Context

Agent-native from the first release (vision doc principle 8). The MCP server is the fourth
client of the kernel: a thin mapping of tools to SDK calls, stdio.

2026-07-28 roadmap audit: the original Part III §4 tool names (get_project_status,
ingest_source, partition_batch, get_ingest_progress, create_task_group, …) predate
the real surface and no longer match it. The authoritative candidate list is the union of
the four MCP parity lists recorded in PR #99 / #100 / #101 / #102 under the epic's
parity rule — 50 tools, named after the API operationIds. The current mcp/main.py stub
still carries the old names; this task replaces them wholesale.

Deliverables

• Decide, tool by tool, which of the 50 parity candidates ship as MCP tools and which
  fold or merge. The parity rule means evaluated, not implemented — 50 tools is a real
  agent-UX cost (tool-selection quality degrades with count), and mcp: validate the tool set against a real Claude Code workflow and adjust (open topic 7 from the vision doc) #36 validates whatever
  this task ships. The candidates, by the PR that recorded them:
  • feat(server): project and schema endpoints — the first protected routes, and the conventions (#27) #99 (projects / schemas): create_project, list_projects, get_project,
    rename_project, delete_project, create_schema_version, get_schema,
    list_schema_versions
  • feat(server): ingest endpoints — upload, launch, poll, and the pattern every long operation reuses (#28) #100 (sources / ingest): register_image_source, register_video_source,
    list_sources, get_source, start_ingest, get_ingest_job, list_ingest_jobs,
    resume_ingest
  • feat(server): batch and job endpoints — the contract a third-party client drives (#29) #101 (batches / jobs / annotations): list_batches, get_batch, approve_batch,
    start_batch, complete_batch, list_batch_jobs, list_batch_assets, get_job,
    get_job_progress, start_job, complete_job, next_pending_assets,
    set_asset_progress, list_asset_annotations, add_annotations,
    update_annotations, delete_annotations
  • feat(server): dataset, release and export endpoints — the cycle closes over HTTP (#30) #102 (datasets / releases / export / downloads): get_project_dataset,
    get_dataset, dataset_stats, list_dataset_assets, remove_dataset_asset,
    list_dataset_changes, promote_batch, publish_release, list_releases,
    get_release, get_release_manifest, verify_release, get_release_assignment,
    export_release, list_formats, get_asset, get_asset_image
• get_asset_image — the tool that makes an agent an annotator, not just an operator
  (2026-07-27 audit): returns the asset's pixels as MCP image content — thumbnail
  resolution by default (token cost), full resolution on request. Without it an agent can
  drive the whole workflow but never see what it is annotating, which guts the AI-first
  story; add_annotations + provenance='model' only matter if the model can look.
  IngestService.open_content / open_thumbnail (server: dataset/release/export endpoints + blob and thumbnail download by hash #30) are what it calls. Pair it with
  list_batch_assets / next_pending_assets so the agent can iterate a job.
• Schema-change preview: SchemaService.preview / compare already exist in the
  kernel and are deliberately unrouted (server: project and schema endpoints (CRUD + versioning) #27 — "no caller yet"). If this task wants
  "destructive changes return the plan, never applied in one step", MCP is their first
  caller. Otherwise create_schema_version's own refusals (DESTRUCTIVE_SCHEMA_CHANGE
  retryable with allow_destructive; SCHEMA_CHANGE_WOULD_ORPHAN deliberately not)
  already carry the explanation.
• Constraints already decided elsewhere, restated so this task does not re-open them:
  • No token-administration tools (docs/auth.md, server: real AuthProvider — persisted per-workspace tokens, create/revoke, bearer auth across the whole API #25): minting a credential is a
    privilege-escalation primitive, and an agent's "shown once" is a transcript.
  • MCP takes local paths, not multipart (server: ingest endpoints (create source, launch ingest, progress) with long-running handling #28): an agent on the same machine calls
    register_images directly; server/uploads.py must not grow an MCP caller.
  • export_release takes a local dest path, not a zip — ExportResult exists for
    exactly this caller, which never sees the bytes (server: dataset/release/export endpoints + blob and thumbnail download by hash #30). Export is synchronous (server: dataset/release/export endpoints + blob and thumbnail download by hash #30's
    stated limit; docs/releases.md).
  • Destructive ops require confirm: true and refuse with an explanatory message when
    false. The other two gate words (allow_destructive, allow_lossy) surface as their
    own parameters, never merged into one (kernel: SchemaService — monotonic immutable versioning, additive/destructive change classification, LabelClass/Attribute/allowed_geometries validation #6, server: dataset/release/export endpoints + blob and thumbnail download by hash #30).
• Tool descriptions written for agent consumption: what it does, when to use it, error
  modes.

Acceptance criteria

• Ship-vs-fold decision recorded per parity tool in the PR body
• Each shipped tool has a unit test through the MCP handler (not just the SDK)
• Destructive-op refusal path tested
• visionset mcp lists all tools over stdio
• An MCP client test retrieves an ingested asset's image content and its dimensions
  match the Asset row