docs(ai): connect-mcp — record what a first real connection actually hits

[baozhoutao]

Summary

Walked content/docs/ai/connect-mcp.mdx against a live app (Claude Code 2.1 + @objectstack/mcp 17.2, HotCRM sample data) and wrote down the four places a first attempt stalls that the page did not cover. Docs-only; publishes nothing.

What changed (one page)

• OAuth track — after claude mcp add, claude mcp list / claude mcp get report ✘ Failed to connect until /mcp → Authenticate is completed in a new session. The health probe is answered 401; the setup is not broken. A session already running when the server was added never picks it up.
• API-key track — where the key is minted (Setup → Connect an Agent, its console route, the Create key button at the bottom, shown once with a ready x-api-key: line, revoked under Setup → API keys); that a keyed registration shows ✔ Connected with no login step; that claude mcp add is local scope by default and -s user makes it global.
• Verify — an anonymous curl that must return 401, then a keyed walk through initialize → tools/list → tools/call query_records, with the two gotchas that cost a retry: the argument is objectName, and its value is the API name from list_objects (crm_opportunity, not opportunity → Object 'opportunity' not found).
• Troubleshooting — four rows for the symptoms above (pre-auth Failed to connect, ConnectionRefused when the app is down, server missing from a running session / wrong scope, wrong object name).

Verification

• check-docs-single-h1, check-docs-redirects, check-docs-image-tag all pass.
• Every /docs/... link on the page resolves to an existing page.
• The curl transcripts in the Verify section are the actual responses from the live run (11 tools listed, query_records on crm_opportunity returning total: 23).

🤖 Generated with Claude Code