> For the complete documentation index, see [llms.txt](https://docs.digibee.com/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digibee.com/documentation/connectors-and-triggers/triggers/web-protocols/mcp-server/how-to-configure-oauth-2.0-on-the-mcp-server-trigger.md).

# How to configure OAuth 2.0 on the MCP Server Trigger

The **MCP Server Trigger** supports the authorization flow defined by OAuth 2.1, with PKCE (Proof Key for Code Exchange), the recommended standard for MCP servers with HTTP transport. With OAuth, before accessing any resource, the client needs to prove that the user has authorized access, through a token issued by a trusted authorization server.

OAuth authorization is recommended when your MCP server accesses user data, performs administrative actions, or operates in corporate environments with strict access controls.

## **Before you begin**

Before configuring OAuth 2.0 on the MCP Server Trigger, make sure you have:

* An OAuth 2.1-compliant authorization server already configured (for example, Auth0, Azure AD, or Okta)
* The authorization server's metadata URL or discovery endpoint
* The scopes your tools will require, defined in your authorization server

## **How the OAuth 2.0 flow works**

OAuth 2.0 protects your pipeline by requiring every client to prove it has been authorized before accessing any tool. Without a valid token, the MCP Server Trigger rejects the request. The flow below describes how a client obtains and uses that token.

1. An MCP client sends a request to the pipeline without an access token.
2. The MCP Server Trigger responds with HTTP 401 Unauthorized, including a header that points to the Protected Resource Metadata document.
3. The client fetches the metadata document and discovers the authorization server location.
4. The client completes the OAuth 2.1 authorization flow with the authorization server, obtaining an access token.
5. The client retries the request, this time including the access token in the Authorization: Bearer \<token> header.
6. The MCP Server Trigger validates the token and, if valid, processes the request.

{% hint style="info" %}
Every HTTP request from client to server must include the Authorization header, even if the requests are part of the same session.
{% endhint %}

## **Step-by-step guide**

{% stepper %}
{% step %}

### **Configure your authorization server**

Your authorization server must expose the OAuth 2.0 metadata endpoints that the MCP client will use for discovery. It must provide either:

* OAuth 2.0 Authorization Server Metadata at `/.well-known/oauth-authorization-server`
* OpenID Connect Discovery at `/.well-known/openid-configuration`

In addition, the authorization server must:

* Support PKCE (Proof Key for Code Exchange) with the S256 challenge method
* Include `code_challenge_methods_supported` in its metadata response
* Support the resource parameter (Resource Indicators for OAuth 2.0, defined in [RFC 8707](https://www.rfc-editor.org/rfc/rfc8707.html))
* Issue short-lived access tokens to reduce the impact of token leakage

The resource parameter scopes the token to your specific MCP Server Trigger endpoint, for example `https://your-pipeline.digibee.io/mcp`. This prevents tokens issued for your pipeline from being reused in other services.

**Example authorization server metadata (OAuth 2.0 Authorization Server Metadata format)**

```json
{
  "issuer": "https://your-auth-server.example.com",
  "authorization_endpoint": "https://your-auth-server.example.com/authorize",
  "token_endpoint": "https://your-auth-server.example.com/token",
  "jwks_uri": "https://your-auth-server.example.com/.well-known/jwks.json",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "scopes_supported": ["read:customers", "write:orders", "read:reports"],
  "client_id_metadata_document_supported": true
}
```

{% endstep %}

{% step %}

### **Register your MCP client**

MCP clients must be registered with your authorization server before they can obtain tokens. Digibee supports three registration approaches:

#### **Client ID Metadata Documents**

The client uses an HTTPS URL as its `client_id`. That URL must point to a JSON document containing the client's metadata. This is the recommended approach for clients with no prior relationship to the authorization server.

**Requirements for the metadata document:**

* Hosted at an HTTPS URL
* Contains `client_id`, `client_name`, and `redirect_uris`
* The `client_id` value must match the document URL exactly

**Example metadata document:**

```json
{
  "client_id": "https://app.example.com/oauth/client-metadata.json",
  "client_name": "My MCP Client",
  "redirect_uris": ["http://localhost:3000/callback"],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}
```

Your authorization server must include `"client_id_metadata_document_supported": true` in its metadata to advertise support for this approach.

#### **Pre-Registration**

The client and server have an existing relationship. The client uses a static `client_id` (and, when applicable, static credentials) obtained through a prior registration process, for example through a configuration interface provided by your authorization server.

#### **Dynamic Client Registration**

The client registers itself programmatically at the authorization server's registration endpoint using the [OAuth 2.0 Dynamic Client Registration Protocol (RFC 7591)](https://datatracker.ietf.org/doc/html/rfc7591). This approach is included for backward compatibility.

```json
POST /register HTTP/1.1
Host: your-auth-server.example.com
Content-Type: application/json

{
  "client_name": "My MCP Client",
  "redirect_uris": ["http://localhost:3000/callback"],
  "grant_types": ["authorization_code"],
  "response_types": ["code"]
}
```

{% endstep %}

{% step %}

### **Enable OAuth 2.0 on the trigger**

1. Open the pipeline containing the MCP Server Trigger and click the trigger.
2. Enable the **OAuth2 JWT** toggle.
3. In the **OAuth2 Authorization Server** field, enter the URL of your authorization server (for example, `https://your-auth-server.example.com`).
4. Click **Save**.

After saving, test the configuration by sending an unauthenticated request to the trigger endpoint. You should receive a 401 response with the WWW-Authenticate header containing the `resource_metadata` URL.
{% endstep %}

{% step %}

### **Configure tools with scopes**

With OAuth 2.0 enabled, define the scopes each tool requires. Scopes are embedded in the JWT token when an agent invokes a tool and enable fine-grained permission enforcement as part of the trigger flow.

1. Open the MCP Server Trigger configuration.
2. In the **MCP Server Tools** section, click the tool you want to configure (or click **Add Tools** to create a new one).
3. In the **Scopes** field, type the scope and press **Enter** or **Tab** to add it as a tag.
4. Repeat for each scope the tool requires.
5. Click **Save**.

**Example scopes:**

| Tool              | Scopes                        |
| ----------------- | ----------------------------- |
| `search_customer` | `read:customers`              |
| `update_order`    | `read:orders`, `write:orders` |
| `generate_report` | `read:reports`                |

{% hint style="warning" %}
Pipelines created before the January 27, 2026 release that use the MCP Server Trigger must be reconfigured due to the addition of Scopes. Open the trigger configuration and click **Save** again. For security, we recommend generating a copy of your **Block Executions** before performing this update.
{% endhint %}
{% endstep %}
{% endstepper %}

## **Connecting MCP clients**

The following clients are validated to work with the MCP Server Trigger OAuth 2.0 flow.

**Claude Desktop**

1. Open the Claude Desktop configuration file (`claude_desktop_config.json`).
2. Add the MCP server entry with your pipeline URL as the endpoint:

```json
{
  "mcpServers": {
    "my-digibee-pipeline": {
      "url": "https://your-pipeline.digibee.io/mcp",
      "authorizationUrl": "https://your-auth-server.example.com"
    }
  }
}
```

3. Restart Claude Desktop. On the next connection attempt, it will initiate the OAuth 2.0 flow and open a browser window for authentication.

**Cursor**

1. Go to **Settings > MCP Servers** in Cursor.
2. Add a new server with your pipeline endpoint and the authorization server URL.
3. Cursor will handle the OAuth 2.0 flow automatically on first connection.

**OpenAI Agent Builder**

1. In your agent configuration, add the MCP server URL pointing to your Digibee pipeline.
2. Set the authentication method to **OAuth 2.0** and provide the authorization server metadata URL.
3. The Agent Builder will fetch the server metadata and complete the authorization flow before making tool calls.

## **Token validation and error handling**

The MCP Server Trigger validates every incoming access token before processing the request. Validation includes:

* Checking the token signature against the authorization server's public keys
* Verifying the token audience matches the MCP Server Trigger's canonical URI
* Confirming the token has not expired

If validation fails, the trigger returns the appropriate HTTP error:

| Status code      | Description                        | When it occurs                                        |
| ---------------- | ---------------------------------- | ----------------------------------------------------- |
| 401 Unauthorized | Token missing, expired, or invalid | No token sent, or token fails validation              |
| 403 Forbidden    | Insufficient permissions           | Token is valid but lacks required scopes for the tool |
| 400 Bad Request  | Malformed request                  | Authorization request is incorrectly formed           |

#### **Handling insufficient scope errors**

If an MCP client sends a valid token but the token does not include the scopes required by the tool being called, the pipeline returns a JSON-RPC error:

```json
{
  "jsonrpc": "2.0",
  "id": "2",
  "error": {
    "code": -32001,
    "message": "Permission denied. Token does not have the required scope for this tool."
  }
}
```

MCP clients should respond to this error by initiating a step-up authorization flow: requesting a new token that includes the additional scopes, then retrying the original request.

{% hint style="warning" %}
MCP clients must implement retry limits for step-up authorization flows. Repeated failures for the same resource and scope combination should be treated as a permanent authorization failure and surfaced to the user.
{% endhint %}

## **Best security practices**

When deploying OAuth 2.0 with the MCP Server Trigger, follow these practices:

* **Use HTTPS everywhere.** All authorization server endpoints and redirect URIs must use HTTPS. The only exception is localhost URIs used during local development.
* **Validate token audience.** The trigger validates that access tokens were issued specifically for your pipeline's canonical URI. Do not reuse tokens across different services.
* **Do not pass through tokens.** If your pipeline calls upstream APIs, obtain a separate token for each upstream service. Never forward the token received from the MCP client.
* **Use short-lived tokens.** Configure your authorization server to issue short-lived access tokens. For public clients, enable refresh token rotation.
* **Apply least privilege.** Define scopes at the tool level and request only the scopes each tool actually needs.

## **Next steps**

Now that your MCP Server Trigger is secured with OAuth 2.0, read [MCP Server Trigger](/documentation/connectors-and-triggers/triggers/web-protocols/mcp-server.md) to review the full trigger configuration reference, including tool schema setup and payload templates for testing.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.digibee.com/documentation/connectors-and-triggers/triggers/web-protocols/mcp-server/how-to-configure-oauth-2.0-on-the-mcp-server-trigger.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.