MCP Authorization Server reference

This reference documents the configuration options, endpoints, and error codes for the Aembit Model Context Protocol (MCP) Authorization Server.

Configuration concepts

MCP servers require specific configuration to work with Aembit’s MCP Authorization Server. Most settings 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
Resource Server URL	Identifies your MCP server for token audience matching	Your MCP server’s public URL	MCP spec
JWKS Endpoint	Public keys used for token signature verification	https://[tenant].mcp.[region].aembit.io/.well-known/openid-configuration/jwks	RFC 8414
Token Issuer	OIDC issuer URL of token validation	https://[tenant].id.[region].aembit.io (note: .id. subdomain)	RFC 8414
Token Audience	Expected audience claim in issued tokens	Must match your Credential Provider configuration	RFC 8707
Signing Algorithm	Algorithm for token signatures	ES256 (default) or RSA	Aembit

MCP server configuration

MCP servers must specify their Authorization Server so unauthenticated clients know where to authenticate. The configuration method varies by implementation.

Example (generic JSON configuration):

{
  "authorization_servers": ["https://[tenant].mcp.[region].aembit.io"],
  "resource_url": "http://localhost:8000",
  "token_issuer": "https://[tenant].id.[region].aembit.io",
  "token_audience": "http://localhost:8000"
}

Implementation-specific field names

The field names shown in the preceding table are examples. Your MCP server may use different names (for example, FastMCP uses authorization_servers and resource_server_url). Consult your MCP server’s documentation for the correct field names.

For environment variable-based configuration, see the MCP server environment variables reference.

MCP client configuration

MCP clients like Gemini CLI discover authorization servers dynamically. Configure the MCP server endpoint in the client configuration:

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

The client handles all discovery and registration steps automatically when it encounters a 401 response from the MCP server.

Tenant URL patterns

Aembit uses different subdomains for different services. When configuring your MCP server, use the correct subdomain for each service.

Service	URL pattern	Example
MCP Auth Server	https://[tenant].mcp.[region].aembit.io	https://abc123.mcp.useast2.aembit.io
Token Issuer	https://[tenant].id.[region].aembit.io	https://abc123.id.useast2.aembit.io
JWKS	https://[tenant].mcp.[region].aembit.io/.well-known/openid-configuration/jwks	https://abc123.mcp.useast2.aembit.io/.well-known/openid-configuration/jwks

Replace [tenant] with your Aembit tenant ID and [region] with your deployment region (for example, useast2).

Token issuer subdomain

The token issuer uses the .id. subdomain, not .mcp.. Ensure your MCP server’s issuer configuration uses the correct subdomain.

Endpoints

Endpoint	Method	Description
/.well-known/openid-configuration	GET	OIDC discovery metadata document
<jwks_uri>	GET	JWKS public keys, as advertised in the discovery document
<registration_endpoint>	POST	Dynamic Client Registration (DCR)
<authorization_endpoint> (e.g. /authorize)	GET	OAuth 2.1 authorization endpoint
<token_endpoint> (e.g. /token)	POST	OAuth 2.1 token endpoint

All endpoints except /.well-known/openid-configuration are discovered via the metadata document and must not be hard-coded; the preceding examples (/authorize, /token) illustrate typical paths only.

Endpoint response examples

OAuth authorization server metadata

GET /.well-known/oauth-authorization-server

Response:

{
  "issuer": "https://[tenant].mcp.[region].aembit.io",
  "authorization_endpoint": "https://[tenant].mcp.[region].aembit.io/connect/authorize",
  "token_endpoint": "https://[tenant].mcp.[region].aembit.io/connect/token",
  "jwks_uri": "https://[tenant].mcp.[region].aembit.io/.well-known/openid-configuration/jwks",
  "registration_endpoint": "https://[tenant].mcp.[region].aembit.io/register",
  "scopes_supported": ["openid", "profile", "email"],
  "response_types_supported": ["code", "token", "id_token", "id_token token", "code id_token", "code token", "code id_token token"],
  "response_modes_supported": ["form_post", "query", "fragment"],
  "grant_types_supported": ["authorization_code"],
  "code_challenge_methods_supported": ["plain", "S256"]
}

Protected resource metadata

GET <resource_metadata_url>

Response:

{
  "resource": "http://your-mcp-server:8000/mcp",
  "authorization_servers": ["https://[tenant].mcp.[region].aembit.io"]
}

HTTP headers

The MCP authorization flow uses these headers:

Response headers

Header	Description
WWW-Authenticate	Returned with 401 responses, contains resource_metadata_url pointing to MCP server metadata

Example 401 response header:

WWW-Authenticate: Bearer resource_metadata_url="http://localhost:8000/mcp"

Request headers

Header	Description
Authorization	Bearer token for authenticated requests to MCP servers

Example authenticated request:

Authorization: Bearer <access_token>

Error codes

The following table contains common HTTP status codes returned by the MCP Authorization Server (this isn’t an exhaustive list):

Code	Description
400	Invalid request (malformed parameters or missing required fields)
401	Unauthorized (authentication failed)
403	Forbidden (Access Policy mismatch)
404	Not found (endpoint or resource doesn’t exist)
429	Too many requests (rate limit exceeded)
500	Internal server error

Supported identity providers

