MCP Servers

MCP (Model Context Protocol) servers provide tools and capabilities to AI agents running inside containers. Heretic CLI handles defining, merging, transforming, and mounting MCP config — so you can copy-paste server definitions from any source and have them work across all agent types.

Adding MCP Servers via Paste

The fastest way to add an MCP server is to paste its JSON config directly. Most MCP server READMEs provide a JSON snippet you can copy.

# Paste JSON via stdin — paste your JSON, then press Ctrl+D (macOS/Linux) or Ctrl+Z+Enter (Windows)
heretic-cli agents mcp claude

Paste the JSON:

{
  "mcpServers": {
    "context7": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@upstash/context7-mcp"
      ],
      "env": {}
    }
  }
}

Press Ctrl+D (macOS/Linux) or Ctrl+Z then Enter (Windows) to submit — the server is merged into your agent profile.

Paste Options

# Paste JSON via stdin
heretic-cli agents mcp claude

# Read from a file instead
heretic-cli agents mcp claude --file ~/mcp-servers.json

# Apply to local project override instead of global profile
heretic-cli agents mcp claude --local
heretic-cli agents mcp claude --local --file .vscode/mcp.json

Supported JSON Formats

Heretic CLI accepts any common MCP JSON format. The format is auto-detected from the top-level key:

Each server entry must have a command field. Optional args and env are passed through. Extra fields (e.g., type, cwd, tools, alwaysAllow) are silently handled — kept or stripped depending on the target agent type.

Examples of Accepted Formats

Claude Code / Copilot CLI format:

{
  "mcpServers": {
    "context7": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "env": {}
    }
  }
}

VS Code format:

{
  "servers": {
    "context7": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    }
  }
}

Bare server map:

{
  "context7": {
    "command": "npx",
    "args": ["-y", "@upstash/context7-mcp"]
  }
}

All three produce the same result inside the container.

Inline Definition

Define MCP servers directly in your agent profile YAML:

mcp:
  - name: filesystem
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
  - name: github
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_TOKEN: "${GH_TOKEN}"

File-Based Config (mcp_file)

Point to an existing JSON file instead of defining servers inline:

mcp_file: ~/projects/my-app/.vscode/mcp.json

The path supports ${VAR} interpolation:

mcp_file: ${CWD}/.vscode/mcp.json

Merging mcp_file and Inline

When both mcp_file and inline mcp are specified, they are merged by server name. Inline servers override file servers with the same name; new inline servers are appended:

mcp_file: ~/shared/mcp-servers.json
mcp:
  - name: trello           # overrides "trello" from file
    command: npx
    args: ["-y", "mcp-remote", "http://localhost:9090/sse"]
  - name: extra-server      # appended (not in file)
    command: npx
    args: ["-y", "my-mcp-server"]

Existing Workspace Config

By default, if a project-level MCP file already exists in your workspace, the CLI skips mounting the generated config and uses your existing file instead.

To force profile-defined MCP servers, set mcp_override: true:

mcp_override: true

The checked path depends on agent_type:

Runtime Override

Override at runtime with --mcp:

# From a JSON file
heretic-cli run claude --mcp ./my-servers.json

# Inline JSON
heretic-cli run claude --mcp '[{"name":"fs","command":"npx","args":["-y","@mcp/server-fs"]}]'

Agent-Specific Format Transformation

You define MCP servers once in any format. The CLI automatically transforms them to the correct format for each agent type when writing the container config.

Claude / Generic

Container path: /workspace/.mcp.json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
      "env": { "KEY": "value" }
    }
  }
}

Clean format — only command, args, and env fields. Extra fields like type, cwd, alwaysAllow are stripped.

Copilot CLI

Container path: ~/.copilot/mcp-config.json (both /root/ and /home/agent/)

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"],
      "type": "stdio",
      "tools": ["*"]
    }
  }
}

Copilot requires type: "stdio" and tools: ["*"] on every entry. These are added automatically by the CLI.

Kilocode (OpenCode)

Container path: /workspace/.kilocode/mcp.json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"],
      "alwaysAllow": ["*"],
      "disabled": false
    }
  }
}

Kilocode requires alwaysAllow (defaults to ["*"] if not provided). The disabled field is optional and preserved when explicitly set.

Kilocode MCP Fields

When defining MCP servers for kilocode agents, you can use these additional fields:

These fields are preserved through the full parse-store-write pipeline when the source is a kilocode-format config.

Configuration Layers

MCP config follows the three-layer merge system:

1. Global profile (~/.heretic/agents/<name>.yaml) — base MCP servers
2. Local override (.heretic/cli/<profile>.yaml) — project-specific servers
3. CLI flags (--mcp) — runtime override

The mcp array replaces entirely at each layer (not merged). Use mcp_file + inline mcp for merge-by-name behavior within a single layer.

Kilocode Global MCP Settings

Kilocode agents have a separate global MCP settings mechanism, independent of the project-level MCP config:

• Global file: ~/.heretic/<name>-kilocode-mcp.json (created by heretic-cli init)
• Local override: .heretic/cli/kilocode-mcp.json
• Container mount: ~/.config/kilo/mcp_settings.json

This is the Kilo Code application-level MCP config (analogous to Claude Code's ~/.claude/settings.json for MCP). The project-level MCP (/workspace/.kilocode/mcp.json) is for project-scoped servers.

{
  "mcpServers": {
    "global-server": {
      "command": "npx",
      "args": ["-y", "some-global-mcp-server"]
    }
  }
}

Global and local files are merged at runtime (arrays unioned, objects shallow-merged, local wins).

Session File Structure

Generated MCP files are stored in the session temp directory:

.heretic/temp/<session>/
  .mcp.json                    # Claude/Generic project-level MCP
  kilocode-local-mcp.json      # Kilocode project-level MCP
  kilo-config/
    mcp_settings.json           # Kilocode global MCP (merged)

These files are auto-managed by the CLI and cleaned up when the agent stops.

Examples

Claude Agent with MCP

# ~/.heretic/agents/claude.yaml
image: giglabo/claude-heretic:latest
runner: docker
provider: anthropic

mcp:
  - name: filesystem
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
  - name: github
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_TOKEN: "${GH_TOKEN}"

Copilot Agent with MCP from VS Code Config

# ~/.heretic/agents/copilot.yaml
image: giglabo/claude-heretic:latest
runner: docker
provider: copilot
agent_type: copilot-cli

mcp_file: ${CWD}/.vscode/mcp.json
mcp_override: true

Kilocode Agent with Project + Global MCP

# ~/.heretic/agents/kilocode.yaml
image: giglabo/claude-heretic:latest
runner: docker
provider: kilocode
agent_type: kilocode-cli
opencode_settings: ~/.heretic/kilocode-opencode.json
kilocode_mcp_settings: ~/.heretic/kilocode-kilocode-mcp.json

# Project-level MCP (mounted to /workspace/.kilocode/mcp.json)
mcp:
  - name: filesystem
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
    alwaysAllow: ["read_file", "list_directory"]

secrets:
  KILOCODE_API_KEY: ~/.heretic/get-kilocode-key.sh
env:
  KILOCODE_API_KEY: "${KILOCODE_API_KEY}"

Local Override Adding Project-Specific MCP

# .heretic/cli/claude.yaml
extends: claude

mcp:
  - name: project-docs
    command: npx
    args: ["-y", "@mcp/server-filesystem", "/workspace/docs"]

mcp_override: true

Next Steps

• Agent Profiles — Full profile reference including MCP fields
• Local Overrides — Per-project MCP configuration
• heretic-cli agents — The agents mcp subcommand for pasting MCP JSON