> Markdown version of https://authpi.com/docs/guides/mcp-authorization/ — fetch the complete AuthPI docs index at https://authpi.com/llms.txt to discover all available pages.

# Secure your MCP server with AuthPI

Enable CIMD and configure your MCP resource URL and allowed scopes on your own AuthPI issuer through the console.

Use **your AuthPI issuer** to sign users in to **your MCP server**. In the console, enable CIMD and register the MCP resource URL with its allowed scopes. Enabling CIMD alone is not enough: the issuer must also permit the resource requested by the MCP client.

AuthPI hosts independent issuers for many customers. Select the issuer that owns your application's users; do not copy AuthPI's own sign-in issuer or hosted administration MCP URL. To inspect your AuthPI account instead, see [AuthPI account via MCP](/docs/guides/authpi-mcp/).

## Before you start

- Select your account and issuer in the console. You need issuer write access; suspended issuers cannot be configured.
- Have an HTTPS MCP server that supports OAuth authorization and a user who can sign in through your issuer.
- Use an MCP application that supports CIMD. A client that only supports Dynamic Client Registration cannot use this flow. See [client registration options](/docs/concepts/clients/#registered-clients-cimd-and-dynamic-registration).
- Identify the exact resource URL your server advertises and the scopes it needs. This example uses `https://mcp.example.com/mcp` and `openid` plus an application-defined `documents:read` scope. Replace them with your server's values.

## 1. Enable CIMD on your issuer

1. Open your issuer's **Settings** and select **Access**.
2. Find **Client ID Metadata Documents (CIMD)**.
3. Turn on **Enable CIMD** and wait for the save to finish.

The connecting application supplies its HTTPS metadata document as its OAuth client ID. You do not create a registered Client resource for each CIMD application. For organization-aware MCP servers, choose **All organizations** under **Organization access for CIMD clients** to include the user's active memberships. This is the default for new issuers; existing issuers retain their saved choice. Sign in again after changing it. Choose **No organizations** if your server does not need memberships, or see the [CIMD reference](/docs/reference/oidc/#client-id-metadata-documents) for selection-based access.

## 2. Add your MCP resource and scopes

On the same **Access** tab:

1. Under **Protected resources**, choose **Add resource**.
2. In **Resource URL**, enter `https://mcp.example.com/mcp`, replaced with your server's exact resource identifier.
3. Keep the prefilled `openid` scope if your client uses OpenID Connect. You can edit or remove it.
4. Choose **Add scope** and enter `documents:read`, replaced with your application's scope.
5. Choose **Save resources**. Reload the page and confirm that the URL and both scopes remain.

The resource URL identifies the protected MCP server. It is not the OAuth callback URL or the issuer URL. Copy it exactly: a different path or trailing slash is a different resource.

Every effective scope in the request must be allowed for the resource. If your client also requests `email`, `profile`, `address`, `phone`, or `offline_access`, either add the scopes your application intends to support or adjust the client to request fewer. An entry containing only `openid` and `documents:read` will not permit a request that also asks for `profile`. These are permitted token scopes; your MCP server still enforces access to each tool and its data.

Resource edits remain drafts until you choose **Save resources**. The button stays visible and is disabled when there are no changes. To change an existing entry, edit its URL or scope list and save. To remove one, choose its **Remove** button and save. **Discard** restores the saved list. Other listed resources are included in the save. The editor leaves the issuer-wide `required` and `allow_multiple` settings unchanged; see [resource policy](/docs/reference/oidc/#issuer-and-client-policy) before changing those through the API.

Your draft survives switching between settings tabs for the same issuer. If another operator changes the issuer before your save, the console rejects an outdated update and keeps your draft. Copy any edits you need, then choose **Discard** to load the latest resource list, reapply your changes, and save again.

## 3. Point your MCP server at your issuer

Configure your MCP server's OAuth support with the same resource URL, your issuer's full URL, and the scopes from step 2. Its protected-resource metadata should identify those values. For example, replacing `YOUR_ISSUER_ID` with your issuer ID:

```json
{
  "resource": "https://mcp.example.com/mcp",
  "authorization_servers": ["https://idp.authpi.com/YOUR_ISSUER_ID"],
  "scopes_supported": ["openid", "documents:read"],
  "bearer_methods_supported": ["header"]
}
```

Serve the metadata at a discoverable location such as `https://mcp.example.com/.well-known/oauth-protected-resource`, and point unauthenticated requests to it through the server's `WWW-Authenticate` challenge. Your MCP framework may handle this. Follow the [MCP authorization specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) for discovery and token handling.

Configure token verification in your server for **your issuer** and **your exact MCP audience**. Verify signatures and token validity, then enforce the granted scopes and your application's user or organization access rules. See [Validate access tokens](/docs/guides/validate-tokens/) and [token claims](/docs/reference/token-claims/). Do not accept a token simply because another AuthPI issuer signed it.

## 4. Connect and verify

1. Add your MCP URL to the connecting application and start a fresh authorization flow.
2. Confirm the sign-in page belongs to your issuer and sign in as one of your application's users.
3. Review and approve the requested resource and scopes.
4. Call a permitted tool and confirm the server accepts the token for your MCP resource.

For CIMD discovery, your issuer's OpenID configuration should advertise `client_id_metadata_document_supported: true`. Check it at `https://idp.authpi.com/YOUR_ISSUER_ID/.well-known/openid-configuration`, using your issuer's actual URL. Your server's metadata and the client's OAuth `resource` parameter must agree with the resource saved in the console.

If authorization returns `invalid_target`, check the exact resource URL and **all** requested scopes in **Protected resources** first. CIMD being enabled does not bypass either check. A registered OAuth client additionally needs the resource in its own `settings.openid.allowed_resources` and permission for the requested application scopes in `settings.scopes`; see [issuer and client policy](/docs/reference/oidc/#issuer-and-client-policy).

If the failure says the callback is not registered, it concerns the client's redirect URI, not the MCP resource URL. For CIMD, check the connecting application's metadata document against the [callback rules](/docs/reference/oidc/#client-id-metadata-documents).

## Optional: call another API for the user

Your MCP server can validate its own access token and serve its tools without token exchange. If it must call a **different API** on the user's behalf, follow [MCP token exchange](/docs/guides/mcp-token-exchange/). That separate flow introduces a confidential backend client and a token intended for the target API; it does not replace the MCP authorization setup above.