MCP Integration
tramai-mcp exposes registered workflows as MCP (Model Context Protocol) tools. This is the adapter for local or remote agent clients that should discover and run workflows through MCP instead of raw REST calls.
What This Covers
- Exposing workflows as MCP tools
- Stdio transport for local agent processes
- SSE transport for network access
- Error mapping for agent clients
- Relationship to the REST API
When to Use It
Add tramai-mcp when:
- a local coding or agent tool should discover workflows automatically
- workflow invocation should look like normal MCP tool usage
- you want workflow input/output contracts exposed as JSON schema
Do not add it just for a server API — the REST API is sufficient for non-MCP clients.
Minimum Setup
Dependency
implementation("dev.tramai:tramai-mcp:0.3.1")
implementation("dev.tramai:tramai-server:0.3.1")
tramai-mcp layers on top of the existing workflow server. It is an adapter, not a second orchestration runtime.
Stdio Transport
tramai:
mcp:
stdio:
enabled: true
This starts an MCP stdio session inside the application process.
SSE Transport
tramai:
mcp:
sse:
enabled: true
host: 127.0.0.1
port: 8091
path: /mcp
Important: The SSE transport is served by an embedded Ktor server. It is separate from the Spring Boot HTTP port — enabling it does not reuse server.port.
Exposed Tools
| Tool | Purpose |
|---|---|
list_workflows | Return registered workflows with input/output JSON schema |
run_workflow | Start a workflow run from a JSON state object |
resume_workflow | Resume a suspended run by workflow id |
get_workflow_status | Fetch current status, history, result, and error state |
The schemas are generated from registered workflow state and result types through the structured-output handler.
How It Works
The current implementation maps MCP requests to the existing server controller and run store logic. MCP behavior inherits:
- workflow validation
- idempotency behavior
- conflict handling
- run status and detail payload semantics
For example, run_workflow uses the same JSON-state decoding path as POST /workflows/{name}/run.
Error Mapping
The adapter normalizes exceptions into MCP tool failures:
| Server exception | MCP error |
|---|---|
| Unknown workflow | not_found |
| Unknown run | not_found |
| Resume/state conflict | conflict |
| Invalid input JSON | invalid_request |
| Unexpected failure | internal_error |
This keeps agent clients from seeing Spring-specific exception shapes.
Transport Options
Stdio
Best for: local coding agents (Codex CLI, Claude Code, Gemini CLI) running in the same process or as a subprocess.
No port, no network, no TLS concerns. The MCP protocol runs over stdin/stdout.
SSE
Best for: remote agent clients that need network access to workflow servers.
Requires an available port. Does not share the Spring Boot HTTP port.
Limitations
- does not expose cancellation as an MCP tool
- does not expose every server-side administrative endpoint
- depends on the workflow server module being present
- SSE transport uses a separate embedded server (Ktor), not the main application port
Next Steps
- Workflow Server — the REST API that powers MCP
- Custom Providers — implement custom providers for your workflows