MCP Server

CLI

The MCP server is how your agent accesses .archcore/. It gives agents tools to list, search, read, create, update, and link documents — and prompts that orchestrate full multi-document cascades — all within the conversation.

You usually don’t need to think about MCP directly — archcore init sets it up automatically. This page explains what happens under the hood and how to configure it manually.

What agents can do

Once MCP is configured, agents interact with your documents through 10 tools:

Action	Tool	Description
Browse	list_documents	List documents filtered by type, layer, or status
Search	search_documents	Full-text and path-reference search across bodies
Read	get_document	Get full document content with relations
Create	create_document	Create new documents from templates
Update	update_document	Modify title, status, or content
Delete	remove_document	Remove a document permanently
Link	add_relation	Create a relation between two documents
Unlink	remove_relation	Remove a relation
Browse links	list_relations	View all relations or filter by document
Bootstrap	init_project	Initialize .archcore/ from inside a session

See MCP tools reference for the complete API with parameters and examples.

Bootstrapping in an empty repo

The MCP server starts even when .archcore/ doesn’t exist yet. From inside a fresh repo, an agent can call the init_project tool to create the directory and write a default settings.json — no shell command required. The tool is idempotent: calling it on an already-initialized project just returns the existing settings.

init_project only sets up .archcore/. To install hooks or register the MCP server with other coding agents, run archcore hooks install and archcore mcp install from the shell.

MCP prompts

The server also exposes 5 prompts — pre-orchestrated multi-document cascades that an agent runs end-to-end with a confirmation gate between phases. Most MCP-aware clients surface them as slash commands.

Prompt	What it does
product_track	PRD → Plan (lightweight feature flow)
architecture_track	ADR → Spec → Plan (technical design + implementation)
standard_track	ADR → Rule → Guide (codify a team standard)
sources_track	MRD → BRD → URD (market / business / user discovery)
iso_track	BRS → StRS → SyRS → SRS (formal ISO 29148 cascade)

Example. In your agent, run:

/product_track feature_name="user notifications"

The agent drafts the PRD, asks you to confirm, then derives a Plan and links it back with plan implements prd. You can stop at any gate.

See MCP prompts reference for arguments and full chain details.

Note

These MCP prompts are different from the plugin’s /archcore:plan --track ... cascades. MCP prompts ship in the CLI’s MCP server and work in any MCP-aware client (Gemini CLI, Copilot, Codex, OpenCode, …). Plugin cascades are skills that ship with the Archcore Plugin and are scoped to plugin hosts.

Built-in agent instructions

The MCP server doesn’t just expose tools — it teaches agents how to use them. On connect, an agent receives instructions covering:

• Which document type to use for each situation
• Naming conventions and slug rules
• When to create vs. update documents
• How to use relations properly
• Status lifecycle (draft -> accepted -> rejected)
• When to call init_project (empty repo + user wants to create a document)

These instructions are sent automatically. You don’t need to explain Archcore conventions to your agent.

Installation

Automatic (recommended)

archcore init

archcore init auto-detects installed agents and configures MCP for each one, writing the config file so the agent launches the MCP server on startup.

Manual

Install for all detected agents:

archcore mcp install

Or for a specific agent:

archcore mcp install --agent claude-code

Manual config

To configure MCP by hand, add to your agent’s MCP config:

{
  "mcpServers": {
    "archcore": {
      "command": "archcore",
      "args": ["mcp"]
    }
  }
}

Config file locations vary by agent — see Agent integrations for details.

Pointing the server at a project root

By default archcore mcp reads documents from the current working directory. Some agents launch the server from a directory that isn’t the workspace root (e.g., a desktop app’s install directory, or a profile-scoped runner). In those cases, point the server at the right project:

• Flag — archcore mcp --project /absolute/path/to/repo
• Environment — ARCHCORE_PROJECT_ROOT=/absolute/path/to/repo archcore mcp

Precedence: --project > ARCHCORE_PROJECT_ROOT > current working directory. The path must exist; it does not need to contain .archcore/ yet — init_project can bootstrap it from the session.

Example MCP config that pins an absolute project root:

{
  "mcpServers": {
    "archcore": {
      "command": "archcore",
      "args": ["mcp", "--project", "/Users/me/code/my-repo"]
    }
  }
}

Language support

If you set a language in your config:

archcore config set language ru

The MCP server instructions will include a directive for the agent to write document content in that language.

Session hooks

Hooks inject a summary of your .archcore/ directory into the agent’s context the moment a session starts — before you type anything. This means the agent can reference your decisions, rules, and patterns from the first message.

Hooks are optional — MCP tools work without them — but they make the experience significantly smoother.

How hooks work

1. You start an agent session (e.g., open Claude Code)
2. The agent triggers its SessionStart event
3. The hook runs archcore hooks <agent-id> session-start
4. Archcore outputs a list of available documents with their types and titles
5. The agent receives this project context alongside the conversation

Installing hooks

Hooks are installed automatically during archcore init. To install manually:

archcore hooks install

Or for a specific agent:

archcore hooks install --agent claude-code

Hook config example

For Claude Code, the hook is added to .claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "archcore hooks claude-code session-start"
          }
        ]
      }
    ]
  }
}

See Hooks for everything hooks emit and how to write custom ones.

When you don’t need hooks

• You always start by asking about context — if your workflow is to ask the agent “what documents exist?” at the start, hooks don’t add much.
• Your agent doesn’t support hooks — some agents lack hook support; MCP tools still work fine.
• You prefer explicit control — some users prefer to decide when the agent loads context.

Protocol details

The MCP server runs as a subprocess launched by your coding agent. When the agent starts, it spawns archcore mcp and communicates over stdin/stdout using JSON-RPC 2.0 (stdio transport). The server stays running for the session.

Next steps

• Agent integrations — per-agent support matrix and config paths.
• Hooks — the session-start hook and what it outputs.
• MCP tools reference — full API spec.
• MCP prompts reference — track cascades available as prompts.