MCP Server

Overview

Helix includes a first-class Model Context Protocol ecosystem for AI-assisted development. The MCP server gives agents structured access to Helix-specific context, while the accompanying skills help those agents apply the framework in a way that stays aligned with Helix conventions.

This is the practical meaning behind Helix being fully agent compliant: agents do not have to guess how the framework is organized or fall back to generic Spring patterns when Helix already provides a better-native answer.

Why It Matters

Without MCP, an agent has to infer framework conventions by searching source files, reading build scripts, and pattern-matching from examples. That can work, but it is slower and more error-prone.

With Helix MCP, an agent can ask direct questions about the ecosystem before it makes changes. That helps it:

• discover Helix-native modules, starters, plugins, templates, and examples
• choose framework-aligned patterns instead of reaching for generic rewrites
• explain Spring bean wiring, autoconfiguration, and web behavior with Helix-aware context
• stay closer to the documented platform model when extending an existing service

Install and Configure

The easiest way to install the Helix MCP server is through the CLI:

helix mcp setup claude

The CLI installs published helix-agent-mcp versions under the Helix config directory and maintains a stable executable path at:

~/.helix/tools/helix-agent-mcp/current/bin/helix-agent-mcp

That stable path is the one to configure in tools such as Codex or Claude. When you later run helix mcp update or helix mcp use <version>, the CLI retargets the stable path so your client configuration does not need to change.

Useful related commands:

helix mcp path
helix mcp versions
helix mcp use <version>
helix mcp update
helix mcp doctor

What Helix Exposes

The Helix MCP server exposes more than a simple package catalog. It provides structured framework context that agents can use during discovery, explanation, and implementation work.

The MCP surface includes:

• module and plugin discovery
• template and example lookup
• semantic code indexes for symbols, members, references, and implementations
• Spring bean, autoconfiguration, configuration-properties, and wiring metadata
• explanation-oriented lookups for runtime behavior, plugin effects, and framework defaults

In practical terms, that means an agent can discover the right Helix capability, inspect an example that demonstrates it, and understand related framework wiring before it edits code.

Prebuilt Skills

Helix also ships prebuilt agent skills for application development on top of the framework. These skills help agents behave more like a teammate who already understands the Helix ecosystem.

They guide agents to:

• prefer local application patterns before introducing new abstractions
• choose Helix-native modules and starters when they fit the task
• follow Helix-friendly testing, configuration, and project structure conventions
• use the Helix MCP for discovery when it is available

The skills and the MCP server complement each other. MCP provides structured framework context. Skills shape how an agent should use that context inside a real application repository.

Common Workflows

Set up a local agent integration

helix mcp setup claude

Inspect the active MCP installation

helix mcp path
helix mcp doctor

Update or switch MCP versions without changing client config

helix mcp update
helix mcp use <version>

Pair MCP with the rest of the Helix docs

Use the MCP page together with:

• CLI for command details and local setup
• Templates for project generation flows
• Examples for implementation patterns
• Core Concepts for the broader ecosystem model