Skip to main content

​
Overview

MCP Gateway provides a centralized authentication layer that eliminates the need to manage credentials for individual MCP servers. Users authenticate once with the gateway, and all subsequent requests to MCP servers are automatically verified and authorized.

​
Benefits of Gateway Authentication

​
Single Sign-On (SSO)

Users authenticate once and get access to all authorized MCP servers:
  • No need to manage multiple API keys
  • Consistent authentication experience
  • Automatic token refresh
  • Session management

​
Credential Security

MCP server credentials are securely stored at the gateway:
  • Users never see server API keys
  • Credentials are encrypted at rest
  • Automatic rotation support
  • Audit trail for all access

​
Identity Forwarding

The gateway automatically forwards user identity to MCP servers:
  • User email and name
  • Team and organization info
  • Custom roles and attributes
  • Request context

​
Authentication Methods

MCP Gateway supports multiple authentication methods to fit your organization’s needs.

​
Bearer Token Authentication

The simplest method using API tokens: 
{
  "auth": {
    "type": "bearer",
    "enabled": true
  }
}
Client configuration: 
{
  "mcpServers": {
    "portkey-gateway": {
      "url": "http://localhost:8787/mcp",
      "headers": {
        "Authorization": "Bearer pt_your_token_here"
      }
    }
  }
}
Generate tokens via the gateway API or console. Tokens can be scoped to specific users, teams, and permissions.

​
API Key Authentication

Use API keys with configurable scopes and expiration: 
{
  "auth": {
    "type": "api-key",
    "enabled": true,
    "header": "X-API-Key"
  }
}
Client configuration: 
{
  "mcpServers": {
    "portkey-gateway": {
      "url": "http://localhost:8787/mcp",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

​
OAuth 2.0 / OIDC

Integrate with your existing identity provider: 
{
  "auth": {
    "type": "oauth",
    "enabled": true,
    "provider": "okta",
    "clientId": "your-client-id",
    "clientSecret": "${OAUTH_CLIENT_SECRET}",
    "issuer": "https://your-org.okta.com",
    "scopes": ["openid", "profile", "email"]
  }
}
Supported providers:
  • Okta
  • Auth0
  • Azure AD
  • Google Workspace
  • Custom OIDC providers
OAuth/OIDC authentication provides the most secure and scalable solution for enterprise deployments.

​
mTLS (Mutual TLS)

For maximum security with client certificate authentication: 
{
  "auth": {
    "type": "mtls",
    "enabled": true,
    "ca": "/path/to/ca.crt",
    "requireClientCert": true
  }
}
Use cases:
  • High-security environments
  • B2B integrations
  • Regulated industries
  • Zero-trust architectures

​
Configuring Authentication

1

Choose authentication method

Select the authentication method that fits your requirements:
  • Bearer tokens: Quick setup, good for development
  • API keys: Production-ready, simple to manage
  • OAuth/OIDC: Enterprise SSO integration
  • mTLS: Maximum security
2

Update gateway configuration

Add authentication configuration to your gateway:
# Set via environment variables
export PORTKEY_AUTH_TYPE=bearer
export PORTKEY_AUTH_ENABLED=true

# Or update config file
vim gateway-config.json
3

Generate credentials

Create authentication credentials for your users:
# Via API
curl -X POST http://localhost:8787/v1/auth/tokens \
  -H "Authorization: Bearer admin-token" \
  -H "Content-Type: application/json" \
  -d '{
    "user": "[email protected]",
    "team": "engineering",
    "scopes": ["mcp:read", "mcp:write"],
    "expiresIn": "30d"
  }'
You can also generate tokens via the gateway console UI.
4

Configure MCP clients

Update your MCP client configuration with the credentials:
{
  "mcpServers": {
    "portkey-gateway": {
      "url": "http://localhost:8787/mcp",
      "headers": {
        "Authorization": "Bearer pt_...your_token..."
      }
    }
  }
}

​
Token Management

​
Creating Tokens

Generate tokens with specific permissions and expiration: 
curl -X POST http://localhost:8787/v1/auth/tokens \
  -H "Authorization: Bearer admin-token" \
  -d '{
    "user": "[email protected]",
    "team": "data-science",
    "permissions": {
      "servers": ["github", "filesystem"],
      "tools": ["read", "write"]
    },
    "expiresIn": "7d"
  }'

​
Revoking Tokens

Instantly revoke access when needed: 
curl -X DELETE http://localhost:8787/v1/auth/tokens/pt_abc123 \
  -H "Authorization: Bearer admin-token"

​
Token Rotation

Rotate tokens before expiration: 
curl -X POST http://localhost:8787/v1/auth/tokens/pt_abc123/rotate \
  -H "Authorization: Bearer admin-token"

​
Identity Forwarding

The gateway automatically forwards user identity to MCP servers in request headers: 
POST /tool/call
X-User-Email: [email protected]
X-User-Name: Alice Smith
X-User-Team: engineering
X-User-Roles: developer,team-lead
X-Organization-Id: org_abc123
Your MCP server can use these headers to:
  • Personalize responses
  • Apply user-specific permissions
  • Track user activity
  • Implement custom authorization logic
Identity forwarding is automatically enabled and requires no additional configuration.

​
Security Best Practices

​
Token Security

Set appropriate expiration times:
  • Development: 7-30 days
  • Production: 1-7 days
  • CI/CD: 1-24 hours
  • Implement automatic rotation
Grant minimum required permissions:
  • Limit to specific servers
  • Restrict to necessary tools
  • Use team-based scoping
  • Regular permission audits
Store tokens securely:
  • Use environment variables
  • Never commit to version control
  • Encrypt in CI/CD systems
  • Use secret managers (AWS Secrets Manager, Vault)
Track authentication activity:
  • Log all authentication attempts
  • Alert on failed attempts
  • Monitor token usage patterns
  • Regular access reviews

​
TLS/SSL Configuration

Always use HTTPS in production: 
{
  "server": {
    "ssl": {
      "enabled": true,
      "cert": "/path/to/cert.pem",
      "key": "/path/to/key.pem"
    }
  }
}
Never use plain HTTP for authentication in production environments. Always use HTTPS to protect credentials in transit.

​
Example: Complete Auth Setup

Here’s a complete authentication configuration example:
gateway-config.json
{
  "server": {
    "port": 8787,
    "ssl": {
      "enabled": true,
      "cert": "/etc/ssl/gateway.crt",
      "key": "/etc/ssl/gateway.key"
    }
  },
  "auth": {
    "type": "oauth",
    "enabled": true,
    "provider": "okta",
    "clientId": "your-client-id",
    "clientSecret": "${OAUTH_CLIENT_SECRET}",
    "issuer": "https://your-org.okta.com",
    "scopes": ["openid", "profile", "email"],
    "tokenExpiration": "7d"
  },
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
    }
  },
  "identityForwarding": {
    "enabled": true,
    "headers": ["email", "name", "team", "roles"]
  }
}

​
Next Steps

Access Control

Configure granular permissions and role-based access

Monitoring

Track authentication events and security metrics

Build docs developers (and LLMs) love

Get started for freeTalk to us