chant serve mcp

Synopsis

chant serve mcp [path]

Description

chant serve mcp starts an MCP (Model Context Protocol) server over stdio. This allows AI agents that support MCP — such as Claude Code, Cursor, and Windsurf — to interact with your chant project programmatically.

Typically you don’t run this directly. chant init detects your IDE and writes the MCP config to the appropriate global config file — ~/.claude/mcp.json for Claude Code, ~/.cursor/mcp.json for Cursor, or ~/.config/mcp/mcp.json otherwise. Your agent picks it up automatically. See Agent Integration.

Tools

The server exposes six core tools that agents can invoke:

build

Build chant infrastructure code and generate output for the target lexicon.

Parameter	Type	Required	Description
path	string	Yes	Path to the infrastructure directory or file
output	string	No	Output file path (returns in response if omitted)
format	"json" | "yaml"	No	Output format (default: json)

Returns { success, resourceCount, output, format }.

lint

Lint chant infrastructure code and report issues.

Parameter	Type	Required	Description
path	string	Yes	Path to the infrastructure directory or file
fix	boolean	No	Auto-fix fixable issues (default: false)

Returns { success, errorCount, warningCount, diagnostics, output }.

import

Import external templates and convert them to chant TypeScript.

Parameter	Type	Required	Description
source	string	Yes	Path to the template file to import
output	string	No	Output directory (default: ./infra/)

Returns { success, lexicon, generatedFiles, warnings }.

explain

Summarize the resources in a chant project.

Parameter	Type	Required	Description
path	string	Yes	Path to the infrastructure directory
format	"markdown" | "json"	No	Output format (default: markdown)

Returns a structured summary of resource counts, entity types, and lexicon groupings.

scaffold

Generate starter files for a chant project.

Parameter	Type	Required	Description
pattern	string	Yes	Resource pattern to scaffold (e.g. "s3-bucket", "pipeline")
lexicon	string	No	Lexicon to use for templates

Returns { success, files } with generated file contents.

search

Search available resource types across loaded lexicons.

Parameter	Type	Required	Description
query	string	Yes	Search query (case-insensitive substring match)
lexicon	string	No	Filter to a specific lexicon
limit	number	No	Maximum results (default: 20)

Returns matching resource type entries sorted by relevance.

Every Op tool takes an optional runtime, the same choice chant run --on makes on the command line. Omitted, it is the built-in local runtime, which executes the Op in this process.

op-list

List every Op discovered from *.op.ts files with the run state the runtime reports.

Parameter	Type	Required	Description
runtime	string	No	Runtime to address: a lexicon name with an opRuntime, or local (the default)

op-run

Run an Op on a runtime and return its result.

Parameter	Type	Required	Description
name	string	Yes	Op name (must match an *.op.ts file)
runtime	string	No	Runtime to address: a lexicon name with an opRuntime, or local (the default)

op-status

Show the state the runtime reports for an Op’s latest run.

Parameter	Type	Required	Description
name	string	Yes	Op name
runtime	string	No	Runtime to address: a lexicon name with an opRuntime, or local (the default)

Returns { op, runId, state, startedAt, endedAt, records, gate }. records is the per-phase StepRecord[] array (present when the Op’s *.op.ts is discoverable; see Progress and gate state) — the same shape --progress-json streams. gate is the pending gate ({ name, since }), absent when none is standing.

op-approve

Record a gate’s resolution on the gate ledger, then wake the runtime hosting the gated run. This is the rename of op-signal, and a different act: a gate is resolved by recording the fact, not by sending a message to a waiting workflow.

Parameter	Type	Required	Description
name	string	Yes	Op name
gate	string	Yes	Gate name (must match the gate’s name in the Op)
approver	string	No	Who approved; defaults to the CI or shell identity
note	string	No	Free-text context recorded on the resolution
url	string	No	Absolute http/https URL this resolution happened at
runtime	string	No	Runtime to address: a lexicon name with an opRuntime, or local (the default)

op-report

Return a markdown report for an Op’s latest run.

Parameter	Type	Required	Description
name	string	Yes	Op name
runtime	string	No	Runtime to address: a lexicon name with an opRuntime, or local (the default)

Plugin Tools

Lexicon plugins can contribute additional tools. Plugin tools are namespaced as {pluginName}:{toolName} to avoid conflicts with core tools.

Resources

The server provides resources that agents can read for context:

URI	MIME Type	Description
chant://context	text/markdown	Lexicon-specific instructions, patterns, and best practices
chant://examples/list	application/json	JSON array of available examples ([{ name, description }])
chant://examples/<name>	text/typescript	Source code of a specific example
chant://ops	application/json	List of all discovered Ops with metadata
chant://ops/{name}/runs	application/json	Recent run history for a specific Op
chant://ops/{name}/runs/latest	application/json	Latest run state for a specific Op

Plugin Resources

Lexicon plugins can contribute additional resources, namespaced as chant://{pluginName}/{path}. Plugin resources with /examples/ in their URI are automatically included in the examples list.

Configuration

Automatic Setup

chant init detects your IDE and adds the MCP server to the appropriate global config file:

IDE	Config path
Claude Code	~/.claude/mcp.json
Cursor	~/.cursor/mcp.json
Other	~/.config/mcp/mcp.json

The config looks like:

{
  "mcpServers": {
    "chant": {
      "command": "npx",
      "args": ["chant", "serve", "mcp"]
    }
  }
}

Manual Setup

If your agent doesn’t auto-detect the MCP config, configure the server manually. The command is:

chant serve mcp

The server communicates over stdin/stdout using JSON-RPC 2.0 with line-based framing (one JSON object per line).

Protocol Details

The MCP server implements the Model Context Protocol specification version 2024-11-05.

Supported Methods

Method	Description
initialize	Handshake — returns protocol version, capabilities, and server info
tools/list	List all available tools (core + plugin-contributed)
tools/call	Invoke a tool by name with parameters
resources/list	List all available resources (core + plugin-contributed)
resources/read	Read a resource by URI

Exit Codes

Code	Meaning
0	Clean shutdown
1	Unknown subcommand or startup failure

See Also

• Agent Integration — Setup guide and .mcp.json configuration
• chant serve lsp — LSP server for editor integration