Skip to content

Add docs for ServiceControl MCP settings #8148

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
WilliamBZA wants to merge 3 commits into
base: master
Choose a base branch
from
+184 −0
Open

Add docs for ServiceControl MCP settings #8148

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
281c39b
Add docs for ServiceControl MCP settings
WilliamBZA Mar 23, 2026
c5b371e
Fix anchor links
WilliamBZA Mar 23, 2026
05e30cf
Document write flag
WilliamBZA Apr 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions menu/menu.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
16 changes: 16 additions & 0 deletions servicecontrol/audit-instances/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
134 changes: 134 additions & 0 deletions servicecontrol/mcp.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,134 @@
---
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#mcp-servicecontrolenablemcpserver) in the error instance configuration settings.

### Audit instance

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:

```
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 |
32 changes: 32 additions & 0 deletions servicecontrol/servicecontrol-instances/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1306,6 +1306,38 @@ 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` |

### 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
Expand Down
Loading