Repository navigation
MCP: Publish connection and migration instructions #2643
Description
Give users a tested guide for connecting through OAuth and moving from older MCP connections. Explain which protocol revisions and exact client builds are supported, how to sign in and grant access, and how to recover from common failures. This is required for the launch in #2408.
Migration instructions should cover client upgrades, removal of old session assumptions and manually configured MCP tokens, and reconnecting through OAuth. Explain that ordinary Data API HTTP authentication is separate.
This ticket is done when the guide is published, reviewed, and tested against the release candidate. Use the client evidence from #2633 and link the operator runbook and support path supplied by #2634. Drafting can proceed while implementation is underway.
Status on November 3, 2026
PR #2669 adds OAuth guidance and a reusable issued-token smoke test. Final connection instructions still depend on the supported-client evidence in #2633 and the deployed runbook in #2634.
The November 3 discussion leaves token lifetime, unattended-authentication scope and the final credential-storage workflow unconfirmed. Document those against the agreed contract in #2654 and released client behavior.
Implementation requirements and source references
Tracking issue: #2408. Workstream: Launch. Launch required. Requirement ID: L5 product onboarding and migration.
Outcome
Publish a usable connection and migration guide for the OAuth-only MCP endpoint with 2026-07-28 as the minimum protocol revision. Support conforming clients without selecting a primary vendor.
Acceptance
- Publish the connection contract, supported protocol revisions, approved client registration modes and exact tested client builds from MCP: Test OAuth sign-in with supported clients #2633, including IBM Bob. Mark unverified clients explicitly.
- Explain endpoint discovery, sign-in, consent, organization/permission selection and reconnecting or renewing access. Never ask users to paste secrets into issues or logs.
- Publish migration steps: upgrade the client, remove initialize/session assumptions, stop configuring AstraCS/custom token headers for MCP and reconnect through OAuth. Explain that ordinary HTTP API authentication is a separate surface.
- Document actionable recovery for 401, 403, unsupported revisions and consent denial. Include an authorized read, an expected denial and recovery using the qualified client matrix.
- Distinguish the AstraCS credential held by the application or credential helper, a client-signed assertion if supported, and the access JWT sent to MCP. Confirm actual token lifetime, renewal and storage behavior against the released client. Do not present unreleased credential-helper workflows or headless modes as supported without versioned evidence.
- Link the operator runbook and support escalation path supplied by MCP: Verify the deployed service and prepare rollout #2634. Validate the guide against the release candidate and record the reviewer and document version.
Completion evidence
Link published user documentation and its review evidence. Keep private operational runbooks and environment details in the approved internal documentation system. This ticket owns documentation, not deployment or promotion approval. Drafting can proceed in parallel with implementation. Final client claims require #2633 evidence, and #2634 owns release promotion.
Related changelog requirements: M1/M2 removal of sessions and initialization, D2 retirement of old HTTP+SSE, G1 feature lifecycle. Exact source lines, D2, G1.
Activity
[-]MCP: Publish OAuth onboarding and migration guidance[/-][+]MCP: Publish connection and migration instructions[/+]