MCP Server Authentication
Configure how Scrydon authenticates to a remote MCP server — static headers, API key / Bearer token, or OAuth 2.1 (client credentials and delegated user flows).
When you register a remote (Streamable HTTP) MCP server in Org Settings → MCP, you choose how Scrydon authenticates to it. Modes are configured per server on the registry entry.
Server URL requirements
By default a remote MCP server URL must be https:// and resolve to a public address. Scrydon rejects http://, localhost, and private/reserved IP ranges at both save time and connect time to prevent a registered server from becoming a server-side request forgery (SSRF) path into internal infrastructure.
Self-hosted / local servers (http:// and private IPs)
If you run an MCP server on your own network without TLS — for example http://localhost:3000/mcp or http://192.168.1.20/mcp — enable Allow private networks in the organization's egress governance policy (Platform Settings → Governance → Egress). This is the same control that governs whether locally-hosted AI runners (Ollama, LM Studio, vLLM) may be reached. When it is on:
http://URLs and loopback / RFC1918 (10.x, 172.16–31.x, 192.168.x) / IPv6 ULA targets are permitted for MCP servers.- Cloud-metadata endpoints (e.g.
169.254.169.254,metadata.google.internal) and internal-service ports (databases, Redis, SSH, …) stay blocked regardless.
When Allow private networks is off (or no egress policy has been saved), MCP traffic stays HTTPS and public-only — the setting is fail-closed, so it must be explicitly enabled and saved. The change applies to save time (registering/approving a server), the Test Connection probe, and the live connection alike.
Plain HTTP has no transport encryption — any bearer token or header you configure travels in clear text — so use it only inside a trusted network.
Auth modes
| Mode | When to use |
|---|---|
| Enterprise-managed (OAuth 2.1 / ID-JAG) | Recommended for enterprises. Your organization's identity provider (e.g. Okta) governs which employees may access the server — centrally, with one policy and one audit trail. No per-server or per-user authorization prompts. See Enterprise-managed authorization below. |
| None / static header | The server is open, or accepts a long-lived token you paste into a header. Headers are configured per workspace when the server is installed. This is the default and preserves the original behavior. |
| API key / Bearer token | The server authenticates with a static token or API key sent in a header — e.g. Authorization: Bearer <token>. Scrydon reads the token from a workspace secret at connect time. See API key / Bearer token below. |
| OAuth — client credentials | Service-to-service access for OAuth-protected servers that don't (yet) support enterprise-managed auth. Scrydon acquires and refreshes an access token automatically using the OAuth 2.1 client-credentials grant. |
| OAuth — user (delegated) | Per-user access where the connection should run as the end user. Requires connecting from the workspace before tools can run. |
Enterprise-managed authorization (recommended)
Enterprise-Managed Authorization (the MCP io.modelcontextprotocol/enterprise-managed-authorization extension) lets your identity provider decide who can use each MCP server — the same way it already governs email and other corporate apps. Employees sign in once with corporate SSO; access is granted or denied by IdP policy, with no per-server consent screens. Onboarding and offboarding happen in one place.
How it works. When a signed-in user invokes the server, Scrydon exchanges that user's IdP identity for a short-lived ID-JAG (identity assertion) at your IdP, then redeems it for an MCP access token at the server's authorization server. If the user isn't authorized, the IdP refuses and Scrydon never receives a token.
Configure (Org Settings → MCP → Add/Edit server → Authentication → Enterprise-managed):
| Field | Description |
|---|---|
| Resource (RFC 8707) | The MCP server's resource identifier — the audience your IdP stamps into the ID-JAG. |
| MCP authorization-server token URL | Where Scrydon redeems the ID-JAG for an access token. |
| Scopes | Optional scopes to request on the issued token. |
Prerequisites (one-time, by your IdP admin):
- Your organization is connected to Scrydon via enterprise SSO (Org Settings → SSO).
- Your IdP must support identity-assertion grants (Okta at launch). Your IdP admin registers Scrydon as an application permitted to request assertions for this MCP server and assigns the users/groups who may access it.
Scope note. Enterprise-managed auth applies to user-initiated runs (where Scrydon holds the caller's IdP identity). Fully automated / background runs have no user identity to delegate; use a fallback mode for those servers.
OAuth — client credentials
Fill in the OAuth fields on the server form:
| Field | Description |
|---|---|
| Token URL | The OAuth token endpoint, e.g. https://auth.example.com/oauth/token. |
| Client ID | The OAuth client identifier issued by the server's authorization server. |
| Client Secret (workspace secret name) | The name of a workspace secret that holds the client secret. Scrydon stores the reference, never the secret value, on the server definition. |
| Scopes | Space- or comma-separated scopes to request (optional). |
| Resource | RFC 8707 resource indicator (optional). |
| Audience | Token audience (optional). |
| Client authentication | Whether to send the client secret in the request body (client_secret_post, the default) or as HTTP Basic (client_secret_basic). |
Scrydon acquires a token on first use, caches it for its lifetime, and re-acquires automatically a minute before it expires. Use Test Connection to validate the configuration before saving — a missing secret or a rejected token request is reported as an error.
Storing the client secret
- Add the client secret as a workspace secret (Org Settings → Secrets) — e.g.
MCP_CLIENT_SECRET. - Put that secret's name in the Client Secret (workspace secret name) field.
The secret value never leaves the secret store and is never written onto the MCP server record.
OAuth — user (delegated)
Delegated OAuth runs the connection as the signed-in user via the OAuth 2.1 authorization-code flow. Configure the Authorization URL and Token URL (plus client id / secret reference / scopes), then Connect the server — Scrydon redirects you to the provider to sign in, stores your token, and refreshes it automatically. Until the connect step is completed, tools that need the server report that a connection is required.
The client secret is resolved by reference from the organization secret store — add it as an org secret (Org Settings → Secrets) and put its name in the Client Secret (workspace secret name) field, the same as for client-credentials.
Delegated access is strictly per-user:
- Tool calls run with the calling user's own token — one user's connection is never used for another user.
- Background / triggered runs have no user identity to act as, so they fail with a clear error; use client-credentials for servers that must run unattended.
- If the upstream provider revokes access (token refresh fails), the connection is marked as needing re-authorization and tool calls ask the user to reconnect the server from MCP settings.
API key / Bearer token
Many MCP servers authenticate with a single long-lived API key sent in a header — for example Twenty expects Authorization: Bearer <YOUR_API_KEY>. Choose API key / Bearer token on the server form and fill in:
| Field | Meaning |
|---|---|
| Token secret (workspace secret name) | The name of a workspace secret holding the token / API key. Add the value under Org Settings → Secrets; only the name is stored on the server record — the value is resolved at connect time and never persisted on the registry entry. |
| Header name (optional) | The header the token is sent in. Defaults to Authorization. |
| Scheme prefix (optional) | The prefix before the token. Defaults to Bearer (sent as Bearer <token>). Set it to a different scheme, or leave it empty to send a raw value (e.g. X-API-Key: <token>). |
At connect time Scrydon resolves the named secret and sends <header>: <scheme> <token>. If the secret is missing the header is omitted and the server responds 401, surfaced as a connection error. No OAuth handshake occurs.
Pack authors can ship a server pre-configured for this mode by declaring auth: { kind: "bearer", tokenRef: "..." } on the MCP server manifest — the token is a secret reference, never embedded in the bundle.
Notes
- OAuth modes apply to Streamable HTTP servers. STDIO servers continue to use environment-variable credentials.
- Existing servers with no auth configured keep working exactly as before (static-header mode).