• OpenID Connect (OIDC) providers with multi-factor authentication support
• SAML 2.0 Identity Providers

For guidance on choosing between OIDC and SAML, see MCP Authorization Server overview.

Supported workload types

Client Workloads

Client WorkloadsClient 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 use the Redirect URI identifier type. Aembit’s MCP Authorization Server supports dynamic client registration, allowing clients to register at runtime.

Server Workloads

Server WorkloadsServer Workload: Server Workloads represent target services, APIs, databases, or applications that receive and respond to access requests from Client Workloads.Learn more use the MCP application protocol.

Supported Trust Provider types

• OIDC ID Token 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

SAML Trust Provider support isn’t available yet. When using a SAML identity provider, Aembit skips Trust Provider validation, but a Credential Provider is still required to generate access tokens.

Dynamic client registration (DCR) support

Aembit’s MCP Authorization Server supports Dynamic Client Registration (DCR) as defined in RFC 7591, allowing MCP clients to register automatically without pre-configuration.

Client registration requirements

When implementing DCR in your MCP client:

Requirement	Value
Grant Type	authorization_code (required)
Response Type	code (required)
Authentication Method	private_key_jwt (recommended)
Proof Key for Code Exchange (PKCE)	Required per MCP specification

Registration behavior

• Automatic registration: Clients can self-register on first connection
• Standards compliance: Follows RFC 7591 Dynamic Client Registration specification
• Unique credentials: Each client receives a unique client_id
• Redirect URI matching: Exact match required (port ignored for localhost per MCP spec)

Implementation notes

Ensure your MCP client library supports DCR. The client must:

1. Discover the registration_endpoint from the OAuth/OIDC metadata document (exposed at /.well-known/openid-configuration)
2. Send a POST request with redirect_uris, grant_types, and response_types
3. Store the returned client_id for subsequent requests
4. Include PKCE (code_challenge and code_challenge_method) in authorization requests

Access token information

Aembit’s MCP Authorization Server issues standard OAuth 2.1 JWT access tokens for use with MCP resource servers.

Token validation for resource servers

MCP resource servers validate access tokens using standard OAuth practices:

Validation Step	Description
Signature verification	Verify using the Authorization Server’s public key from JWKS endpoint
Issuer (iss)	Confirm matches your expected Authorization Server (uses .id. subdomain)
Audience (aud)	Confirm matches your resource server URL
Expiration (exp)	Confirm token hasn’t expired
Scope	Confirm token includes required scopes for the request

Standard claims

Tokens issued by the MCP Authorization Server include these standard claims:

Claim	Description
iss	Token issuer - your Aembit tenant’s .id. subdomain
aud	Intended audience - your MCP resource server URL
sub	Authenticated user identifier from the identity provider
scope	Authorized scopes for the request
exp	Token expiration timestamp
iat	Token issuance timestamp

JWKS endpoint

Token validation keys are available at:

https://[tenant].mcp.[region].aembit.io/.well-known/openid-configuration/jwks

Resource servers should cache JWKS responses and refresh periodically per standard OAuth practices. Resource servers should obtain this from the jwks_uri field in the discovery document.

Token and policy behavior

Token validation

MCP servers validate tokens using these configurable claims:

• aud (audience)
• iss (issuer)
• sub (subject)

Token lifetime is configurable on the MCP server side.

Token algorithm

Aembit supports two signing algorithms for access tokens:

• ES256 - ECDSA with P-256 and SHA-256
• RSA - RSA signatures

Algorithm selection

Aembit typically uses ES256 by default and supports RSA-based algorithms, as configured in your Credential Provider.

Configure your MCP server’s JWT verifier to match the algorithm in your Credential Provider settings:

token_verifier = JWTVerifier(
    # ... other configuration
    algorithm="ES256",  # or "RS256" if using RSA
)

Access Policy matching

For local IP addresses (such as localhost or 127.0.0.1) in redirect URIs, the MCP Authorization Server ignores the port during 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 matching. This behavior follows the MCP specification.

User experience

Typically, you’ll see an IdP selection screen (if you configure multiple IdPs) and, in error cases, an error screen. The rest of the flow is automatic from the MCP client’s perspective. All other steps occur automatically.

For details on the user experience and IdP selection with multiple identity providers, see MCP Authorization Server overview.

API protection

The access token issued by the MCP Authorization Server protects all API requests to the MCP server.

Observability

Aembit’s MCP Authorization Server uses the same observability and audit pipeline as the rest of Aembit Cloud. It doesn’t expose a separate logging API or custom metrics surface.

MCP-related activity appears in existing Aembit observability features as:

• Workload Events - show authentication and authorization activity for MCP client and server workloads.
• Access Policy evaluations - including Access Condition failures that block MCP requests.
• Credential Provider usage - token issuance and validation behavior associated with MCP flows.

You can view and export this data using Aembit’s standard tools:

• Admin Dashboard - for interactive inspection and high-level trends.
• Log Streams - for exporting detailed event and audit data to external systems (for example, SIEM or object storage).

Aembit records and surfaces MCP Authorization Server traffic like other Aembit workload activity.

Related resources

• MCP specification (version 2025-06-18)
• MCP Authorization Server overview
• Set up the MCP Authorization Server