From 281c39b5a7bd01937d5c7c3522d2eeb979cdb9b0 Mon Sep 17 00:00:00 2001 From: williambza Date: Mon, 23 Mar 2026 11:59:08 +0200 Subject: [PATCH 1/3] Add docs for ServiceControl MCP settings --- menu/menu.yaml | 2 + .../audit-instances/configuration.md | 16 +++ servicecontrol/mcp.md | 125 ++++++++++++++++++ .../servicecontrol-instances/configuration.md | 16 +++ 4 files changed, 159 insertions(+) create mode 100644 servicecontrol/mcp.md diff --git a/menu/menu.yaml b/menu/menu.yaml index af0580c5762..3af5d37bf75 100644 --- a/menu/menu.yaml +++ b/menu/menu.yaml @@ -1677,6 +1677,8 @@ Url: servicecontrol/contracts - Title: Transport adapter Url: servicecontrol/transport-adapter + - Title: Model Context Protocol (MCP) + Url: servicecontrol/mcp - Title: MassTransit Articles: - Title: Introduction diff --git a/servicecontrol/audit-instances/configuration.md b/servicecontrol/audit-instances/configuration.md index 8bafb642732..acc5f85d62a 100644 --- a/servicecontrol/audit-instances/configuration.md +++ b/servicecontrol/audit-instances/configuration.md @@ -910,6 +910,22 @@ The ServiceControl primary instance queue name to use to send plugin messages (e | --- | --- | | string | `Particular.ServiceControl` | +## MCP + +### ServiceControl.Audit/EnableMcpServer + +Enables the [Model Context Protocol (MCP)](/servicecontrol/mcp.md) server, allowing AI-powered tools and assistants to interact with ServiceControl Audit data. + +| Context | Name | +| --- | --- | +| **Environment variable** | `SERVICECONTROL_AUDIT_ENABLEMCPSERVER` | +| **App config key** | `ServiceControl.Audit/EnableMcpServer` | +| **SCMU field** | N/A | + +| Type | Default value | +| --- | --- | +| bool | `false` | + ## Troubleshooting ### ServiceControl.Audit/DataSpaceRemainingThreshold diff --git a/servicecontrol/mcp.md b/servicecontrol/mcp.md new file mode 100644 index 00000000000..b04a5cc6f81 --- /dev/null +++ b/servicecontrol/mcp.md @@ -0,0 +1,125 @@ +--- +title: Model Context Protocol (MCP) integration +summary: Integrate AI tools with ServiceControl using the Model Context Protocol. +reviewed: 2026-03-21 +component: ServiceControl +related: +- servicecontrol/servicecontrol-instances/configuration +- servicecontrol/audit-instances/configuration +--- + +ServiceControl can expose a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server, allowing AI-powered tools and assistants to interact with failed and audit message data directly. + +When enabled, the MCP server is available at the `/mcp` path on the ServiceControl instance's HTTP endpoint. The server uses the HTTP Streamable transport and supports standard MCP tool discovery and invocation. + +## Enabling MCP + +The MCP server is disabled by default and must be enabled separately on each instance type. + +### Error instance + +See [EnableMcpServer](/servicecontrol/servicecontrol-instances/configuration.md#enablemcpserver) in the error instance configuration settings. + +### Audit instance + +See [EnableMcpServer](/servicecontrol/audit-instances/configuration.md#enablemcpserver) in the audit instance configuration settings. + +## Connecting an MCP client + +Once enabled, configure an MCP client to connect to the ServiceControl instance using the HTTP Streamable transport. For example, an error instance running on its default address would be accessible at: + +``` +http://localhost:33333/mcp +``` + +An audit instance running on its default address would be accessible at: + +``` +http://localhost:44444/mcp +``` + +The exact host and port depend on the [host settings](/servicecontrol/setting-custom-hostname.md) of each instance. + +> [!NOTE] +> When [authentication](/servicecontrol/security/configuration/authentication.md) is enabled, MCP clients must provide appropriate credentials. + +### Client configuration examples + +Most MCP clients accept a server configuration in JSON format. The following example shows how to configure a connection to a ServiceControl error instance: + +```json +{ + "mcpServers": { + "servicecontrol": { + "url": "http://localhost:33333/mcp" + }, + "servicecontrol-audit": { + "url": "http://localhost:44444/mcp" + } + } +} +``` + +## Available tools + +The MCP server exposes tools for querying and managing messages. The tools available depend on the instance type. + +### Error instance tools + +#### Failed messages + +| Tool | Description | +| --- | --- | +| `GetFailedMessages` | Get failed messages with filtering by status, modified date, and queue address | +| `GetFailedMessageById` | Get details of a specific failed message | +| `GetFailedMessageLastAttempt` | Get the last processing attempt for a failed message | +| `GetErrorsSummary` | Get error counts grouped by status | +| `GetFailedMessagesByEndpoint` | Get failed messages for a specific endpoint | + +#### Retries + +| Tool | Description | +| --- | --- | +| `RetryFailedMessage` | Retry a single failed message by sending it back to its original queue | +| `RetryFailedMessages` | Retry multiple failed messages by their IDs | +| `RetryFailedMessagesByQueue` | Retry all failed messages from a specific queue address | +| `RetryAllFailedMessages` | Retry all failed messages across all queues | +| `RetryAllFailedMessagesByEndpoint` | Retry all failed messages for a specific endpoint | +| `RetryFailureGroup` | Retry all failed messages in a failure group | + +#### Archiving + +| Tool | Description | +| --- | --- | +| `ArchiveFailedMessage` | Archive a single failed message | +| `ArchiveFailedMessages` | Archive multiple failed messages by their IDs | +| `ArchiveFailureGroup` | Archive all failed messages in a failure group | +| `UnarchiveFailedMessage` | Unarchive a single failed message back to unresolved | +| `UnarchiveFailedMessages` | Unarchive multiple failed messages by their IDs | +| `UnarchiveFailureGroup` | Unarchive all failed messages in a failure group | + +#### Failure groups + +| Tool | Description | +| --- | --- | +| `GetFailureGroups` | Get failure groups (messages grouped by exception type and stack trace) | +| `GetRetryHistory` | Get history of past retry operations and their outcomes | + +### Audit instance tools + +#### Audit messages + +| Tool | Description | +| --- | --- | +| `GetAuditMessages` | Get successfully processed audit messages with paging and sorting | +| `SearchAuditMessages` | Search audit messages by keyword across content and metadata | +| `GetAuditMessagesByEndpoint` | Get audit messages received by a specific endpoint | +| `GetAuditMessagesByConversation` | Get all audit messages in a conversation | +| `GetAuditMessageBody` | Get the body content of a specific audit message | + +#### Endpoints + +| Tool | Description | +| --- | --- | +| `GetKnownEndpoints` | List all known endpoints that have sent or received audit messages | +| `GetEndpointAuditCounts` | Get audit message counts per day for a specific endpoint | diff --git a/servicecontrol/servicecontrol-instances/configuration.md b/servicecontrol/servicecontrol-instances/configuration.md index 91e6ca748f0..382c87ee059 100644 --- a/servicecontrol/servicecontrol-instances/configuration.md +++ b/servicecontrol/servicecontrol-instances/configuration.md @@ -1306,6 +1306,22 @@ When configuring the heartbeat grace period, make sure it is greater than the [h > [!NOTE] > When monitoring multiple endpoints, ensure that the heartbeat grace period is larger than any individual heartbeat interval set by the endpoints. +## MCP + +### ServiceControl/EnableMcpServer + +Enables the [Model Context Protocol (MCP)](/servicecontrol/mcp.md) server, allowing AI-powered tools and assistants to interact with ServiceControl. + +| Context | Name | +| --- | --- | +| **Environment variable** | `SERVICECONTROL_ENABLEMCPSERVER` | +| **App config key** | `ServiceControl/EnableMcpServer` | +| **SCMU field** | N/A | + +| Type | Default value | +| --- | --- | +| bool | `false` | + ## Troubleshooting ### ServiceControl/DataSpaceRemainingThreshold From c5b371e655f787afdd6019bb2b09ba2c200862a5 Mon Sep 17 00:00:00 2001 From: williambza Date: Mon, 23 Mar 2026 12:05:11 +0200 Subject: [PATCH 2/3] Fix anchor links --- servicecontrol/mcp.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/servicecontrol/mcp.md b/servicecontrol/mcp.md index b04a5cc6f81..f71d0456beb 100644 --- a/servicecontrol/mcp.md +++ b/servicecontrol/mcp.md @@ -18,11 +18,11 @@ The MCP server is disabled by default and must be enabled separately on each ins ### Error instance -See [EnableMcpServer](/servicecontrol/servicecontrol-instances/configuration.md#enablemcpserver) in the error instance configuration settings. +See [EnableMcpServer](/servicecontrol/servicecontrol-instances/configuration.md#mcp-servicecontrolenablemcpserver) in the error instance configuration settings. ### Audit instance -See [EnableMcpServer](/servicecontrol/audit-instances/configuration.md#enablemcpserver) in the audit instance configuration settings. +See [EnableMcpServer](/servicecontrol/audit-instances/configuration.md#mcp-servicecontrol-auditenablemcpserver) in the audit instance configuration settings. ## Connecting an MCP client From 05e30cf702522e90f99996fcfe95626615e1e287 Mon Sep 17 00:00:00 2001 From: WilliamBZA Date: Sun, 5 Apr 2026 13:16:47 +0200 Subject: [PATCH 3/3] Document write flag --- servicecontrol/mcp.md | 9 +++++++++ .../servicecontrol-instances/configuration.md | 16 ++++++++++++++++ 2 files changed, 25 insertions(+) diff --git a/servicecontrol/mcp.md b/servicecontrol/mcp.md index f71d0456beb..b0faa1532ca 100644 --- a/servicecontrol/mcp.md +++ b/servicecontrol/mcp.md @@ -24,6 +24,15 @@ See [EnableMcpServer](/servicecontrol/servicecontrol-instances/configuration.md# See [EnableMcpServer](/servicecontrol/audit-instances/configuration.md#mcp-servicecontrol-auditenablemcpserver) in the audit instance configuration settings. +## Write mode + +By default, the MCP server on the error instance operates in read-only mode. Write operations such as retrying and archiving failed messages are disabled unless write mode is explicitly enabled. + +To enable write operations, set [EnableMcpWriteMode](/servicecontrol/servicecontrol-instances/configuration.md#mcp-servicecontrolenablemcpwritemode) to `true` on the error instance in addition to enabling the MCP server. + +> [!WARNING] +> Enabling write mode allows MCP clients to perform destructive operations on failed messages, such as retrying or archiving them. Only enable this if you trust the MCP clients connecting to the instance. + ## Connecting an MCP client Once enabled, configure an MCP client to connect to the ServiceControl instance using the HTTP Streamable transport. For example, an error instance running on its default address would be accessible at: diff --git a/servicecontrol/servicecontrol-instances/configuration.md b/servicecontrol/servicecontrol-instances/configuration.md index 382c87ee059..cffb5fc87c9 100644 --- a/servicecontrol/servicecontrol-instances/configuration.md +++ b/servicecontrol/servicecontrol-instances/configuration.md @@ -1322,6 +1322,22 @@ Enables the [Model Context Protocol (MCP)](/servicecontrol/mcp.md) server, allow | --- | --- | | bool | `false` | +### ServiceControl/EnableMcpWriteMode + +Enables write operations in the [Model Context Protocol (MCP)](/servicecontrol/mcp.md) server, allowing AI-powered tools and assistants to perform actions such as retrying and archiving failed messages. When disabled, the MCP server operates in read-only mode. + +Requires [`ServiceControl/EnableMcpServer`](#mcp-servicecontrolenablemcpserver) to be enabled. + +| Context | Name | +| --- | --- | +| **Environment variable** | `SERVICECONTROL_ENABLEMCPWRITEMODE` | +| **App config key** | `ServiceControl/EnableMcpWriteMode` | +| **SCMU field** | N/A | + +| Type | Default value | +| --- | --- | +| bool | `false` | + ## Troubleshooting ### ServiceControl/DataSpaceRemainingThreshold