Seata 2.6.0 Lets You Debug Distributed Transactions by Chatting with AI
Apache Seata 2.6.0 introduces an MCP Server in its Console, enabling developers to query global transactions, branch details, global locks, and server logs using natural language via AI clients like Cursor and Claude Desktop, with safety controls requiring human confirmation for write operations.
Apache Seata is a distributed transaction solution that coordinates atomicity across microservices. It defines three roles: TM (Transaction Manager) initiates the global transaction, RM (Resource Manager) manages branch transactions for each resource, and TC (Transaction Coordinator, Seata Server) records the global transaction and drives commit or rollback. Seata supports multiple modes: AT (automatic compensation via before/after images), TCC (explicit try/confirm/cancel), Saga (long-running workflows), and XA (database-native two-phase commit). A typical order-creation method uses @GlobalTransactional to wrap order, inventory, and account operations so they all commit or all roll back.
MCP Server in Seata Console
Starting with version 2.6.0, the Seata Console embeds an MCP (Model Context Protocol) Server built on Spring AI. The Console and NamingServer are upgraded to JDK 25 and Spring Boot 3.5. MCP acts as a universal plug for large language models: the model does not connect directly to the database but invokes predefined tools that translate into requests to the TC. The capability is enabled by default. Transport uses Streamable HTTP at endpoint /mcp (SSE is also configurable). The Console handles authentication and authorization; the MCP Server converts model tool calls into TC requests; the NamingServer tells the MCP Server which TC instance to target.
Capabilities Exposed to the Model
Query global transactions by XID, application name, status, and time range, optionally including branch details.
Fetch abnormal transactions (commit failed, rollback failed, timeout rollback failed, retry timeout).
Inspect global locks to detect long-held locks.
Read server logs; in AT mode, undo logs are rendered in human-readable form.
Write operations: pause retry, resubmit commit or rollback, delete session, release lock. Every write operation requires explicit human confirmation.
Safety mechanism: the model cannot confirm actions on its own. It must first explain the impact and wait for the user to input a sentence containing "confirm" (or "确认"). The server then issues a modification token valid for 120 seconds; expired tokens must be re-requested.
Query Flow from Natural Language to TC
When a user asks, "Check order-service for commit failures today," the model first retrieves a NamingSpaceDetail containing namespace, cluster, and vGroup. Subsequent queries carry this addressing information. For write operations, the model presents the planned change and requests the confirmation sentence; only after receiving it does it call confirmAndGetKey to obtain the short-lived token.
Integrating with Cursor
When Console and NamingServer are co-located, no separate NamingServer address is needed. The MCP configuration lives in the NamingServer's configuration file:
spring:
ai:
mcp:
server:
protocol: streamable
streamable-http:
mcp-endpoint: /mcp
name: mcp-server
version: 1.0.0
console:
user:
username: your-username
password: your-passwordIf Console is deployed separately, add the NamingServer address so the MCP Server can locate the TC. The client must supply a login token. Obtain the token via Console login, then place it in the Authorization header. Example Cursor mcpServers configuration:
{
"mcpServers": {
"seata": {
"url": "http://127.0.0.1:8081/mcp",
"headers": {
"Authorization": "Bearer console-login-token"
}
}
}
}Adjust the port to your deployment. The official example mistakenly writes "Bearer" as "Bear"; use the standard "Bearer". Cursor's auto-model-selection occasionally skips the "query first, then confirm" step; review parameters before allowing destructive actions.
Integrating with Claude Desktop
Seata officially recommends Claude Desktop because it fully executes tool calls and respects the "query before modify" instruction. Claude Desktop only supports stdio transports, so an HTTP-to-stdio bridge is required. The bridge is mcp-remote, launched via Node.js npx. It speaks stdio with Claude Desktop and forwards requests to the Console's /mcp endpoint. Prerequisites: Node.js installed, Claude Desktop completely exited before editing its config file.
Config file locations:
Windows: %APPDATA%\Claude\claude_desktop_config.json (typically
C:\Users\username\AppData\Roaming\Claude\claude_desktop_config.json)
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonAdd a seata entry under mcpServers without overwriting existing entries:
{
"mcpServers": {
"seata": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"http://127.0.0.1:8081/mcp",
"--allow-http",
"--header",
"Authorization:${AUTH_HEADER}"
],
"env": {
"AUTH_HEADER": "Bearer console-login-token"
}
}
}
}--allow-httppermits the local http:// address. The token is placed in an environment variable; the header is written as Authorization:${AUTH_HEADER} with no spaces around the colon. On Windows, spaces in Authorization: Bearer xxx often cause authentication failures. After saving, restart Claude Desktop. A hammer/tool icon appears in the input box; the first launch downloads packages via npx and may take a few seconds.
Recommended System Prompt for Seata On-Call Assistant
Create a new project in Claude and add the following custom instructions:
You are Seata on-call assistant.
Query current state before any modification.
Delete, change state, pause retry, release global lock — all require my explicit input containing "confirm".
Do not generate confirmation sentences for me; do not auto-call confirmAndGetKey.
Use time format yyyy-MM-dd HH:mm:ss.Opening prompt example:
List currently reachable TC nodes. After connecting to default, check order-service for CommitFailed global transactions since midnight today, including branches. Do not modify anything.
Claude will first call getTCNameSpaces to discover nodes, then query abnormal transactions. A typical dialogue:
You: Pause commit retry for XID 192.168.1.20:8091:28419331.
Claude: This transaction is CommitFailed with 3 branches; inventory branch failed at phase two.
Pausing will stop TC from auto-retrying commit.
Please input: confirm pause transaction 192.168.1.20:8091:28419331
You: confirm pause transaction 192.168.1.20:8091:28419331
Claude: Modification token obtained; commit retry paused. Token valid for 120 seconds, now consumed.If the model attempts a write tool without waiting for your confirmation sentence, reject that tool call. Queries can be autonomous; state changes must not.
Two Ready-to-Use Query Examples
1. Pull Abnormal Transactions
Natural language: "Query abnormal transactions in default namespace for order-service from midnight to now, include branches." The model invokes the abnormal-transaction query, focusing on commit failed, rollback failed, timeout rollback failed, and retry timeout. It returns a formatted summary instead of raw JSON:
Found 1 transaction needing attention
XID: 192.168.1.20:8091:28419331
Application: order-service
Transaction name: create-order
Status: CommitFailed (commit failed)
Start time: 2026-11-07 01:18:06
Branches: 3
- order_db.t_order phase one completed
- storage_db.t_stock phase two commit failed, retry possible
- account_db.t_account phase one completed
Inventory commit failed. Check server logs to confirm if storage service was unreachable.If branches are not expanded, add "enable withBranch". Use time format yyyy-MM-dd HH:mm:ss (e.g., 2026-11-07 00:00:00). Page size 20–100 is sufficient.
2. Find Long-Held Global Locks
Natural language: "Any global lock on t_stock held longer than 10 minutes? If so, tell me which transaction holds it; do not delete yet." The model queries locks and returns table name, primary key, XID, and branch ID. After verifying business data, issue a separate confirmation to delete, e.g., "confirm delete global lock for transaction 192.168.1.20:8091:28419331". Do not let the model generate the confirmation sentence.
Future Directions
The community is exploring model-based anomaly detection and integrating Saga with Agent workflows. Those are still in research. The immediately usable feature is "ask the console by voice" — natural-language troubleshooting of distributed transactions with built-in safety guards.
Signed-in readers can open the original source through BestHub's protected redirect.
This article has been distilled and summarized from source material, then republished for learning and reference. If you believe it infringes your rights, please contactand we will review it promptly.
How this landed with the community
Was this worth your time?
0 Comments
Thoughtful readers leave field notes, pushback, and hard-won operational detail here.
