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.:
MCP gateway `billing` rejected unauthenticated request (sec name=`partner.key` username=`partner1`)
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
The Zato_MCP_Check_Origin environment variable, set to true, refuses every request that carries an Origin header with HTTP 403 and logs it. Browsers send this header with their requests, so the variable keeps web pages from calling your gateways:
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. The value must be true in lowercase, and Zato reads it when the server starts.
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 |