feat(mcp-v2,docs,api): MCP server instructions and destructive/read-only tool annotations

Merged
SA
4mo ago
+144-7

Summary

  • Add instructions to both MCP servers' initialize responses and behavioral annotations to every tool: readOnlyHint on the 12 list/get tools, destructiveHint on the 3 deletes, idempotentHint on updates/pause/resume, destructiveHint: false on creates/dispatch.
  • This is the genuinely useful slice of the latest orank rescan: it graded our new docs MCP server and flagged missing instructions/annotations — the same gaps existed invisibly in the product mcp-v2 server, where they matter for real agent safety (an agent can now decline workspaces_delete without user confirmation instead of guessing).

Why / Context

Follow-up to #5910/#5912. The rescan (77/100) surfaced three real MCP-quality items alongside a pile of REST-isms we're deliberately not chasing. Per the MCP spec, an unannotated tool defaults to "assume destructive" — annotating makes the safe majority of our catalog explicitly safe and the dangerous minority explicitly dangerous.

How It Works

  • defineTool (mcp-v2) gains an annotations pass-through; each of the 27 tool definitions declares its hints inline.
  • createMcpServer sets instructions (host-scoped ID guidance + destructive-tool warning) in the initialize response.
  • Docs MCP server gets instructions + readOnlyHint on both tools.
  • The live-introspected server card now carries annotations per tool.
  • Also: /.well-known/mcp.json manifest alias (marketing + api), typed response schemas for the 4 discovery operations in openapi.json, and a factual versioning/deprecation paragraph (v1 MCP stays served during migration; changes announced in changelog).

Manual QA Checklist

  • tools/list on mcp-v2 (via server card introspection): all 27 tools annotated, deletes carry destructiveHint, lists carry readOnlyHint, none unannotated
  • Docs MCP initialize returns instructions; both tools readOnlyHint: true
  • /.well-known/mcp.json serves on the api app (marketing route is an identical re-export)
  • Invalid tool call / bad args verified to return structured -32602 errors (SDK behavior, unchanged)

Testing

  • bun run typecheck (mcp-v2, api, docs, marketing)
  • bun run lint (exits 0)

Known Limitations

  • The scanner's "MCP error handling" warning wants raw JSON-RPC errors where the MCP SDK intentionally returns isError tool results with the code in the message — not ours to patch.

Summary by cubic

Adds MCP server instructions and explicit tool annotations to mcp-v2 and the docs server so agents can safely distinguish read-only, idempotent, and destructive calls. Also surfaces annotations in the server card, adds a /.well-known/mcp.json manifest alias, and types discovery endpoints in openapi.json with versioning notes.

  • New Features
    • mcp-v2: initialize now returns instructions (host-scoped ID guidance + destructive-tool warning). All 27 tools annotated: readOnlyHint on list/get, destructiveHint on deletes (and destructiveHint: false on creates/dispatch), idempotentHint on updates/pause/resume.
    • Docs MCP: added instructions; both tools set readOnlyHint: true.
    • Server card now includes per-tool annotations; new /.well-known/mcp.json alias on api and marketing for manifest probes.
    • openapi.json: adds typed response schemas for resource metadata, authorization server metadata, MCP server card, and the OpenAPI document; documents path-based versioning (v2) and deprecation policy (v1 MCP remains available during migration).

Summary by CodeRabbit

  • New Features

    • MCP tools now expose clear read-only, destructive, and idempotent operation indicators.
    • MCP server guidance now explains supported behavior, tool usage, and safety considerations.
    • MCP discovery endpoints are available through standardized metadata routes.

  • Documentation

    • API documentation now provides more precise schemas for discovery and server-card responses.
    • Versioning and migration guidance has been added to the API documentation.

  • Improvements

    • Server cards now include tool annotations for richer client experiences.