Skip to content

📖 MCP Server Authentication & Integration Cookbook ​

"If Your Backend MCP Server Requires X ➔ Here Is Exact Setup Y" ​

This guide provides practical recipes to connect backend Model Context Protocol (MCP) servers to Model Context Gateway (MCG). It covers common authentication patterns and setup steps.


⚡ Quick-Lookup Decision Matrix ​

Find the authentication type that your downstream server requires in the table below. The table shows the required gateway settings:

If Your MCP Server Requires...Transport TypeSecret ProviderAuth ShapeKey Router Configuration Fields
1. No Auth / Public / Localsse / httpNonebearer (ignored)Leave ApiKey and SecretPath blank.
2. Standard Bearer Token (Authorization: Bearer <token>)sse / httpNone, Environment, or VaultbearerEnter token in ApiKey, or set SecretProvider: Environment with the variable name, or use Vault.
3. Custom HTTP Header (e.g. X-API-Key, X-Plex-Token)sse / httpNone, Environment, or Vaultcustom-header or x-api-keySet AuthShape: custom-header, SecretField: <Header-Name>, and enter the token.
4. HTTP Basic Auth (Authorization: Basic <base64>)sse / httpNone, Environment, or VaultbasicEnter the username:password string. The gateway formats the Base64 header automatically.
5. URL Query Parameter (http://host/sse?token=<key>)sse / httpNone, Environment, or VaultquerySet AuthShape: query and SecretField: <param_name> (defaults to token).
6. Local CLI Binary / Subprocess (stdio)stdioNone, Environment, or Vault(Auto-handled)Command and arguments. The gateway injects secrets into process environment variables.
7. HashiCorp Vault Secrets (Enterprise Key Rotation)sse, http, stdioVault(Matches backend)SecretProvider: Vault, Vault Mount: secret, Path: <path>, Field: <key>.
8. Windows DPAPI Registry Secrets (Windows Server / IIS)sse, http, stdioWindowsRegistry(Matches backend)SecretProvider: WindowsRegistry, Registry Path: SOFTWARE\McpRouter\Secrets, Key Name: <Key>.
9. Per-User Personal Access Tokens (BYOK)sse / httpUserProvided(Matches backend)SecretProvider: UserProvided. Users save personal tokens in the My MCP Servers tab (backed by encrypted DB or Vault).
10. Pass-Through Dynamic JWTssse / httpAllowPassThroughAuth(Matches backend)Set AllowPassThroughAuth: true. The client passes the token in the X-Target-Auth header.
11. Identity-Forwarding Gateway (Downstream RLS)sse / http(Any)(Matches backend)The gateway sends a service account token and passes X-Forwarded-User: <username> for Row-Level Security.
12. RFC 8693 Downstream Token Exchangesse / httpTokenExchangebearerExchanging caller identity/token with an In-House IdP for downstream audience tokens.
13. Windows Kerberos Impersonationsse / httpNone (Locked)impersonationAuthShape: impersonation. Runs downstream request under caller's Windows token (S4U2Proxy / IIS).
14. 3LO Egress OAuth (Connected Accounts)sse / http(OAuth 3LO Enabled)bearerDownstream SaaS requiring user login (GitHub, Slack, Jira). MCG handles the OAuth redirect and callback, vaults user tokens in DB/Vault with AES-256-GCM, and automatically handles token refresh.

🚫 Incompatible Combinations & Configuration Guardrails ​

The Model Context Gateway Web UI and API enforce strict validation rules to protect against conflicting, non-functional, or insecure configurations:

CombinationStatusWhy It Is Disallowed & Gateway Behavior
Kerberos Impersonation + External Secret Provider (Vault / Env / DPAPI)❌ ForbiddenWhen AuthShape: impersonation is selected, outbound calls execute inside WindowsIdentity.RunImpersonated using the authenticated caller's Windows token. Fetching an external API key is irrelevant and contradictory. The UI disables and locks Secret Provider to None.
Kerberos Impersonation + Static API Key❌ ForbiddenImpersonation authenticates using Windows credentials, not a hardcoded static bearer token. The UI disables and hides the API Key input.
User-Provided (BYOK) + Static Server API Key❌ ForbiddenWhen SecretProvider: UserProvided is selected, credentials resolve dynamically on a per-user basis from the user secret store. Entering a global server API key creates ambiguity. The UI disables the static API Key input.
Token Exchange + Kerberos Impersonation❌ ForbiddenToken Exchange mints an OAuth 2.0 / OIDC JWT for downstream HTTP/SSE endpoints. It cannot be combined with Windows Kerberos OS-level token impersonation.
Vault User Secret Store + Vault Provider Disabled⚠️ WarningIf administrators configure User Secret Storage to use HashiCorp Vault (KV v2), but the primary Vault secret provider is disabled or unconfigured, the UI displays a prominent warning banner and user credential lookups will fail closed.

🍳 Detailed Recipes & Implementation Examples ​


Recipe 1: No Authentication (Local Sidecars, Public Services) ​

  • Common Use Cases: Local test servers, unauthenticated Docker container sidecars, and internal read-only MCP tools.
  • How It Works: The gateway connects directly without sending authorization headers.

Web UI Configuration: ​

  1. Click + Add Server.
  2. Set Server ID to mock-tools.
  3. Set Transport Type to SSE Stream or HTTP JSON-RPC.
  4. Set URL to http://mock-service:8080/sse.
  5. Set Secret Provider to None.
  6. Leave API Key empty.
  7. Click Save Server.

Admin MCP Tool JSON (manage_servers): ​

json
{
  "action": "create",
  "id": "mock-tools",
  "displayName": "Mock Tools Service",
  "url": "http://mock-service:8080/sse",
  "type": "sse",
  "category": "testing",
  "secretProvider": "None",
  "enabled": true
}

Recipe 2: Static Bearer Token (Authorization: Bearer <token>) ​

  • Common Use Cases: Home Assistant (Long-Lived Access Tokens), OpenAI/LiteLLM MCP, Docker Socket Proxy, and SaaS APIs.
  • How It Works: The gateway formats the resolved secret as Authorization: Bearer <secret> on outbound requests.
  • Bearer Token Explained: A bearer token is a secret security key. Any client that sends this token receives access.

Option A: Direct Static Token in DB (AES-256-GCM Encrypted) ​

  • Secret Provider: None
  • API Key / Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
  • Auth Shape: bearer
  • Set this variable in your host or container environment: HOMEASSISTANT_TOKEN=eyJhbGci...
  • In the server modal:
    • Secret Provider: Environment
    • Secret Field / Env Var: HOMEASSISTANT_TOKEN
    • Auth Shape: bearer

Admin MCP Tool JSON (manage_servers): ​

json
{
  "action": "create",
  "id": "homeassistant",
  "displayName": "Home Assistant Smart Home",
  "url": "http://ha-mcp:8086/sse",
  "type": "sse",
  "category": "smarthome",
  "secretProvider": "Environment",
  "secretField": "HOMEASSISTANT_TOKEN",
  "authShape": "bearer",
  "enabled": true
}

Recipe 3: Custom HTTP Header Auth (X-API-Key, X-Plex-Token, etc.) ​

  • Common Use Cases: Plex (X-Plex-Token), Radarr/Sonarr (X-Api-Key), Anthropic (x-api-key), and custom microservices.
  • How It Works: The gateway extracts the secret and inserts it into the specified header name.

Example 3A: Plex Media Server (X-Plex-Token) ​

  • Transport: SSE Stream
  • URL: http://plex-mcp:8000/sse
  • Secret Provider: Environment
  • Secret Field (Env Var & Header): PLEX_TOKEN
  • Auth Shape: custom-header
  • Custom Header Name: X-Plex-Token

Example 3B: Radarr / Sonarr (X-Api-Key) ​

  • Secret Provider: None (or Environment: RADARR_API_KEY)
  • Auth Shape: x-api-key (or custom-header with SecretField: X-Api-Key)

Admin MCP Tool JSON (manage_servers): ​

json
{
  "action": "create",
  "id": "plex",
  "displayName": "Plex Media Server",
  "url": "http://plex-mcp:8000/sse",
  "type": "sse",
  "category": "media",
  "secretProvider": "Environment",
  "secretField": "PLEX_TOKEN",
  "authShape": "custom-header",
  "customHeaderName": "X-Plex-Token",
  "enabled": true
}

Recipe 4: HTTP Basic Authentication (Authorization: Basic ...) ​

  • Common Use Cases: Legacy internal APIs and services requiring username and password credentials.
  • How It Works: Enter username:password as the secret. The gateway Base64-encodes the value and sends Authorization: Basic <base64>.

Web UI Configuration: ​

  • Secret Provider: None (or Environment: SERVICE_BASIC_AUTH)
  • API Key / Secret: admin:SuperSecretPassword123
  • Auth Shape: basic

Admin MCP Tool JSON (manage_servers): ​

json
{
  "action": "create",
  "id": "legacy-db-mcp",
  "displayName": "Legacy Database MCP",
  "url": "http://internal-db-mcp:8080/mcp",
  "type": "http",
  "category": "database",
  "apiKey": "admin:SuperSecretPassword123",
  "authShape": "basic",
  "enabled": true
}

Recipe 5: URL Query Parameter Authentication (?token=<key>) ​

  • Common Use Cases: Webhook-style MCP backends and streaming servers that reject custom HTTP headers during connection handshake.
  • How It Works: The gateway appends ?<param_name>=<secret> to the request URL.

Web UI Configuration: ​

  • Endpoint URL: http://streaming-service:9000/sse
  • Secret Provider: Environment (e.g. STREAM_API_KEY)
  • Auth Shape: query
  • Secret Field: token (or a custom query parameter name like apiKey)

Resulting Outbound Request: ​

GET http://streaming-service:9000/sse?token=ResolvedSecretKey123


Recipe 6: Local Subprocess / STDIO Process Environment (stdio) ​

  • Common Use Cases: Official MCP CLI tools (@modelcontextprotocol/server-filesystem, @modelcontextprotocol/server-github, uvx, Python scripts).
  • How It Works (Zero CLI Leakage): The gateway spawns the subprocess. It injects the resolved secret directly into process environment variables (ProcessStartInfo.Environment["API_KEY"]). Secrets never appear in command-line arguments or process inspection tools (ps aux).

Web UI Configuration: ​

  • Transport Type: STDIO CLI
  • Command / Executable: npx
  • Arguments: -y @modelcontextprotocol/server-filesystem /shared/data
  • Secret Provider: Environment (or Vault)
  • Secret Field: GITHUB_PERSONAL_ACCESS_TOKEN

Admin MCP Tool JSON (manage_servers): ​

json
{
  "action": "create",
  "id": "filesystem-mcp",
  "displayName": "Local Filesystem MCP",
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/app/data"],
  "category": "infrastructure",
  "enabled": true
}

TIP

When running in Docker, use the ghcr.io/spelech/model-context-gateway:latest-full container image. It includes Node.js 22, Python 3.12, uv, and bun to run stdio tools out of the box.


Recipe 7: Enterprise Credential Rotation with HashiCorp Vault (KV v2) ​

  • Common Use Cases: Production environments requiring automated token rotation, zero secrets stored in database files, and central audit logging.
  • How It Works: The gateway authenticates to Vault with AppRole (roleId/secretId) or a token. It reads the secret from secret/data/<path>, caches it in memory for 10 minutes, and injects it into downstream calls.

Step 1: Configure Vault in Router Settings ​

In Settings -> Secret Providers -> HashiCorp Vault:

json
{
  "address": "https://vault.corp.internal:8200",
  "mountPath": "secret",
  "roleId": "8f8c49e2-1234-5678-abcd-ef0123456789",
  "secretId": "3b2a1c0d-9876-5432-fedc-ba9876543210"
}

Step 2: Configure Server with Vault Path ​

  • Secret Provider: Vault
  • Vault Mount: secret
  • Secret Path: infrastructure/docker
  • Secret Field: api_key
  • Auth Shape: bearer

Admin MCP Tool JSON (manage_servers): ​

json
{
  "action": "create",
  "id": "docker-prod",
  "displayName": "Production Docker MCP",
  "url": "http://docker-mcp.internal:8080/sse",
  "type": "sse",
  "category": "infrastructure",
  "secretProvider": "Vault",
  "vaultMount": "secret",
  "vaultPath": "infrastructure/docker",
  "vaultKey": "api_key",
  "authShape": "bearer",
  "enabled": true
}

Recipe 8: Enterprise Windows DPAPI Registry Secrets (Windows Server / IIS) ​

  • Common Use Cases: Windows Server and IIS on-premises deployments using Active Directory machine trust and DPAPI hardware encryption.
  • How It Works: Secrets stored in HKLM\SOFTWARE\McpRouter\Secrets with Windows DPAPI encryption are decrypted in memory by the gateway service account.

Web UI Configuration: ​

  • Secret Provider: WindowsRegistry
  • Registry Path: SOFTWARE\McpRouter\Secrets
  • Key Name: ProdDatabaseApiKey
  • Auth Shape: bearer

Recipe 9: Multi-Tenant / Bring-Your-Own-Key (BYOK / UserProvided) ​

  • Common Use Cases: Shared gateway deployments where users connect with their personal tokens (such as personal GitHub PATs, Slack user tokens, or Notion API keys).
  • Storage Backends:
    • Database (Default): Credentials stored in UserCredentialDto table encrypted with AES-256-GCM.
    • HashiCorp Vault (KV v2): User credentials stored dynamically in Vault using configurable path templates (e.g. {Company}/mcgateway/{User}/{Server}).
  • How It Works:
    1. The administrator registers the server with SecretProvider: UserProvided.
    2. The UI automatically disables the static API Key field to prevent conflicts.
    3. Users open the My MCP Servers tab in the dashboard.
    4. Users enter their personal API token (or full JSON credential object).
    5. The gateway decrypts and injects the user's personal token when they execute tool calls.

Admin Server Registration: ​

  • Secret Provider: UserProvided
  • Auth Shape: bearer (or custom-header)

Recipe 10: Dynamic OAuth 2.0 / OIDC Token Exchange & Pass-Through JWTs ​

  • Common Use Cases: Downstream microservices that require short-lived user JWTs from an identity provider (Keycloak, Authentik, Okta, Microsoft Entra ID).
  • OAuth 2.0 Explained: OAuth 2.0 allows applications to access services on behalf of users without sharing credentials.
  • How It Works:
    • Pass-Through Mode: Set AllowPassThroughAuth: true. The client sends the JWT in the X-Target-Auth header. The gateway maps X-Target-Auth into the backend auth format (such as Authorization: Bearer <jwt>).
    • Interactive OAuth Consent: Third-party applications register through Dynamic Client Registration (RFC 7591) and call /connect/authorize. Users approve access on the /consent screen.

Recipe 11: Trusted Gateway Pattern (Identity-Forwarding for Row-Level Security) ​

  • Common Use Cases: Backend MCP servers that enforce internal authorization and require the user principal for Row-Level Security (RLS).
  • How It Works: The gateway authenticates to the backend using a shared Service Account token. It adds standard identity propagation headers to each request:
    • X-Forwarded-User: <username> (e.g. admin or DOMAIN\spelech)
    • X-Forwarded-Groups: <groups> (e.g. full_admin, engineering)
    • X-Mcp-Session-Id: <session_id>

The backend server trusts the gateway IP and applies Row-Level Security based on the forwarded identity.


Recipe 12: RFC 8693 Downstream Token Exchange (In-House IdP / Microservices) ​

  • Common Use Cases: Downstream microservices that require audience-specific tokens from an enterprise Identity Provider.
  • How It Works:
    1. The client sends a request authenticated with an External JWT Bearer or AppKey.
    2. The TokenExchangeClient connects to the IdP token endpoint (urn:ietf:params:oauth:grant-type:token-exchange).
    3. The gateway exchanges the user token for a downstream bearer token for the target audience.
    4. The gateway sends Authorization: Bearer <downstream_jwt>.

Admin Server Registration: ​

  • Secret Provider: TokenExchange
  • Secret Key / Parameter: Downstream audience or resource URL (such as https://mcp-internal.corp.local/api/tools).
  • Auth Shape: bearer

Recipe 13: Windows Kerberos Impersonation (IIS / Windows Domain Services) ​

  • Common Use Cases: Downstream servers on Windows Server and IIS that require the caller's Windows domain identity.
  • Operating System Requirement: Windows Server and IIS only. This mode does not operate on Linux containers.
  • How It Works:
    1. The user authenticates with Windows Integrated Authentication (Negotiate / Kerberos).
    2. The gateway extracts the caller's WindowsIdentity.
    3. The HTTP transport executes within WindowsIdentity.RunImpersonated().
    4. Outbound HTTP requests use the caller's Kerberos ticket.

Admin Server Registration: ​

  • Secret Provider: None (Locked)
  • Auth Shape: impersonation
  • API Key: (Disabled / Not Applicable)

Recipe 14: Personal 3LO Egress OAuth (Connected Accounts) ​

  • Common Use Cases: SaaS MCP servers where every developer must execute operations as themselves (e.g. GitHub Copilot/Issues, Atlassian Jira, Slack, Linear, Salesforce).
  • How It Works:
    1. The administrator registers the server with EnableOAuth3Lo: true and configures the OAuth Client ID and Secret.
    2. Developers open the My MCP Servers dashboard tab and click Connect Account.
    3. The gateway manages the browser OAuth flow out-of-band and receives the callback at /api/oauth/egress/callback.
    4. Access and refresh tokens are encrypted at rest with AES-256-GCM.
    5. When AI agents call tools, the gateway strips the developer's gateway key, verifies expiration, auto-refreshes tokens via refresh_token if needed, and injects Authorization: Bearer <user_token>.

Web UI Configuration: ​

  1. Open the server configuration modal.
  2. Check Enable OAuth (3LO).
  3. Fill in the OAuth Client parameters:
    • OAuth Client ID: SaaS Application Client ID.
    • OAuth Client Secret: SaaS Application Secret (stored encrypted).
    • Authorization URL: e.g. https://github.com/login/oauth/authorize.
    • Token URL: e.g. https://github.com/login/oauth/access_token.
    • Scopes: e.g. repo,read:org,write:discussion.
  4. Click Save Server.
  5. Users can now click Connect Account under My MCP Servers.

🎯 Common Backend MCP Server Cheat Sheet ​

MCP ServerTypical TransportRecommended Secret ProviderConfigured Auth ShapeExample Secret Field / Header
Docker Daemon MCPsseEnvironment / VaultbearerDOCKER_MCP_TOKEN
Home Assistant MCPsseEnvironment / VaultbearerHOMEASSISTANT_TOKEN
Plex MCPsseEnvironment / Vaultcustom-headerX-Plex-Token
Overseerr / Seerr MCPsseEnvironment / Vaultx-api-keySEERR_API_KEY
Radarr / Sonarr MCPhttpEnvironment / Vaultx-api-keyX-Api-Key
Actual Budget MCPsseUserProvided (BYOK)bearer(User PAT)
Google Workspace MCPsseEnvironmentbearerGOOGLE_WORKSPACE_TOKEN
Unifi Network MCPsseEnvironmentx-api-keyUNIFI_API_KEY
PostgreSQL / MySQL MCPhttp / stdioEnvironment / Vaultbasic or EnvDB_PASSWORD
Filesystem / GitHub MCPstdioEnvironment(Auto Process Env)GITHUB_TOKEN
Slack Native Direct MCPhttp(OAuth 3LO / Hybrid)bearerxoxp-... (User Token / 3LO Delegated)

Released under the Apache 2.0 License.