docs(readme): note the sign-in step the claude mcp add one-liner needs (#10319) (#11019)

The "Your app is AI-operable, for free" section's copy-paste command —
`claude mcp add --transport http my-app http://localhost:3000/api/v1/mcp` —
registers the MCP server correctly, but the next natural step (an agent
actually calling a tool) 401s until the caller signs in. Measured live, at
head, against a freshly booted `examples/app-crm`: unauthenticated
`initialize` returns `401 {"code":"UNAUTHENTICATED","message":"Unauthorized:
a valid OAuth access token or API key is required"}`, matching the finding
this closes. The README gave no hint that a sign-in step follows the
command.

The linked docs page, content/docs/ai/connect-mcp.mdx ("Connect an MCP
Client"), already carries the step in full — interactive OAuth browser
login for the exact same command, plus a headless API-key flow for
CI/containers — so the fix is a one-sentence pointer here, not a rewrite of
a page that already correctly carries the weight this README delegates to.

Fixes #10319

Claude-Session: https://claude.ai/code/session_019bmVFqoQPq63zhKrxdYG1r

Co-authored-by: Claude <noreply@anthropic.com>

Author: Elon Musk

.changeset/readme-mcp-add-auth.md

@@ -0,0 +1,24 @@
+---
+"@objectstack/spec": patch
+---
+
+docs: note that the root README's `claude mcp add` one-liner needs a follow-up sign-in step (#10319)
+
+The "Your app is AI-operable, for free" section's copy-paste command
+(`claude mcp add --transport http my-app http://localhost:3000/api/v1/mcp`)
+registers the server correctly, but running it alone and then calling a tool
+401s — measured live, at head, against a freshly booted `examples/app-crm`:
+unauthenticated `initialize` returns
+`401 {"code":"UNAUTHENTICATED","message":"Unauthorized: a valid OAuth access
+token or API key is required"}`, exactly as the finding this closes reported.
+The README gave no hint that a sign-in step follows the command.
+
+The linked docs page, [Connect an MCP
+Client](https://objectstack.ai/docs/ai/connect-mcp), already carries the step
+in full (interactive OAuth browser login, plus a headless API-key flow for
+CI/containers) — confirmed by reading it and by reproducing both paths live:
+the same unauthenticated call 401s with a `WWW-Authenticate` header
+advertising OAuth metadata, and minting a key via `POST /api/v1/keys` with a
+session cookie and sending it back as `x-api-key` returns `200` with a valid
+`initialize` response. So the fix is a one-sentence pointer in the README, not
+a rewrite of the docs page it already correctly delegates to.

README.md

@@ -172,8 +172,11 @@ as a human:
 claude mcp add --transport http my-app http://localhost:3000/api/v1/mcp
 ```
 
-Objects are exposed automatically; actions opt in with `ai: { exposed: true }`.
-See [Connect an MCP Client](https://objectstack.ai/docs/ai/connect-mcp).
+The first tool call opens a browser to sign you in — each deployment is its own
+OAuth server, so there's no token to copy-paste. Headless setups (CI,
+containers) use an API key instead. Objects are exposed automatically; actions
+opt in with `ai: { exposed: true }`. See
+[Connect an MCP Client](https://objectstack.ai/docs/ai/connect-mcp) for both flows.
 
 ## This repo