Skip to main content

Configure MCP Server Authentication

The Setup tab on an MCP server edit page controls how Willow authenticates to the upstream MCP server on behalf of users. The right mode depends on what the server expects: organization-level OAuth tokens, per-user API keys, forwarded SSO credentials, or nothing at all. Choose it before syncing tools. Authentication errors during a tool test almost always trace back to a mismatched or missing auth configuration.

Prerequisites​

You need:

  • admin access to Willow
  • an MCP server already added to your organization

Go to Build > MCP Servers, click the server row to open its edit page, then select the Setup tab.

Authentication types​

TypeUse when
Proxy OAuthThe MCP server supports OAuth and each user should authorize access through Willow's proxied flow.
Proxy API KeyEach user provides their own API key, or you define setup keys users complete during connection.
Proxy PassthroughThe user's SSO provider JWT ID token should be sent to the MCP server as the Authorization header.
NoneThe upstream server requires no authentication. Use only for local or trusted test servers.

Do not choose None for production systems just to complete setup. Match the auth mode to how the server will actually be used.

MCP server Setup tab showing Proxy OAuth, Proxy API Key, Proxy Passthrough, and None authentication options

Configure Proxy OAuth​

  1. On the Setup tab, select Proxy OAuth.
  2. Select Discover OAuth Settings if Willow can auto-detect endpoints from the server.
  3. Enter Client ID and Client Secret (optional) from your OAuth application.
  4. Select Save Changes.

For servers that need manual endpoint configuration, expand Advanced settings and fill in:

  • Authorization Endpoint
  • Token Endpoint
  • Authorization Server Metadata (JSON)
  • Client Registration (JSON)
MCP server Setup tab with Proxy OAuth selected and Advanced settings expanded showing authorization and token endpoints

Configure Proxy API Key​

  1. On the Setup tab, select Proxy API Key.
  2. Optionally add How to find Keys (Markdown) instructions for end users.
  3. Turn on Enable Setup Keys if users should provide keys during connection.
  4. Add key rows with a display name and key identifier.
  5. In the MCP configuration on the Settings tab, reference the key using {{key}} where key is the identifier you set.
  6. Select Save Changes.
MCP server Setup tab with Proxy API Key selected showing setup keys and key identifier fields

You can also configure API key behavior at creation time for custom MCP servers. See Add an MCP Server.

Configure Proxy Passthrough​

Proxy Passthrough requires no server-side credentials. Instead, Willow takes the user's JWT ID token from your SSO provider and forwards it as the Authorization header on every upstream request. The MCP server receives the token directly and handles validation itself.

  1. On the Setup tab, select Proxy Passthrough.
  2. Select Save Changes.

This mode only works when users are authenticated through your configured SSO provider. Anyone without an active SSO session cannot make tool calls. See SSO Overview.

MCP server Setup tab with Proxy Passthrough selected

Using vault secrets​

Store sensitive values in the Vault and reference them in MCP configuration with:

{{vault.SECRET_NAME}}

On the Settings > MCP Configuration section, use Insert Secret to search vault secrets and insert the placeholder into the JSON editor. See MCP Server Settings Reference.

Test the connection​

After saving authentication settings:

  1. Use the run or test area on the Setup tab if the connector exposes one.
  2. Save your changes and open the Tools tab.
  3. Select Sync Tools, then test a low-risk tool.

A successful test confirms Willow can reach the upstream MCP server with the current credentials. If the test fails, check the auth mode, vault secret references, OAuth client details, and upstream server reachability before changing gateway or client settings.

On this page