MCP Server Trigger

Learn more about the MCP Server Trigger and how to use it on the Digibee Integration Platform.

Overview

The MCP Server Trigger is a trigger that allows a Digibee pipeline to receive and process requests coming from an MCP (Model Context Protocol) client.

It acts as the entry point for events or actions initiated by external tools connected through the MCP protocol, for example, tools used by AI assistants or automation services that communicate with Digibee.

What it’s used for

It’s used when you want to:

• Enable AI or external services (like an MCP-compliant assistant) to run an action, get more context or interact with a Digibee pipeline.

• Enforce business playbooks and processes to make your Agent smarter

  • Agents struggle with unstructured guidance. Digibee ensures correct step-by-step execution.

• Make sure your Agent Adhere to business rules and policies

  • You can externalize your rules into MCP pipelines. It'll guarantee deterministic and auditable decisions.

How it works

1. The MCP client sends a request that matches the trigger configuration.

2. The MCP Server Trigger starts the pipeline and provides the input payload.

3. The pipeline executes its logic (transformations, integrations, and so on).

4. The result is encapsulated in a content object, as required by the official MCP protocol. This ensures that the AI ​​agent receives the information in the expected text or image format.

AI-assisted fields

Fields marked with in this documentation support AI-assisted content generation. In the platform, these fields display a sparkle button () in the upper-right corner. Use it to generate or edit field content from a plain-language description, without having to write it manually.

To use the assistant:

1. Click the sparkle icon (). A panel opens where you can describe what you need.

2. Enter your description and click Generate.

3. When generation is complete, you can choose one of the following options:

   1. Apply: Replaces the current field content with the generated result.

   2. Try again: Returns to the prompt to repeat the same description or test a new one.

   3. Cancel: Discards the result and keeps the current field content.

Applying a generated result overwrites whatever is currently in the field.

Tools configuration

To start configuring the trigger, you must add tools. Each tool exposed by an MCP server includes a set of core fields that define its identity, purpose, permissions, and data structure.

Adding a new tool

1. Go to the MCP Server Tools section.

2. Click Add Tools.

3. Fill in the fields described below.

4. After saving, the tool will appear in the Tools List, where you can add, edit, or delete entries.

Tool fields

Tool Name

Unique identifier for the tool. It should be concise, descriptive, and typically use snake_case.

Example: search_web

Description

Short and clear summary of what the tool does. Helps both the model and users understand its purpose.

Example: Performs a web search and returns the top results.

Scopes

Defines the permissions this tool requires at runtime. Scopes are embedded in the scoped JWT token when an agent invokes this tool. This field is optional. Type a scope and press Enter or Tab to add it as a tag.

Example: read:web, write:logs

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.

Schema Configuration

You can define how your tool handles both input and output data using JSON Schemas. These schemas describe the expected structure, data types, and validation rules.

The configuration applies to two sections:

• Input Schema: Defines the structure of the data received by the tool.

• Output Schema: (Optional) Defines the structure of the data returned by the tool.

Both can be configured in two ways:

Option 1: Wizard

Use the Wizard to guide your configuration by clicking Add Property and filling in the parameters:

• Name: Defines the property name within the JSON object.

• Type: Specifies the data type (string, number, boolean, array, or object).

• Required: Indicates whether the field is mandatory.

• Description: Describes the purpose or meaning of the property.

• Enum Values: (Applicable only to the string type) Lists the allowed values for the property.

• Array Type: (Applicable only to the array type) Defines the data type of the array elements (string, number, boolean, or array).

• Object Properties: (Applicable only to the object type) Defines the set of properties contained within the object.

Example: Input Schema

Name	Type	Required	Description	Enum Values
query	string	Yes	The search term or keywords to look up.	—
limit	number	No	Number of results to return.	N/A

Resulting JSON Schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "The search term or keywords to look up."
    },
    "limit": {
      "type": "integer",
      "description": "Number of results to return.",
      "default": 5
    }
  },
  "required": ["query"]
}

Example: Output Schema

Name	Type	Required	Description	Array Type
results	array	No	List of URLs matching the search query.	string

Resulting JSON Schema

{
  "type": "object",
  "properties": {
    "results": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "List of URLs matching the search query."
    }
  }
}

Option 2: Schema

Alternatively, enter the JSON Schema directly in the provided field.

Parameters configuration

