TramAI

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

ToolPurpose
list_workflowsReturn registered workflows with input/output JSON schema
run_workflowStart a workflow run from a JSON state object
resume_workflowResume a suspended run by workflow id
get_workflow_statusFetch 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 exceptionMCP error
Unknown workflownot_found
Unknown runnot_found
Resume/state conflictconflict
Invalid input JSONinvalid_request
Unexpected failureinternal_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

Previous
Next