Set up the MCP Authorization Server

Model Context Protocol (MCP), like many other AI-related technologies, is still novel when it comes to security best practices.

This page explains how to configure the Aembit MCPModel Context Protocol: A standard protocol for AI agent and server interactions that defines how AI assistants communicate with external tools and data sources.Learn more(opens in new tab) Authorization Server.

Human/user authentication only

Aembit’s MCP Authorization Server supports human/user authentication only. See Current authentication support.

Prerequisites

Before you begin, ensure you have:

• An Aembit TenantAembit Tenant: Aembit Tenants serve as isolated, dedicated environments within Aembit that provide complete separation of administrative domains and security configurations.Learn more with admin access
• At least one identity provider configured in Administration > Identity Providers:
  • OIDC 1.0 - Requires an OIDC ID Token Trust Provider and a Credential Provider
  • SAML 2.0 - Requires a Credential Provider (Trust Provider validation not available)
• An MCP serverMCP Server: A server that implements the Model Context Protocol to provide tools, resources, or data to AI agents and MCP clients.Learn more (cloud, on-premises, or local demo)
• An MCP clientMCP Client: An application (such as Claude Desktop, Claude Code, or Gemini CLI) that connects to MCP servers to access tools and resources on behalf of users.Learn more (for example, MCP Jam or Gemini CLI)

For details on the differences between OIDC and SAML flows, see Choosing between OIDC and SAML.

Configure an Access Policy

Configure your Access PolicyAccess Policy: Access Policies define, enforce, and audit access between Client and Server Workloads by cryptographically verifying workload identity and contextual factors rather than relying on static secrets.Learn more with these components:

Create a Client Workload

Create a Client WorkloadClient Workload: Client Workloads represent software applications, scripts, or automated processes that initiate access requests to Server Workloads, operating autonomously without direct user interaction.Learn more to represent the MCP clients that will request access to your MCP servers. For MCP, use the Redirect URI identifier type - this allows MCP clients to register dynamically at runtime through Dynamic Client Registration. For details on how redirect URIs work in MCP, see Redirect URIs.

For general Client Workload configuration guidance, see Client Workloads.

1. Log into your Aembit Tenant.

2. Go to Client Workloads in the left sidebar.

3. Click + New to open the Client Workload form.

4. Enter the Name and optional Description for your MCP client.

5. Under Client Identification, select Redirect URI from the dropdown.

6. In the Value field, enter the redirect URI that your MCP client uses for OAuth callbacks.

   Each MCP client uses a specific redirect URI for OAuth callbacks. Enter the redirect URI for your client:

   Local host

   Local development:

   MCP client	Redirect URI
   MCP Jam	http://localhost:6274/oauth/callback
   Gemini CLI	http://localhost:7777/oauth/callback

   Local development

   For local development, you can use either 127.0.0.1 or localhost. The MCP specification allows ephemeral ports, so the Authorization Server ignores port numbers in redirect URIs when matching policies against local IP addresses. See Access Policy matching.

   Remote/cloud

   Remote or cloud-hosted:

   MCP client	Redirect URI
   Claude Desktop	https://claude.ai/api/mcp/auth_callback
   Custom web app	https://your-app.example.com/oauth/callback

7. Click Save to create the Client Workload.

Create a Server Workload

Create a Server WorkloadServer Workload: Server Workloads represent target services, APIs, databases, or applications that receive and respond to access requests from Client Workloads.Learn more to represent the MCP server you want to protect. The configuration must match the URL that MCP clients connect to and your MCP server’s resource server URL. The specific configuration name varies by implementation (for example, FastMCP uses resource_server_url).

For general Server Workload configuration guidance, see Server Workloads.

1. In Aembit, go to Server Workloads in the left sidebar.

2. Click + New to open the Server Workload form.

3. Enter the Name and optional Description for your MCP server.

4. In the Host field, enter the hostname where your MCP server runs (for example, mcp.acme-corp.example.com).

5. From the Application Protocol dropdown, select MCP.

6. In the Port field, enter the port your MCP server listens on (for example, 443 for HTTPS).