Parameter	Description	Data type	Default value
Server Name	Name of the MCP server. This is for reference purposes only.	String	N/A
Description	Short description for identifying the MCP Server.	String	N/A
Maximum Timeout	Maximum time (in milliseconds) for the pipeline to process information before returning a response. Limit: 900000 ms.	Integer	90000
The Maximum Allowed Request Size In Mb	Maximum size of the payload in megabytes. The maximum configurable size is 5 MB.	Integer	5
External API	If enabled, the MCP Server becomes accessible through Digibee’s external gateway, allowing it to communicate over the public Internet.	Boolean	true
Internal API	If enabled, exposes the MCP Server through Digibee’s internal gateway, restricting access to the internal network only. Both the External API and Internal API options can be active simultaneously.	Boolean	false
API Key	If enabled, the endpoint can only be accessed with an API key configured in the Digibee Integration Platform.	Boolean	false
External JWT	If enabled, the MCP Server validates JWT tokens from external identity providers (for example, Auth0, Azure AD, Okta) received via the externalJWT header.	Boolean	false
Public Key	The external provider's public key. It is used to validate the token signature.	String	N/A
JSW Algorithm (JWA)	Specifies the encryption algorithm used to validate the digital signature of the JWT token.	String	ES256
OAuth2 JWT	If enabled, the MCP Server validates access tokens using OAuth 2.0 with JWT. For setup instructions, see How to configure OAuth 2.0 on the MCP Server Trigger.	Boolean	false
OAuth2 Authorization Server	URL of the OAuth 2.0 authorization server used to validate incoming tokens (for example, https://your-auth-server.example.com). Only available when OAuth2 JWT is enabled.	String	N/A
Validate OAuth2 Audience	If enabled, rejects tokens whose aud claim does not match the MCP resource URL. Only available when OAuth2 JWT is enabled.	Boolean	true
Documentation	Optional field to describe the trigger configuration and any relevant business rules.	String	N/A

Visual representation of the tools

After saving the trigger configuration, a visual representation of the tools is displayed in the pipeline.

Tools can only be edited through the trigger's configuration form. Any changes made are immediately reflected in the pipeline after saving.

Each tool is connected to a Block Execution connector. This connector is designed to logically separate the integration into different subflows, making pipeline management easier. To complete the configuration, you must create the flows for each route within the OnProcess and OnException subflows.

Regardless of the number of tools configured, there is always a default route for cases where a tool is not found. You can configure this route to handle missing tools appropriately.

Important notes:

• If you create the flow before configuring the trigger, existing connectors will be disconnected once the trigger is saved.

• Deleting a tool from the Tools List will disconnect the corresponding Block Execution connector from the main flow.

Payload templates for the MCP Server Trigger

The MCP Server Trigger includes built-in test options that automatically add a payload to the Execution Panel, making it easier to test your tools. You can either list all available tools at once or execute them individually.

Tools can be tested only after the trigger is saved. If you add, rename, or remove a tool, you must save the trigger before listing all available tools or executing a tool individually.

List all available tools

Click Test Tools List to list all tools available on the MCP Server Trigger. The following payload will be added to the Execution Panel. Click Play to execute it:

{
  "tool": "tools/list",
  "arguments": {}
}

"tool": "tools/list" is a permanent identifier for this operation. The arguments field is mandatory, even when empty.

Execute a tool

To test a tool individually, click the three-dot icon next to the tool and select Test Tool in the trigger configuration panel. The following payload will be added to the Execution Panel, pre-filled with the tool's input parameters:

{
  "tool": "<TOOL_NAME>",
  "arguments": {
    "<param1>": "",
    "<param2>": ""
  },
  "headers": {},
  "userAgent": "<Agent identifier>"
}

Payload fields

Field	Type	Required	Description
tool	string	Yes	Name of the tool to execute.
arguments	object	Yes	Input payload for the tool. Must follow the schema defined for that specific tool.
headers	object	No	Additional headers for the execution, such as custom authentication.
userAgent	string	No	Identifier of the caller agent, useful for tracing and observability.

Practical example

For example, if you have a tool named search_web with a query parameter, its generated template will be:

{
  "operation": "tools/call",
  "tool": "search_web",
  "arguments": {
    "query": ""
  },
  "headers": {},
  "userAgent": "Digibee Execution Panel"
}