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.

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

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"]
    }
  }
}

(bunx is used instead of npx when bun is detected as the package manager.)

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