Configuring Authentication for MCP Servers

When you create an MCP server in the AI Gateway, authentication works in two directions:

• Who connects to your MCP server? This is called Agent Authentication. It's how your team members, AI assistants, or automated pipelines prove their identity before using the server.
• How does your MCP server connect to the app behind it? This is called App Authentication. It's the credential the gateway uses when it calls Gmail, Slack, GitLab, or whatever service your MCP server wraps.

You can configure both from the Authentication tab on any MCP server in the MCP Registry.

Quick Start: Which setup do I need?

Find your situation below and jump to the relevant section.

I want to...	What to configure
Let my team use this MCP server from Cursor, Claude Desktop, or VS Code	Agent Auth → Interactive (SSO)
Let a CI/CD pipeline or script use this MCP server	Agent Auth → Passthrough
Connect to an app that uses OAuth (Google, Slack, GitLab, etc.)	App Auth → OAuth 2.1 Authorization
Connect to an app using an API key or token my IT team gave me	App Auth → API Key or Bearer Token
The upstream app needs two different credentials in the same request	Additional Outbound Headers

---

Agent Authentication

"Who is allowed to connect to my MCP server?"

This controls how AI clients (like Cursor or Claude Desktop) or automated systems authenticate before they can use the tools on your MCP server.

To configure:

1. Open the MCP server from the MCP Registry.
2. Click the Authentication tab.
3. Click Edit next to Agent Authentication.

You'll see two options:

Interactive (SSO)

Choose this when: Your team members will connect from an AI coding assistant like Cursor, Claude Desktop, Windsurf, or VS Code.

When a user connects, they'll see a familiar SSO login prompt in their browser. After they log in, the MCP server knows who they are, and every action runs under their own account and permissions.

This is the recommended option for most teams. It means:

• Each person logs in as themselves
• Actions in the connected app (sending an email, creating a ticket) happen under their identity
• You get full visibility into who did what

Passthrough

Choose this when: The connecting system already has its own credentials and you want the gateway to forward them as-is. Common for internal services, scripts, or testing.

With Passthrough, the gateway doesn't add or check any credentials — it simply forwards whatever the caller sends.

Optional: Add JWT validation for extra security

If you're using Passthrough but still want to verify that incoming requests carry a valid token, enable Require JWT Validation. When enabled, the gateway checks the token before forwarding the request:

1. Toggle on Require JWT Validation in the Passthrough configuration.
2. Your IT team can provide the JWKS URL (a URL where the gateway can look up signing keys) or a JWKS JSON blob. Enter one of these.
3. Optionally enter the expected Issuer and Audience if your IT team specifies them.

If the token is missing or invalid, the request is rejected. If you leave JWT validation off, everything passes through without checks.

Restricting which headers get forwarded

Under "Restricted Inbound Headers," you can block specific header patterns from being forwarded to the upstream service. For example, adding x-internal-* ensures that any headers matching that pattern are stripped before the request reaches the upstream app. The gateway always blocks sensitive headers like authorization and cookie automatically.

---

App Authentication

"What credentials does the gateway use when calling the upstream app?"

This controls how your MCP server authenticates to the service it wraps — for example, how it proves to Gmail that it's allowed to read your email.

To configure:

1. Open the MCP server from the MCP Registry.
2. Click the Authentication tab.
3. Click Edit next to App Authentication.
4. To switch types, click Change Authentication Type.

Which type should I choose?

If the app uses...	Choose	Who provides the credentials
OAuth login (Google, Slack, GitLab, Atlassian)	OAuth 2.1 Authorization	Pre-configured by your admin
A service account or machine-to-machine OAuth	OAuth 2.1 Client Credentials	Your IT team (client ID, client secret, token URL)
An API key	API Key	Your IT team or the app's dashboard
A bearer token / access token	Bearer Token	Your IT team or the app's dashboard
Username and password	Basic Authentication	Your IT team
No auth, or the agent supplies its own credentials	Passthrough	Nothing to configure

