Skip to main content
MCP Gateway is available on Portkey Cloud. For the complete authentication reference, see portkey.ai/docs/product/mcp-gateway.

​
How authentication works

The MCP Gateway acts as the single authentication boundary for all MCP traffic. Clients authenticate to the gateway once — the gateway then forwards verified requests to your MCP servers without requiring each server to implement its own auth. 
MCP Client
  → presents credentials to Portkey MCP Gateway
  → gateway validates credentials
  → gateway forwards request + verified identity headers to MCP server
  → MCP server trusts the forwarded identity
This means your MCP servers can focus on tool logic rather than authentication infrastructure.

​
Client authentication

Clients authenticate to the gateway using a Portkey API key passed in the x-portkey-api-key request header: 
POST /mcp/YOUR_WORKSPACE_ID/tools/call HTTP/1.1
Host: api.portkey.ai
x-portkey-api-key: YOUR_PORTKEY_API_KEY
Content-Type: application/json
For user-facing applications, Portkey also supports virtual keys — workspace-scoped credentials that can be scoped, rotated, and revoked independently of your main API key.

​
Identity forwarding

After authenticating a request, the gateway forwards the verified user identity to the MCP server as request headers. This lets MCP servers apply their own authorization logic without needing to authenticate the user themselves. The following headers are forwarded automatically:
HeaderValue
x-portkey-userAuthenticated user identifier
x-portkey-teamTeam or workspace the user belongs to
x-portkey-rolesRoles assigned to the user
x-portkey-request-idUnique ID for this request
MCP servers can use these headers to implement per-user access rules, audit trails, or personalized behavior.
MCP servers should validate that requests originate from the Portkey gateway (for example, by checking an internal network policy or a shared secret configured in the Portkey dashboard) before trusting forwarded identity headers.

​
Revoking access

Access can be revoked instantly from the Portkey dashboard:
  • Revoke an API key — immediately blocks all requests using that key
  • Revoke a virtual key — blocks requests from a specific integration or user
  • Disable a workspace — blocks all traffic through that gateway endpoint
Revocation takes effect immediately for all subsequent requests. In-flight requests are not interrupted.

​
Learn more

Build docs developers (and LLMs) love

Get started for freeTalk to us