How to configure OAuth 2.0 on the MCP Server Trigger

Learn how to enable and configure OAuth 2.0 authorization on the MCP Server Trigger in the Digibee Integration Platform.

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.

Every HTTP request from client to server must include the Authorization header, even if the requests are part of the same session.

Step-by-step guide

1

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)

• 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)

{
  "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
}

2

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:

{
  "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). This approach is included for backward compatibility.

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"]
}

3

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.

4

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

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.

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:

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

1. 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:

{
  "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.

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.

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 to review the full trigger configuration reference, including tool schema setup and payload templates for testing.