Troubleshoot the MCP Authorization Server

This guide covers common errors you may encounter when setting up or using the Aembit Model Context Protocol (MCP) Authorization Server.

Quick reference

Error	Jump to
redirect_uri mismatch	Redirect URI mismatch
Protected resource does not match	Resource URL mismatch
No Identity Providers Available	No identity providers available
scope is required	Missing scope parameter
Backend debug proxy error	MCPJam backend proxy error
invalid_client_metadata	Client registration failures
code_verifier doesn't match	Proof Key for Code Exchange (PKCE) validation failures
No matching Access Policy found	Access Policy not found
Token exchange failed	Token exchange failures
JWT signature verification failed	Key authentication failures
Required SAML attribute not found	SAML attribute mapping errors
Failed to parse SAML metadata	SAML metadata errors

URL mismatch errors

URL mismatches are among the most common configuration issues. Three URLs must align for the MCP authorization flow to succeed.

Redirect URI mismatch

Error:

Error: redirect_uri mismatch

Cause: The redirect URI registered in your Aembit 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 doesn’t match the callback URL your MCP client uses.

Resolution:

1. Check your Client Workload configuration in Aembit
2. Verify the redirect URI matches your MCP client’s callback URL exactly
3. For local development, ensure you’re consistent with localhost vs 127.0.0.1

Resource URL mismatch

Error:

Error: Protected resource http://server-a:8080/mcp does not match expected http://server-b:8080/mcp (or origin)

Cause: The URL your MCP client connects to doesn’t match the resource server URL configured in your MCP server.

Resolution:

1. Check your MCP server’s resource server URL configuration
2. Ensure your MCP client connects to the exact same URL
3. See URL configuration alignment for details

No identity providers available

Error:

No Identity Providers Available

Cause: The Access Policy'sAccess 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 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 doesn’t have an associated identity provider configured.

Resolution:

1. Verify your Access Policy includes a Trust Provider
2. Ensure the Trust Provider is an OIDC ID Token Trust Provider
3. Confirm the Trust Provider has an identity provider (IdP) linked to it
4. Check that the IdP is correctly configured with your OIDC provider (Azure AD, Okta, Google, etc.)

Missing scope parameter

Error:

{"StatusCode":400,"Error":"scope is required","Custom":{}}

Cause: The MCP client didn’t send a scope parameter during the OAuth flow. This typically indicates a Trust Provider configuration issue.

Resolution:

1. Verify you configured a Trust Provider and added it to your Access Policy
2. Check that you correctly configured the Trust Provider for OIDC ID Token authentication
3. Ensure the Trust Provider’s IdP settings match your identity provider

Active development

This is an area of active development. Contact Aembit support if the issue persists after verifying Trust Provider configuration.

MCPJam backend proxy error

Error:

Backend debug proxy error: 500 Internal Server Error

Cause: MCPJam uses a backend proxy server to fetch OAuth metadata. If your MCP server’s firewall only allows specific IP addresses, your firewall blocks MCPJam’s proxy servers.

Resolution:

1. Open your firewall to allow MCPJam’s proxy IP ranges
2. Or use a different MCP client that performs OAuth entirely in the browser

MCPJam limitation

This limitation only affects MCPJam when connecting to remote MCP servers with restricted network access. Local development typically doesn’t encounter this issue.

Dynamic client registration issues

Client registration failures

Error:

Error: invalid_client_metadata

Cause: The MCP client’s registration request is missing required fields or contains invalid values.

Resolution:

1. Verify your Dynamic Client Registration (DCR) request includes authorization_code in grant_types
2. Verify your DCR request includes code in response_types
3. Check that redirect_uris contains valid, correctly formatted URLs
4. Ensure redirect URIs match exactly with your Client Workload configuration

PKCE validation failures

Error:

Error: invalid_grant - code_verifier doesn't match code_challenge

Cause: The PKCE code verifier doesn’t match the code challenge sent during authorization.

Resolution:

1. Verify your client generates a proper code_challenge from the code_verifier
2. Ensure code_challenge_method is set to S256
3. Check for URL encoding issues in code values
4. Confirm the same code_verifier is used throughout the flow

Policy evaluation errors

Access Policy not found

Error:

Error: No matching Access Policy found

Cause: No Access Policy matches the combination of Client Workload (redirect URI) and Server Workload for this request.

Resolution:

1. Verify you have an Access Policy that connects your Client Workload to your Server Workload
2. Check that the redirect URI in your Client Workload matches the MCP client’s registered redirect URI
3. Confirm the Server Workload’s host, port, and path match your MCP server configuration
4. Ensure the Access Policy is active (not turned off)

Token exchange failures

Error:

Error: Token exchange failed

Cause: The client failed to exchange the authorization code for an access token.

Resolution:

1. Verify the authorization code hasn’t expired (codes are short-lived)
2. Check that the code_verifier matches the code_challenge from the authorization request
3. Confirm the redirect URI in the token request matches the one used in authorization
4. Review the Credential Provider configuration for your Access Policy

Identity provider issues

Key authentication failures

Error:

Error: invalid_client - JWT signature verification failed

Cause: Public/private key mismatch between your identity provider and Aembit configuration.

Resolution:

1. Verify the public key uploaded to your IdP matches the private key configured in Aembit
2. Check the key format (PEM or JWKS)
3. Ensure the key ID (kid) matches between systems
4. Test the key pair independently using a JWT library

SAML attribute mapping errors

Error:

Error: Required SAML attribute not found

Cause: Your SAML Identity Provider isn’t returning the required user attributes in the SAML assertion.

Resolution:

1. Verify your SAML Trust Provider configuration includes the correct attribute mappings
2. Check your IdP’s attribute release policy to ensure it sends required attributes
3. Confirm the attribute names match between your IdP configuration and Aembit Trust Provider
4. Test the SAML assertion using your IdP’s testing tools to verify attribute contents

SAML metadata errors

Error:

Error: Failed to parse SAML metadata

Cause: The SAML metadata URL is inaccessible or the metadata format is invalid.

Resolution:

1. Verify the metadata URL is accessible from Aembit’s servers
2. Check that the metadata XML is valid and well-formed
3. If using a metadata file, ensure you exported it correctly from your IdP
4. Verify your IdP’s signing certificate hasn’t expired

Related resources

• MCP Authorization Server overview
• Set up the MCP Authorization Server
• MCP Authorization Server reference