# Troubleshoot the MCP Authorization Server

> Common errors and solutions when configuring the Aembit MCP Authorization Server.

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

> **Event-based troubleshooting**
>
> For runtime failures that surface as generic errors in the MCP client start with [Troubleshoot MCP and AI IAM access](/user-guide/troubleshooting/mcp-ai-iam/). That guide walks through Access Authorization Events, Workload Events, and MCP Authorization Tracing in order.
>
> Use this page for configuration-time errors visible to the MCP client during setup.

## Quick reference

| Error                               | Jump to                                                                             |
| ----------------------------------- | ----------------------------------------------------------------------------------- |
| `redirect_uri mismatch`             | [Redirect URI mismatch](#redirect-uri-mismatch)                                     |
| `Protected resource does not match` | [Resource URL mismatch](#resource-url-mismatch)                                     |
| `No Identity Providers Available`   | [No identity providers available](#no-identity-providers-available)                 |
| `scope is required`                 | [Missing scope parameter](#missing-scope-parameter)                                 |
| `Backend debug proxy error`         | [MCPJam backend proxy error](#mcpjam-backend-proxy-error)                           |
| `invalid_client_metadata`           | [Client registration failures](#client-registration-failures)                       |
| `code_verifier doesn't match`       | [Proof Key for Code Exchange (PKCE) validation failures](#pkce-validation-failures) |
| `No matching Access Policy found`   | [Access Policy not found](#access-policy-not-found)                                 |
| `Token exchange failed`             | [Token exchange failures](#token-exchange-failures)                                 |
| `JWT signature verification failed` | [Key authentication failures](#key-authentication-failures)                         |
| `Required SAML attribute not found` | [SAML attribute mapping errors](#saml-attribute-mapping-errors)                     |
| `Failed to parse SAML metadata`     | [SAML metadata errors](#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:**

```text
Error: redirect_uri mismatch
```

**Cause:** The redirect URI registered in your Aembit Client Workload 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:**

```text
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](/ai-guide/mcp/authorization-server/concepts-mcp-auth-server/#url-configuration-alignment) for details

## No identity providers available

**Error:**

```text
No Identity Providers Available
```

**Cause:** The Access Policy's Trust Provider 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:**

```json
{"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:**

```text
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:**

```text
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:**

```text
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:**

```text
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:**

```text
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:**

```text
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:**

```text
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:**

```text
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](/ai-guide/mcp/authorization-server/)
* [Set up the MCP Authorization Server](/ai-guide/mcp/authorization-server/setup-mcp-auth-server/)
* [MCP Authorization Server reference](/ai-guide/mcp/authorization-server/reference-mcp-auth-server/)