MCP gateway security
Require authentication on every gateway with API keys, Basic Auth or bearer tokens.
Every MCP gateway requires authentication - a gateway cannot be left open. An AI agent presents a credential with each request, the credential resolves to a security definition, and that definition is the agent's identity everywhere else: in sessions, in the audit log and in rate limiting.
Credential types
| Type | How the agent sends it |
|---|---|
| API key | The X-API-Key header - the header name can be redefined through an environment variable |
| Basic Auth | The standard Authorization header, e.g. curl -u user:password |
| Bearer token | Authorization: Bearer <token> - a static token or a JWT verified against a JWKS endpoint, with audience and claim filters |
| OAuth | Authorization: Bearer <token> too, with the token obtained by the person signing in through your identity provider from inside their AI client - the gateway's OAuth field on, and a bearer token definition with an issuer and an audience in its group |
Assign definitions to a gateway
The Security picker on the wizard's step 01, How do agents connect?, lists the available API key and Basic Auth definitions. Each gateway has a security group named mcp.<gateway-name> and the picker manages that group's members - the same group is visible under Security > Groups, which is also where bearer token definitions are added to a gateway.
A request is accepted when any member of the group matches the presented credentials. Membership changes are live - adding or removing a member is reflected in enforcement immediately, without restarts.
When a JWT matches a claim-filtered bearer definition, the resolved identity is that specific definition - two definitions with different claim filters on one gateway resolve to different identities, so a session initialized with one token cannot be reused by a caller whose token resolves to the other. A definition with an identity claim goes one step further and resolves each person to an identity of their own, <definition>/<claim value>, so that two people let in by one definition are two callers. The details are on the bearer tokens page.
Rejections
A request without valid credentials never reaches any tool, and how it is refused depends on the gateway's OAuth field:
- With OAuth off, the request is refused with HTTP 403 and an empty body.
- With OAuth on, the request is refused with HTTP 401 and a
WWW-Authenticateheader naming the gateway's metadata document, from which an MCP client learns where to send the person to sign in. A request with a token the gateway did not accept also getserror="invalid_token"in the header:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://api.example.com/.well-known/oauth-protected-resource/mcp/billing", error="invalid_token"
Each rejection is logged in the server log with the gateway, the security definition and the username involved, e.g.:
With the audit log on, rejections are recorded too, as auth-failed events that say why the token was refused and, when it could be read, who presented it.
Origin validation
For gateways reachable from browsers, the Zato_MCP_Check_Origin environment variable, set to true, additionally validates the Origin header of incoming requests against the gateway's list of allowed origins - a request whose origin is not on the list is refused with HTTP 403 and logged:
MCP gateway `billing` rejected origin `https://evil.example` (sec name=`partner.key` username=`partner1`)
With validation off, which is the default, the header is ignored. Requests without the header, e.g. from command-line clients, are never affected either way.
See also
| Feature | What it does |
|---|---|
| Rate limits | Traffic caps configured on the same security definitions |
| Audit log | How accepted and rejected requests are recorded |
| Bearer tokens | Static tokens and JWTs with JWKS, audience and claim filters |
| OAuth | Sign-in through your identity provider in place of a key |
| REST authentication | The same definitions and groups protecting REST channels |