MCP Integration

tramai-mcp is a Spring Boot auto-configured MCP server adapter. It reads the WorkflowRegistry, WorkflowRunStore, and WorkflowController already present from tramai-server and exposes four MCP tools over stdio or SSE. Agent clients can then discover and invoke workflows through the standard MCP contract instead of raw REST calls.

Read This First: Availability

tramai-mcp is internal and not published in 0.6.0. There is no Maven coordinate for it, it is not managed by tramai-bom, and it is not part of the stable public API. It is composed inside the TramAI repository as a Gradle project dependency:

// inside the TramAI monorepo, in the build.gradle.kts of an MCP host
dependencies {
    implementation(project(":tramai-mcp"))
}

tramai-server, which this adapter requires, is internal and not published for the same reason. Do not plan a consumer-facing integration around either module without first checking the classification in the repository's config/quality/module-catalog.yml.

This page documents the adapter's actual behaviour so it can be used inside the repository — and so nobody builds against a surface that does not exist yet.

What Does Not Exist

Two things are commonly assumed to be part of TramAI's MCP support. Neither is implemented in 0.6.0:

• There is no governed remote MCP client. TramAI does not act as an MCP client that discovers remote MCP servers and subjects their tools to policy, approval, or audit. Remote MCP tools are not governed by TramAI today.
• There is no governed remote MCP tool connector. Workflows do not automatically discover, register, and govern third-party MCP tools.

What does exist for workflow-side MCP calls is a builder convention: tramai-orchestration provides an mcpStep function on the workflow builder, where you supply the tool-call builder yourself. That is a calling convention for a tool you already understand, not discovery or governance.

For the governance story that is implemented, see MCP Governance and Tool Governance.

What This Covers

• The four exposed MCP tools
• Stdio and SSE transport configuration
• Error mapping to MCP errors
• Where the adapter sits relative to the REST API
• Known limits

When To Use It

Use tramai-mcp when:

• a local agent tool should discover workflows automatically
• workflow invocation should look like normal MCP tool usage
• workflow input and output contracts should be exposed as JSON Schema

Do not add it when no MCP client will consume it — the tramai-server REST API is enough, and both modules are repository-internal.

Exposed Tools

run_workflow takes workflowName, state, and an optional idempotencyKey. resume_workflow and get_workflow_status take a workflowId and an optional workflowName; when the name is omitted, the adapter scans the registered workflows to find the owner of the run ID.

Schemas are generated from the registered workflow state and result types through the structured-output handler, so the contract the MCP client sees matches what the engine actually deserializes.

Activation

The auto-configuration is conditional on all three server beans being present:

• WorkflowRegistry — registered workflow definitions
• WorkflowRunStore — persisted run state
• WorkflowController — run, resume, and status operations

In practice that means tramai-server must already be in the application. The adapter layers on top; it does not replace or duplicate the server.

Transport Configuration

At least one transport must be enabled for the server to start. Everything binds under tramai.mcp.*:

tramai:
  mcp:
    stdio:
      enabled: false      # starts an MCP stdio session in-process
    sse:
      enabled: false      # starts an embedded Ktor SSE server
      host: 127.0.0.1
      port: 8091
      path: /mcp

Defaults are stdio.enabled: false, sse.enabled: false, sse.host: 127.0.0.1, sse.port: 8091, and sse.path: /mcp.

Stdio

Best for local agent processes that spawn the host JVM as a subprocess. The server creates a StdioServerTransport over the process's standard input and output and starts a session on the application's coroutine scope. No port, no network, no TLS concerns.

tramai:
  mcp:
    stdio:
      enabled: true

SSE

Best for network-accessible MCP clients.

tramai:
  mcp:
    sse:
      enabled: true
      host: 127.0.0.1
      port: 8091
      path: /mcp

The SSE transport is served by an embedded Ktor CIO server and is separate from the Spring Boot HTTP port. Enabling it does not reuse server.port, its TLS configuration, or its security filters. Treat it as a separately exposed surface.

Relationship To The REST API

Every MCP tool call flows through the same code path as the equivalent REST request:

MCP run_workflow("invoice", { "invoiceId": "abc" })
  → McpToolHandlers.runWorkflow()
    → WorkflowController.runWorkflow(name, body, idempotencyKey)
      → WorkflowEngine.run(...)

MCP behaviour therefore inherits workflow validation, idempotency, conflict handling, and run status semantics unchanged. The adapter introduces no second execution path.

Error Mapping

Server-side exceptions are normalized into MCP tool failures:

Failures return a structured { error, errorType } payload alongside the human-readable message, so agent clients never see Spring-specific or Ktor-specific exception shapes.

Limits

• No cancellation tool — a workflow run cannot be cancelled through MCP; use the REST API.
• No tools/notifications — listChanged is false, so clients must re-list to discover new workflows.
• Stdio creates exactly one session; use SSE for multiple connections.
• The SSE server is a separate Ktor instance and does not reuse the Spring Boot HTTP port or its TLS setup.
• No administrative endpoints are exposed beyond the four tools above.
• Internal, unpublished status means no compatibility promise and no Maven coordinate.

Next Steps

• Workflow Server — the REST API and server-side run store
• MCP Governance — the governance model for MCP tool use
• Custom Providers — provider adapters for tool-calling backends
• Adding a Workflow Step — contributing workflow steps