OAuth 2.1 Authorization

This is the most common setup for apps like Gmail, Google Drive, Slack, or GitLab. It uses an OAuth consent flow so that each user authorizes the gateway to act on their behalf.

You'll see an App ID field — this is pre-configured by your admin when the app was set up in the catalog. In most cases, you won't need to change it.

OAuth 2.1 Client Credentials

Use this when the gateway should authenticate as a service account rather than an individual user. There's no user login involved — the gateway uses a fixed set of credentials.

Your IT team will provide:

• Token URL — where to request tokens
• Client ID and Client Secret — the service account credentials
• Scopes — what the service account is allowed to do

API Key

Some apps (like Datadog, Proofpoint, or internal APIs) use a simple API key. Your IT team or the app's admin console will provide:

• Key Name — the header or parameter name (e.g., X-API-Key or api-key)
• Key Value — the actual key
• Location — whether the key goes in a header or a query parameter

Bearer Token

Similar to an API key, but sent in the standard Authorization: Bearer <token> format. Paste the token your IT team provides.

Basic Authentication

Username and password. Enter the credentials your IT team provides.

Passthrough

The gateway doesn't add any credentials. Use this when the agent calling the MCP server already includes the right credentials and you just want them forwarded.

---

When One Credential Isn't Enough

Some apps require more than one credential in the same request. For example:

• Azure AI Search needs a service-level API key plus the user's SSO token on a separate header.
• An internal API might need both a service token and the caller's identity forwarded.

This is where Additional Outbound Headers come in. They let you attach extra headers to every request the gateway sends to the upstream app — on top of whatever you configured in App Authentication.

How to add an additional header

1. On the Authentication tab, click Edit next to App Authentication.
2. Scroll down to Additional Outbound Headers.
3. Click + Add Header.
4. Pick from the menu of common patterns, or choose Custom header to set one up manually.
5. Fill in the details and click Save.

Common patterns

The + Add Header menu gives you ready-made options for the most common scenarios:

OAuth2 service token

"The upstream app needs a service-level OAuth token."

The gateway will automatically fetch a fresh token using OAuth client credentials and attach it to the header you specify. Your IT team provides the token URL, client ID, and client secret.

Forward caller's token

"The upstream app needs to know who the user is, via their SSO token."

The gateway takes the token the user used to authenticate and attaches it to a header you specify. Useful when the upstream app accepts user tokens on a custom header.

On behalf of caller

"The upstream app needs a token that's scoped to the current user, but issued by a different identity provider."

The gateway takes the user's token, exchanges it with a downstream identity provider for a new token scoped to that specific service, and attaches the result. Your IT team provides the exchange endpoint details.

Stored API key / credential

"I've already saved an API key or token in the AI Gateway's token vault, and I want to use it here."

Select a credential from your vault. You can choose whether it applies to the whole organization or is matched per-user.

Pass caller identity

"The upstream app needs the caller's user ID or email in a header."

Sets a header to a value like the caller's user ID or email, drawn from their authentication token.

Custom header

"None of the above fit. I need to set a specific header with a specific value."

Configure a header from scratch: pick the header name, source type, and value.

---

Real-World Examples

Example 1: "My team wants to use Gmail from Cursor"

Setting	Value
Agent Authentication	Interactive (SSO)
App Authentication	OAuth 2.1 Authorization (pre-configured for Gmail)
Additional Headers	None needed

Your team members open Cursor, connect to the Gmail MCP server, and see a Google login prompt. After signing in, they can ask their AI assistant to read emails, send messages, and manage labels — all under their own Gmail account.

Example 2: "A nightly script needs to pull data from Datadog"

Setting	Value
Agent Authentication	Passthrough
App Authentication	API Key (Datadog API key from your IT team)
Additional Headers	None needed

The script sends requests without any special auth headers. The gateway adds the Datadog API key automatically on every outbound request.

Example 3: "Azure AI Search needs both a service key and the user's token"

