Upstream Authentication
Two separate questions get conflated in MCP setups. How does the client authenticate to the gateway? (Your Waxell OAuth session or an API key — covered in the Quickstart.) How does the gateway authenticate to each upstream? That's this page, and it's per-upstream — the auth_mode on the upstream row.
MCP OAuth (mcp_oauth_dcr) — the zero-credential default
Most modern vendor MCP servers (Notion, Linear, Calendly, Stripe, Monday, 100+ in the catalog) implement the MCP authorization spec. For these, nobody ever touches a vendor developer console:
- Discovery — the gateway asks the server itself how to authenticate: the server's 401 response points at its protected-resource metadata (RFC 9728), which names its authorization server, whose metadata (RFC 8414) provides the authorize, token, and registration endpoints.
- Dynamic client registration — the gateway registers itself as an OAuth client programmatically (RFC 7591), preferring a public client secured by PKCE. Happens once per tenant, on the first connect.
- Per-user authorization — each user does a standard consent dance (authorization code + PKCE, with the token bound to the specific MCP server via RFC 8707
resource). - Silent refresh — tokens refresh automatically for the life of the grant, including providers that rotate refresh tokens.
Discovery results and the registered client are cached on your tenant's upstream row; everyone after the first user goes straight to the consent screen. This is what the Auto OAuth badge means in the catalog, and it works for any spec-compliant server you add as a custom upstream.
A few servers speak MCP OAuth but don't offer dynamic registration (DocuSign, PagerDuty, Smartsheet, the Google Cloud services). Same mode, one extra step: an admin registers an OAuth app with the vendor once and stores the client credentials on the upstream — the discovery and per-user flows are unchanged.
Open (no_auth)
Some servers are simply public — Microsoft Learn, PubMed, AWS Marketplace, Open Targets. The gateway sends no Authorization header at all to these (forwarding a stray token to a third party would leak it). Why route an open server through the gateway? Because the caller still authenticates to Waxell, and policy, rate limits, and audit still apply. Open upstream ≠ ungoverned upstream.
Classic per-user OAuth (oauth_per_user)
The traditional flow for providers without MCP-spec auth: an admin registers an OAuth app with the vendor (or uses Waxell's platform-registered app where available), pastes the client ID and secret on the catalog entry or upstream row, and users connect individually. Per-provider protocol quirks (token endpoint auth style, body encoding, scope separators, PKCE) are handled by a built-in dialect engine that discovers, learns, and remembers each provider's dialect.
The rest of the modes
| Mode | What it does | Use when |
|---|---|---|
tenant_api_key | One tenant-wide key, resolved from the Waxell secret store at call time — the key itself never sits on the gateway | Vendor offers API keys, per-user identity not needed |
shared_service_account / byo_token_env | A token the gateway holds (secret store or environment variable) | Internal servers, legacy setups |
forward_caller_token | Passes the caller's own Waxell bearer through | Upstream shares Waxell's auth (e.g. Waxell's own MCPs) |
Credential precedence
When multiple credentials could apply, the gateway resolves: tenant's own (BYO) credentials → Waxell platform credentials → environment fallback. Per-user grants are always stored encrypted at rest and scoped to (user, upstream) — revocable individually from the Connections page.
Agent identity: delegations and vaults
When an agent calls through the gateway, two questions are answered on every call, on every auth mode:
- May this agent act here, and as whom? — the delegation. Under Identity → Delegations (or on the agent's own page) an admin decides, per app, whether the agent acts as itself, as a person (per-member toggles; the person must have connected the app), or as a service account. Rules under Identity → Rules grant whole groups by tag; an explicit row always wins, and a revoked row is a kill switch. A pair with nothing at all is left unmanaged.
- Where does that identity's credential come from? — the vault. Under Identity → Vault backends each app names a backend. Native is the default and reads Waxell's own stores: the person's OAuth connection, the agent's per-agent secret for as itself, or the workspace secret for a service account, all under one key per app (
auth_secret_ref, otherwiseMCP_<SLUG>_TOKEN) managed under Settings → Secrets. Federated backends (AWS AgentCore, Auth0 Token Vault, Descope, AWS Secrets Manager) are asked at call time; the page shows which backends are configured and which identities each can serve.
The Vault backends page and the agent page both report presence — "workspace key set", "needs MCP_LINEAR_TOKEN" — never a value. A call whose delegation resolves to an identity with no stored credential answers no_grant naming the key to add, and a denied delegation answers delegation_denied with the reason; both are recorded on the call's trace and audit row with the delegation that decided them.