`helix mcp`¶

Sub-dispatcher for Model Context Protocol (MCP) management. Three subcommands: list shows the MCP servers configured in a flow file, serve is an alias for helix run that runs the configured servers, and inspect connects to a running MCP server and dumps its tool list and resources.

Usage¶

helix mcp <subcommand> [arguments]

Sub-commands¶

Sub-command	Description
`helix mcp list <file>`	Print the MCP server table from a YAML's `mcps:` block plus the workflows that could be exposed.
`helix mcp serve <file>`	Run the flow (delegates to `cmdRun`). MCP servers in `helix.mcp.servers` are started as part of normal startup.
`helix mcp inspect <address>`	Connect to a running MCP server (HTTP streamable transport) and list its tools and resources.

`mcp list`¶

Reads the flow's helix.mcp.servers config and prints NAME, TRANSPORT, ADDRESS, and the list of exposed workflows (or all when none are explicitly named). Disabled servers are skipped.

Below the server table, it lists every workflow in the file with a [workflow] or [agent] kind marker plus an input-schema parameter count when present — these are the workflows you can attach to an expose: list.

When no MCP block is present, prints an example mcps: snippet to get the user started.

`mcp serve`¶

Wraps cmdRun. The MCP startup logic is unchanged — every helix.mcp.servers[] entry with enabled: true becomes an mcp-server:// workflow at engine start, with security params (api_keys, cors_origins, rate_limit, ip_allowlist, trusted_proxies, max_body_bytes, allowed_tools, blocked_tools) translated into URI query params. Use it when "this flow exists primarily to serve MCP" and you want a more descriptive name in scripts than helix run.

`mcp inspect`¶

Connects to a running MCP server using the official github.com/modelcontextprotocol/go-sdk HTTP streamable transport. The address may be a bare host:port (auto-prefixed with http://) or a full URL. Lists every tool with a truncated description and input schema preview, then any resources.

Flags¶

This subcommand takes no flags. Sub-command behavior is positional.

Behavior notes¶

Requires $HELIX_LICENSE. Verified at process start.
mcp inspect uses a 10-second context timeout for the round-trip; unreachable or unresponsive servers fail with a clear error.
The client identifies itself as helix-cli with the binary's version string.
All MCP servers run by helix mcp serve are exposed at mcp-server://<addr>?.... Tool overrides (descriptions and input schemas declared in helix.mcp.servers[].tools) are propagated to the matching workflow at startup.

Examples¶

Show MCP servers + the workflows they could expose:

$ helix mcp list app.yaml
MCP Servers in app.yaml:

NAME                 TRANSPORT  ADDRESS                   TOOLS
----                 ---------  -------                   -----
my-tools             http       0.0.0.0:3200              chat-agent

Available routes (4):
  chat-agent                [agent ] General chat assistant
  doc-search                [workflow] Search knowledge base documents (1 params)
  ...

Start the configured servers:

helix mcp serve app.yaml

Probe a running MCP server:

$ helix mcp inspect localhost:3200
Connecting to MCP server at http://localhost:3200...

MCP Server: http://localhost:3200
Tools: 3

TOOL                      DESCRIPTION
----                      -----------
chat                      General chat assistant
search-docs               Search the knowledge base for relevant docs
                          schema: {"type":"object","properties":{"query":{"type":"string"}}...

Resources: 1
  helix://routes — List of all routes in this server

Source¶

cmd/helix/main.go lines 2776-2791 (cmdMCP dispatcher), 2793-2851 (cmdMCPList), 2853-2861 (cmdMCPServe), 2863-2931 (cmdMCPInspect).

The MCP server config schema lives in pkg/config/ under helix.mcp.servers; the mcp-server:// and mcp:// components live in pkg/component/mcp/.

helix mcp¶