MCP Server

CLI

The MCP server is how your agent accesses .archcore/. It gives agents tools to list, read, create, update, and link documents — 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 if needed.

What agents can do

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

Action	Tool	Description
Browse	list_documents	List documents filtered by type, layer, or status
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

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

Built-in agent instructions

The MCP server doesn’t just expose tools — it teaches agents how to use them. When an agent connects, it 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)

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. It writes the appropriate 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

If you need 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.

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 hooks 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 duration of 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.