> 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.md).

# MCP Server Trigger

## **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 <i class="fa-sparkles">:sparkles:</i> in this documentation support AI-assisted content generation. In the platform, these fields display a sparkle button (<i class="fa-sparkles">:sparkles:</i>) 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 (<i class="fa-sparkles">:sparkles:</i>). 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.

{% hint style="warning" %}
Applying a generated result overwrites whatever is currently in the field.
{% endhint %}

<figure><img src="/files/ImN1GVVvS7B5CFcH5hK7" alt=""><figcaption></figcaption></figure>

## **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** <i class="fa-sparkles">:sparkles:</i>

Unique identifier for the tool. It should be concise, descriptive, and typically use snake\_case.

**Example:** `search_web`

#### **Description** <i class="fa-sparkles">:sparkles:</i>

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`

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

#### **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**

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

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

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

## **Visual representation of the tools**

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

<figure><img src="/files/afBE0RYrI9Q9sMg8g1xQ" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Tools can only be edited through the trigger's configuration form. Any changes made are immediately reflected in the pipeline after saving.
{% endhint %}

Each tool is connected to a [**Block Execution**](/documentation/connectors-and-triggers/connectors/logic/block-execution.md) 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](/documentation/developer-guide/development-cycle/build-overview/pipelines/subpipelines.md).

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.

{% hint style="warning" %}
**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.
  {% endhint %}

## **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.

{% hint style="info" %}
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.
{% endhint %}

### **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:

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

{% hint style="info" %}
`"tool": "tools/list"` is a permanent identifier for this operation. The `arguments` field is mandatory, even when empty.
{% endhint %}

### **Execute a tool**

<figure><img src="/files/RV4A1WdZOcASZEWA2vUd" alt=""><figcaption></figcaption></figure>

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:

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

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

```


---

# 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.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.