Setting	Value
Agent Authentication	Interactive (SSO)
App Authentication	Bearer Token (Azure service API key)
Additional Headers	Forward caller's token → header x-ms-query-source-authorization with prefix Bearer

The gateway sends the service API key on the Authorization header and the user's SSO token on x-ms-query-source-authorization. Azure AI Search uses both to authorize the request.

Example 4: "We're building a chatbot that performs GitHub actions on behalf of each user"

A common pattern for agentic platforms: you're building a chatbot or AI assistant where end users interact through a chat interface, and the AI performs actions in GitHub (creating issues, reviewing PRs, merging code) on their behalf. Each user should only be able to do what they can do in the actual GitHub web app — same repositories, same permissions.

Setting	Value
Agent Authentication	Interactive (SSO)
App Authentication	OAuth 2.1 Authorization (configured for GitHub)
Additional Headers	None needed

What the user experiences:

The user only ever logs into your chatbot platform — they don't need to know the AI Gateway exists. Behind the scenes, two things happen (both feel seamless to the user):

1. Signing in to the platform (automatic). When the chatbot connects to the MCP server, the gateway's Interactive (SSO) auth kicks in. If your chatbot platform and the AI Gateway share the same identity provider (e.g., Okta, Google Workspace, Entra ID), the user is already authenticated — no extra login prompt. They just start chatting.

2. Connecting their GitHub account (one-time). The first time a user tries a GitHub action — say they ask "list my open pull requests" — the gateway notices they haven't linked their GitHub account yet. The chatbot surfaces a prompt like "To use GitHub, please connect your account" with an authorization link. The user clicks it, sees GitHub's familiar consent screen ("Authorize this app to access your repositories"), approves it, and they're back in the chat. This happens once. The gateway stores their GitHub token and uses it automatically from that point on.

After that initial setup, it just works:

• User A asks "list my open pull requests" → the gateway calls GitHub using User A's token → returns only PRs from repos User A has access to.
• User B asks the same question → completely different results, because the gateway uses User B's token.
• If User A can't push to a repo in GitHub's web UI, they can't push through the chatbot either — same permissions, enforced automatically.

Why this is the right approach:

• No shared service account. Each user's actions go through their own GitHub credentials, so there's no risk of one user seeing another's private repos.
• Same permissions as the web app. The gateway uses the user's own OAuth token, so permissions match exactly.
• Full audit trail. Commits, issue comments, and PR reviews show up as the actual user in GitHub — not as a generic "bot" account.
• Scales to any number of users. The gateway manages tokens per-user automatically. You don't need to create individual API keys or service accounts for each person.
• Works for any OAuth-based app. This same pattern applies to Slack, Google Workspace, Jira, GitLab, Salesforce — not just GitHub. Users connect each app once, and the gateway handles the rest.

---

What to ask your IT team

When setting up authentication, you may need to gather a few details. Here's a quick checklist of what to ask for, depending on your setup:

If you're configuring...	Ask your IT team for...
OAuth 2.1 Client Credentials	Token URL, Client ID, Client Secret, Scopes
API Key	Key name, key value, and where it goes (header or query)
Bearer Token	The token value
Basic Authentication	Username and password
JWT Validation (Passthrough)	JWKS URL (or JWKS JSON), expected Issuer, expected Audience
Token Exchange (On behalf of caller)	Exchange endpoint URL, Client ID, Client Secret, audience URL

---

Tips

• Start simple. Most MCP servers only need Interactive (SSO) for agent auth and OAuth 2.1 Authorization for app auth. You can always add more later.
• Use the pre-built recipes. When adding outbound headers, the + Add Header menu has ready-made options for the most common patterns — you don't need to configure everything from scratch.
• You can change authentication after creation. If you pick the wrong type initially, you can always go back to the Authentication tab and switch.
• Credentials are stored securely. API keys, tokens, and OAuth secrets entered in the portal are encrypted and stored in the platform's secret manager.