7. (Optional) In the URL Path field, enter the path if your MCP server uses one (for example, /mcp).

   When you select MCP as the application protocol, Aembit automatically configures HTTP Authentication with the Bearer scheme. The Aembit MCP Authorization Server URL field displays the auto-generated authorization server URL that MCP clients use for OAuth discovery.

   URL alignment

   The Host, Port, and URL Path must match exactly with:

   • The URL your MCP clients connect to
   • The resource server URL in your MCP server configuration (for example, resource_server_url in FastMCP)

   See URL configuration alignment for details.

8. Click Save to create the Server Workload.

Create a Trust Provider

Create a Trust ProviderTrust Provider: Trust Providers validate Client Workload identities through workload attestation, verifying identity claims from the workload's runtime environment rather than relying on pre-shared secrets.Learn more to validate user identity during the MCP authorization flow. The Trust Provider verifies that incoming identity tokens match your expected claims.

For detailed configuration including advanced claim matching, see OIDC ID Token Trust Provider.

1. In Aembit, go to Trust Providers in the left sidebar.

2. Click + New to open the Trust Provider form.

3. Enter the Name and optional Description for your Trust Provider.

4. From the Trust Provider dropdown, select OIDC ID Token.

5. Configure the Attestation Method:

   • Method - Select OIDC Discovery (recommended for standard OIDC providers).
   • OIDC Endpoint - Enter your identity provider’s discovery URL, for example: https://login.microsoftonline.com/{tenant}/v2.0.

6. Configure Match Rules to validate identity token claims:

   • Audience (aud) - The intended recipient of the token. Set this to your Aembit identity provider client ID. This ensures your MCP server only accepts tokens issued for your application.
   • Issuer (iss) - (Optional) The identity provider URL that issued the token.
   • Subject (sub) - (Optional) The user identifier pattern to match.

   Avoid wildcards

   You can use * as a wildcard to allow any value, but Aembit doesn’t recommend this approach. Wildcards weaken your security posture by allowing tokens from unintended sources. Always specify explicit values when possible, especially for the aud (audience) claim.

7. Click Save. Aembit displays your new Trust Provider in the list of Trust Providers.

Configure Access Conditions (optional)

Optionally configure Access ConditionsAccess Condition: Access Conditions add dynamic, context-aware constraints to authorization by evaluating circumstances like time, location, or security posture to determine whether to grant access.Learn more to add additional security requirements such as time-based restrictions or geolocation-based access control. For details, see Access Conditions.

Create a Credential Provider

For OIDC identity providers, create an OIDC ID Token Credential ProviderCredential Provider: Credential Providers obtain the specific access credentials—such as API keys, OAuth tokens, or temporary cloud credentials—that Client Workloads need to authenticate to Server Workloads.Learn more. This configures how Aembit issues tokens that MCP servers use to authenticate requests.

SAML identity providers

If you’re using a SAML identity provider, you still need a Credential Provider to generate access tokens. The only difference is that Trust Provider validation isn’t available for SAML (a SAML Trust Provider doesn’t exist yet).

For detailed Credential Provider configuration guidance, see Create an OIDC ID Token Credential Provider.

1. In Aembit, go to Credential Providers in the left sidebar.

2. Click + New to open the Credential Provider form.

3. Enter the Name and optional Description for your Credential Provider.

4. Under Credential Type, select OIDC ID Token.

