docs(api): document Messages count_tokens and forwarded Anthropic headers

[slin1237]

SMG now serves POST /v1/messages/count_tokens (smg-project/smg#2638), and it forwards the anthropic-version and anthropic-beta headers to engines. Claude Code and the Anthropic SDKs depend on both. Messages also routes through HTTP PD dual dispatch (#2250).

The existing page was thin and partly wrong:

• It said tool use works "via MCP integration". Custom tools work on every path.
• It left out HTTP workers and HTTP PD.
• It showed only an x-api-key example, but the gateway's own auth never reads that header.
• It listed no streaming events.

Changes

reference/api/messages.md is rewritten for v1.11:

• Endpoints and backend support: an endpoints table, plus a matrix of what /v1/messages and count_tokens do on gRPC, ZMQ, HTTP, HTTP PD, and the Anthropic backend, and under IGW.
• Authentication: the client→SMG, SMG→worker, and SMG→Anthropic hops, x-api-key handling, and the CORS header list.
• Request body: the full field table with validation rules and the accepted content blocks.
• Examples: self-hosted and Anthropic tabs, a response example, and tool use.
• Streaming: the event list, with an exact SSE example from the gRPC path.
• Count Tokens: request, response, and per-backend behavior. The gRPC and Anthropic backends return 501, and requests with no router return 404 NO_ROUTER (#2659).
• Request Headers:
  • X-SMG-MCP: enabled turns on the SMG-run MCP tool loop on the Anthropic backend.
  • The two Anthropic headers are forwarded.
  • The full forward allowlist is listed.
• gRPC and ZMQ translation: tool handling, tool_choice, thinking, per-engine sampling fields, toolu_ tool IDs (#2111), integer cache-token counters (#2269), and 400 context_length_exceeded (#2618).
• MCP tools: the SMG-run loop versus passthrough, with a link to the MCP concept page.
• Errors: the real error shapes.

Verification

• Checked against smg v1.11.0 (3be823a7): crates/protocols/src/messages.rs, routers/{http/router,http/pd_router,gateway,mod}.rs, crates/external_router/src/{header_utils,anthropic/*}.rs, the gRPC messages pipeline, middleware/auth.rs, and server.rs.
• pnpm lint, pnpm check (0 errors), and pnpm build pass.
• The link check reports only three pages that sibling PRs add: zmq-workers.md (docs: add a guide for direct ZMQ engine connections #45), multimodal.md (docs: add a multimodal pipeline concept page #44), and request-streaming.md (docs: document request body streaming and upstream HTTP/2 #47).
• The page renders with status 200 under wrangler pages dev.

This is one of a series of docs PRs that bring the site up to smg v1.11.0, one per area.

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

Next included review available in 23 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 4 included reviews currently available. Your 65 included PR review attempts over the past 7 days set your current allowance at 4 reviews per hour.

Your organization has reached its usage spending cap. Adjust your spending cap in the billing tab.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Team

Run ID: 5fc2e35c-71a3-467a-968a-06d5c2602bcc

📥 Commits

Reviewing files that changed from the base of the PR and between 7362b40 and 0ea0ff4.

📒 Files selected for processing (1)

• src/lib/content/reference/api/messages.md

---

_{Comment @coderabbitai help to get the list of available commands.}