docs: add User Sources overview + add User Source to gateway auth options

[wdawson]

Summary

• New /guides/user-sources/ section with a User Sources overview as the index page
• Adds User Source as a third option on the existing MCP Gateway authentication content (folds in GRO-92)
• Adds User Source / User Sources to the Arcade Vale vocabulary

Closes GRO-93 and GRO-92. Part of the GRO-75 umbrella — sibling per-provider guides and the consent-skip reference are still in flight.

What's on the User Sources overview page

1. Concept: Arcade users vs. end users, what a User Source is, why it's project-bound, 1:N to gateways.
2. When to use a User Source: three-row table comparing Arcade Auth, User Source (recommended for production), and Arcade Headers (fallback).
3. Register an OAuth client at your identity provider: documents the prod redirect URL https://cloud.arcade.dev/oauth2/intermediate_callback and what credentials you'll need to copy out.
4. Create a User Source: dashboard walkthrough — Name, Description, Issuer URL, Client ID, Client Secret, Subject Claim (default sub, no provider-specific alternatives at this level).
5. Use a User Source on an MCP Gateway: short — links to the Gateways doc for the actual auth picker.
6. Manage: edit, rotate client secret (with a warning about rotating at the IdP first), deactivate, and delete. Deactivation and deletion are both blocked entirely while any active gateway references the source.

What's on the gateway auth pages

• app/en/guides/mcp-gateways/page.mdx — Authentication table now lists three modes (Arcade Auth, User Source recommended, Arcade Headers fallback), with cross-links to the new User Sources overview.
• app/en/guides/mcp-gateways/create-via-dashboard/page.mdx — Authentication bullets now mirror the dashboard's actual two-level radio: "Members of this Project (Arcade Auth)" vs. "Non-Arcade Users → User Source (recommended) / Arcade Headers (fallback)."

Decisions worth flagging

• Terminology: "project-bound" instead of "project-scoped" — avoids overload with OAuth scope.
• Redirect URL: documented as the prod URL only, per Wils — no staging URL in prod docs.
• Org-bound binding: not documented. Data model supports it but there's no CRUD UI today.
• Feature flag: not mentioned. Written as if GA.
• Lifecycle guards: documented as enforced by the Dashboard (active-gateway check) for both deactivate and delete. The backend API has no guard today — frontend-only.
• No screenshots yet: text-only walkthrough; can wire up screenshots before the umbrella ships.
• Out-of-scope vale findings: pre-existing Google.Headings flags on mcp-gateways/page.mdx and a pre-existing <YOUR-GATEWAY-SLUG> MDX parser confusion on create-via-dashboard/page.mdx are not addressed in this PR.

Test plan

• vale clean on app/en/guides/user-sources/page.mdx
• check-meta-keys — all _meta.tsx keys valid
• pnpm build — /en/guides/user-sources renders; /en/guides/mcp-gateways and /en/guides/mcp-gateways/create-via-dashboard still build
• Reviewer to spot-check the concept overview tone
• Reviewer to confirm the redirect URL matches what should be public
• Reviewer to spot-check the gateway auth wording against the dashboard form copy

🤖 Generated with Claude Code

---

Note

Low Risk
Low risk: documentation-only changes that add a new guide and update existing auth-mode wording/links; no runtime or API behavior is modified.

Overview
Adds a new User Sources documentation section describing how to connect an OIDC identity provider to an Arcade MCP Gateway, including setup steps, redirect URL, configuration fields, and lifecycle operations (edit/rotate/deactivate/delete).

Updates MCP Gateway authentication docs to introduce User Source as the recommended production option alongside Arcade Auth and Arcade Headers, and aligns the dashboard-creation guide wording with the UI’s two-level chooser.

Refreshes related docs/indexing by adding a consistent “production end users” callout linking to User Sources across multiple MCP client guides, registering user-sources in guides metadata, and updating the glossary, llms.txt, and Vale vocabulary to include the new term.

^{Reviewed by Cursor Bugbot for commit e3c619f. Bugbot is set up for automated code reviews on this repo. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	May 22, 2026 10:49am

[github-actions]

Style Review

Found 4 style suggestion(s).

Powered by Vale + Claude

[vfanelle]

I'd hold on launching this page until User Sources is available to everyone in GA. And until all of the identity providers mentioned in the doc are actually supported.

The docs changes overall look good, with one nit.

Looking Good:

• I appreciate that you added references to User Sources from the MCP Gateways page.
• The name of the new User Sources page matching the section title is consistent with other Guides.
• I assume we'll add pages specific to each identity provider, so a dropdown menu makes sense.
• The terminology in the doc lines up with the User Sources page in the Dashboard on staging, which is good.

Nit:

• Can we add User Sources to the Glossary under Authentication and Billing, possibly next to Auth Provider? I think this will help with 2 things: 1) Users might get confused on the difference between an Auth Provider and a User Source. 2) Bc it's in the glossary, each time we say 'User Sources,' a user can easily hover to read the definition in-line without going to the glossary.

Noting a follow on task on the MCP Client docs, maybe @torresmateo can help: Each of our MCP Client pages show Arcade Auth and Arcade Headers. If you don’t want Headers and don’t want users on Arcade accounts, we can include a line saying to set up a User Source with links to the guide + glossary.

[vfanelle]

I commented in the thread already with the requested Glossary change

[wdawson]

Thanks Valerie!

Nit (addressed): Added User Source to the glossary under Authentication and Billing, right after Auth Provider. With it in the glossary, the auto-linker will pop the definition on hover wherever the term appears, on this page or anywhere else. Pushed in e95aa87.

Hold on launch: Agreed — this PR (and the rest of GRO-75's sub-issues) will land as a unit. Going forward, the sibling PRs (GRO-99 next) will target this branch rather than main, so they're independently reviewable but merge together. This PR stays open as the integration target until the umbrella is ready.

MCP Client docs follow-on: Filed GRO-152 under GRO-75 to cover the per-client auth-mode mentions. Suggested assignee Mateo; milestone is "Broader Validation, Telemetry & Docs".