From 47869aeefdd1793abadab7b4ed84b7ddea197288 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 22 Aug 2026 08:23:11 +0000 Subject: [PATCH] docs(readme): note the sign-in step the `claude mcp add` one-liner needs (#10319) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .changeset/readme-mcp-add-auth.md | 24 ++++++++++++++++++++++++ README.md | 7 +++++-- 2 files changed, 29 insertions(+), 2 deletions(-) create mode 100644 .changeset/readme-mcp-add-auth.md diff --git a/.changeset/readme-mcp-add-auth.md b/.changeset/readme-mcp-add-auth.md new file mode 100644 index 0000000000..1192d70370 --- /dev/null +++ b/.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. diff --git a/README.md b/README.md index 28ea14703d..06d6e41f6d 100644 --- a/README.md +++ b/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