5. Configure the following fields:

   • Subject - Select Dynamic or Literal. Use Dynamic to extract the subject from the incoming identity token. For details, see Dynamic Claims.
   • Audience - Your MCP server’s base URL (for example, https://mcp.acme-corp.example.com). Must match the token audience your server expects.
   • Lifetime - Token validity in seconds, for example 3600 (1 hour). Adjust based on security requirements.
   • Signing Algorithm Type - Select ES256 (default) or RSA.

   Aembit auto-generates the Issuer field based on your tenant configuration.

6. (Optional) Add Custom Claims if your MCP server requires additional token claims.

7. Click Save to create the Credential Provider.

Use MCP clients

After configuring your Access Policy, connect an MCP client to your protected MCP server. The following clients support OAuth 2.1 with Dynamic Client Registration, which allows them to automatically discover and authenticate with the Aembit MCP Authorization Server.

Select your MCP client to see configuration instructions:

MCP Jam

MCPJam Inspector is an MCP client that provides visual testing and debugging for your MCP servers. It includes an OAuth debugger that displays each step of the authentication flow. This helps troubleshoot issues that are otherwise invisible due to redirects.

To start the MCPJam Inspector:

npx @mcpjam/inspector@latest

The inspector launches in your browser at http://127.0.0.1:6274.

Local development configuration:

Field	Value
Transport	Streamable HTTP
Server URL	http://localhost:8000/mcp
Auth	OAuth 2.1 with Dynamic (DCR)

Remote server configuration:

Field	Value
Transport	Streamable HTTP
Server URL	https://your-server.example.com/mcp
Auth	OAuth 2.1 with Dynamic (DCR)

When running the inspector in Docker and connecting to a host machine server, use http://host.docker.internal:PORT instead of http://localhost:PORT.

The debugger displays each step of the authorization flow:

1. Initial MCP request (401 response)
2. Metadata retrieval
3. Dynamic client registration
4. Authorization request
5. Token exchange
6. Authenticated MCP request

MCPJam Inspector supports Standard Input/Output (STDIO), Server-Sent Events (SSE), and streamable HTTP connections, with OAuth 2.1 and bearer token authentication.

Network considerations: MCPJam uses a backend proxy server to fetch OAuth metadata. If your MCP server has restricted network access, you may need to allow MCPJam’s proxy IP ranges. See MCPJam backend proxy error for details.

Gemini CLI

Gemini CLI supports automatic discovery and registration with the MCP Authorization Server.

Key details:

• Supports OAuth 2.0 authentication for remote MCP servers
• Automatic OAuth discovery for servers that support it
• Manages tokens automatically after initial authentication

Authentication commands:

• /mcp auth - List servers requiring authentication
• /mcp auth serverName - Authenticate with a specific server

Add your MCP server to the Gemini CLI settings.json file:

Scope	File path
User (global)	~/.gemini/settings.json
Project	.gemini/settings.json

Add the mcpServers configuration:

{
  "mcpServers": {
    "TestMCPServer": {
      "httpUrl": "http://localhost:8000/mcp"
    }
  }
}

The CLI handles OAuth discovery and registration automatically when it encounters a 401 response from the MCP server.

Claude Desktop

Claude Desktop supports MCP servers through Settings > Connectors.

Adding remote MCP servers

Add remote MCP servers through the Connectors UI, not via claude_desktop_config.json.

Key details:

• Supports OAuth 2.1 with Dynamic Client Registration (DCR)
• OAuth callback URL: https://claude.ai/api/mcp/auth_callback
• Available on Pro, Max, Team, and Enterprise plans

Configuration:

1. Navigate to Settings > Connectors
2. Add your MCP server URL (for example, http://localhost:8000/mcp)
3. Optionally configure OAuth client_id and client_secret in Advanced settings
4. Complete OAuth authentication when prompted

For more information, see Building Custom Connectors via Remote MCP Servers.

Claude Code

Claude Code supports MCP servers through the CLI or configuration files.

Key details:

• Supports OAuth 2.0 for MCP servers
• Supports Dynamic Client Registration (DCR)
• Uses /mcp command to manage authentication
• Automatic token storage and refresh

Add via CLI:

claude mcp add --transport http test-mcp-server http://localhost:8000/mcp

Add via .mcp.json:

{
  "mcpServers": {
    "TestMCPServer": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Scope	File path
Project (team-shared)	.mcp.json at project root
User	claude mcp add command

To authenticate, run /mcp within Claude Code and select Authenticate.

For more information, see Claude Code MCP Documentation.

If you encounter authentication errors, see Troubleshoot the MCP Authorization Server.

MCP server requirements

To work with Aembit’s MCP Authorization Server, your MCP server needs certain configuration settings. Most of these are standard OAuth concepts from the MCP specification—the exact field names vary by MCP server implementation.

Concept	Purpose	Aembit value	Required by
Authorization Server URL	Where MCP clients discover OAuth endpoints	https://[tenant].mcp.[region].aembit.io	MCP spec
Token Issuer	OIDC issuer URL of token validation	https://[tenant].id.[region].aembit.io	RFC 8414
JWKS URI	Public keys used for token signature verification	https://[tenant].mcp.[region].aembit.io/.well-known/openid-configuration/jwks	RFC 8414
Token Audience	Must match your Credential Provider configuration	Your MCP server’s public URL	RFC 8707
Token Algorithm	Signing algorithm for access tokens	ES256 (default) or RSA	Aembit

Token algorithm

The MCP specification doesn’t mandate a specific signing algorithm. Aembit supports ES256 (default) and RSA—configure your MCP server’s token verifier to match your Credential Provider settings.

Consult your MCP server’s documentation for how to configure these settings. For a complete reference, see Configuration concepts.

Issuer subdomain

When configuring your MCP server’s token verification, the issuer must use the .id. subdomain (for example, abc123.id.useast2.aembit.io), not the .mcp. subdomain. See Tenant URL patterns for details.

Test with a demo MCP server

If you don’t have an existing MCP server, you can use this FastMCP demo server to test your Aembit configuration. This example shows one way to configure the settings from the preceding table—your production MCP server may use different field names or configuration methods.

Replace the placeholder values with your Aembit tenant details, then run with python server.py.

server.py

from fastmcp import FastMCP
from fastmcp.server.auth import RemoteAuthProvider
from fastmcp.server.auth.providers.jwt import JWTVerifier
from pydantic import AnyHttpUrl
import json

# Replace [your-tenant-id] and [region] with your Aembit tenant details.
# Find these values in the Server Workload form after selecting MCP protocol.
cfg = {
    "host": "0.0.0.0",
    "port": 8000,
    "mcp_server_url": "http://localhost:8000",
    # Authorization server uses .mcp. subdomain
    "auth_server": "https://[your-tenant-id].mcp.[region].aembit.io",
    # Token issuer uses .id. subdomain (NOT .mcp.)
    "issuer": "https://[your-tenant-id].id.[region].aembit.io",
    "jwks_uri": "https://[your-tenant-id].mcp.[region].aembit.io/.well-known/openid-configuration/jwks",
}

# Configure JWT verification against Aembit's JWKS endpoint
token_verifier = JWTVerifier(
    jwks_uri=cfg["jwks_uri"],
    issuer=cfg["issuer"],
    audience=cfg["mcp_server_url"],  # Audience must match server URL
    algorithm="ES256",  # Or "RS256" if using RSA in your Credential Provider
)

# Configure OAuth 2.1 discovery - returns 401 with auth server URL
auth = RemoteAuthProvider(
    token_verifier=token_verifier,
    authorization_servers=[AnyHttpUrl(cfg["auth_server"])],
    base_url=cfg["mcp_server_url"],
)

# Initialize server with authentication
mcp = FastMCP(
    "Aembit Test MCP Server",
    host=cfg["host"],
    port=cfg["port"],
    auth=auth,
)


@mcp.tool()
def get_server_status() -> str:
    """Get server status - confirms authentication succeeded."""
    return json.dumps({
        "server": "Aembit Test MCP Server",
        "status": "running",
        "authenticated": True,
        "message": "Successfully authenticated via Aembit!"
    })


if __name__ == "__main__":
    print(f"Starting server on {cfg['mcp_server_url']}/mcp")
    mcp.run(transport="streamable-http")

requirements.txt

fastmcp>=2.11.0
httpx
uvicorn
pyjwt[crypto]
pydantic

Key configuration notes:

• The issuer uses the .id. subdomain (for example, abc123.id.useast2.aembit.io), not .mcp.
• The algorithm must match your Credential Provider setting—ES256 (default) or RSA (see Token algorithm)
• The audience must match your server’s public URL exactly

For URL configuration details, see URL configuration alignment.

Troubleshooting

For common errors and solutions, see Troubleshoot the MCP Authorization Server.

Next steps

• Review the MCP Authorization Server reference for configuration options and endpoints
• Learn more about Access Policies