Skip to main content

Build an MCP Server Behind Willow

You can run your own MCP server and have Willow proxy calls to it. Willow handles the caller's authentication at the gateway, then forwards a credential to your server based on the server's configured auth mode. This page covers what your server receives and how to validate it.

Speak MCP over HTTP​

Your server must handle MCP requests over HTTP. At minimum it responds to:

  • initialize with a result containing protocolVersion, capabilities, and serverInfo
  • tools/list with the tools you expose
  • tools/call to run a tool and return its content

Willow discovers your tools by calling initialize and tools/list when the server is added, then proxies tools/call at runtime. These are the same JSON-RPC request and response shapes documented in Programmatic Gateway Access; the Express tutorials below show a complete handler. Willow accepts a plain JSON response for each request.

What Willow forwards, per auth mode​

The Authorization header your server receives is determined by the auth mode on the server's Setup tab. See the authentication types reference for the full matrix; in summary:

Auth modeWhat your server receives
NoneNo Authorization header
Proxy PassthroughThe caller's SSO token (human user) or a client-credentials token minted from the machine user's credentials (machine user)
Proxy Client CredentialsA client-credentials token that Willow mints from the server's configured client, for every caller
Proxy API KeyThe key the end user supplied. By default it arrives as the raw Authorization header value with no Bearer prefix; it also lands in any custom header where your MCP configuration references {{apiKey}} (or {{<identifier>}} for named setup keys)
Proxy OAuthAn OAuth access token that your server's OAuth flow issued to the user, forwarded as Authorization: Bearer <token>

For Proxy Passthrough and Proxy Client Credentials, the forwarded token is a JWT issued by your identity provider (Okta or Keycloak), not by Willow. For Proxy OAuth, the token is one your own server issued, so you validate it against your own OAuth server.

Validate the forwarded token​

When you use Proxy Passthrough or Proxy Client Credentials, validate the JWT the same way you would any OAuth access token:

  1. Read the Authorization: Bearer <token> header.
  2. Fetch your identity provider's JWKS (for Okta, https://{domain}/oauth2/default/v1/keys; for Keycloak, https://{host}/realms/{realm}/protocol/openid-connect/certs).
  3. Verify the token signature, iss, aud, and exp.
  4. Authorize the request using the token's claims. A machine-user token carries the cid of the configured client and the scopes you granted (for example api.access).

Never trust the header without verifying the signature against the provider's keys.

Testing reachability​

Willow's gateway calls your server from its backend, so the server URL must be reachable from the public internet over HTTPS. If Willow reports a connection error when you add the server, confirm the host resolves publicly and that any firewall in front of it allows the connection.

For Proxy OAuth, your server issues the token itself. See Build an OAuth-Protected MCP Server for Willow for the endpoints to implement. For Proxy API Key, see Accept Per-User API Keys from Willow.

On this page