MCP Server for Project Context

CLI

The MCP server is how your agent accesses .archcore/. It gives agents tools to list, search, read, create, update, and link documents inside the conversation.

You usually don’t need to configure MCP directly, because archcore init sets it up. This page explains what the server exposes and how to configure it by hand.

What agents can do

Once MCP is configured, agents interact with your documents through 10 always-registered tools, plus install_host_config, which the server registers only when it is started with host wiring:

Action	Tool	Description
Browse	list_documents	List documents filtered by type, category, or status
Search	search_documents	Word 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
Wire the host	install_host_config	Install hooks, MCP config, and the instruction nudge (conditionally registered)

archcore mcp always starts the server with host wiring, so all 11 tools are available when your agent launches the CLI. A server embedded in another program without a host-wiring executor exposes only the first 10.

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

install_host_config is gated

install_host_config wires a project’s host configs: hooks, the MCP server entry, and the Archcore instruction nudge. It produces the same artifacts as archcore init --agent. It is the only MCP tool that writes files outside .archcore/, so its invocation contract is narrow.

An agent may call it only when you have explicitly asked to set up or wire Archcore into your host and have confirmed a plan the agent stated first (which agent, which files). An agent that notices an unwired project must ask before it acts.

The tool is non-destructive by construction:

• Hook installs append or update in place, scoped to archcore’s marker-recognized entries. Foreign entries stay untouched.
• MCP config writes merge only archcore-owned fields, so your fields and other MCP servers survive.
• Instruction-nudge writes are fenced to the archcore marker span and atomic, so a crash mid-write cannot corrupt your CLAUDE.md, AGENTS.md, or GEMINI.md.

It returns a JSON report naming every artifact path it ensured, per agent, so nothing lands in your repo without appearing in the response.

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 is required. The tool is idempotent: calling it on an already-initialized project returns the existing settings.

init_project sets up .archcore/ only. It never touches host config. To install hooks or register the MCP server with other coding agents, run archcore hooks install and archcore mcp install from the shell, or ask the agent to run install_host_config once you’ve agreed on a plan.

Built-in agent instructions

On connect, an agent receives instructions for using the tools. They cover:

• The type catalog: all 21 document types with their virtual category, including research in vision and evidence in knowledge
• 25 pairwise type-selection rules for the types agents confuse (rnd vs research, spec vs doc, brs vs brd). Three closing tests decide the investigation types: a verdict closes an rnd, coverage of the declared scope closes a research, and an evidence is one material, never one statement
• How the informal requirements sources (mrd, brd, urd, prd) relate to the ISO specifications (brs, strs, syrs, srs)
• Document relations: the seven relation types on three axes (structural, evidential, temporal) with the direction of each, plus the advisory linking conventions for rnd and research, and the rule that a contradicts edge stays until the disputed document records the resolution in prose
• Tag format and filtering semantics
• The status values draft, accepted, and rejected, including the rnd verdict mapping (draft = investigating, accepted = proceed/refine, rejected = defer/stop), the research reading (accepted = the synthesis is current as of its last revision), and the evidence reading (accepted = a second reader confirmed the material and the extract)
• Naming conventions and slug rules
• When to create, update, delete, or search instead of creating
• When to call init_project (empty repo + user wants to create a document)

The server sends these instructions automatically. You don’t need to explain Archcore conventions to your agent.

Note

The instructions describe document types, not workflows. The Archcore plugin’s /archcore:plan skill assembles multi-document packages, including the sdd, sources, and iso expert paths, so workflow orchestration has a single owner. The MCP server dropped its five track prompts in v0.7.0, and prompts/list now answers with a JSON-RPC method-not-found.

Global sources

If your .archcore/settings.json declares a globals array, the MCP server mounts those external knowledge bases read-only and surfaces them through the read tools (list_documents, get_document, search_documents) alongside your local documents. Each global document is tagged source_kind: "global", read_only: true, and a source_id so the agent can tell it apart from local content. The write tools (create_document, update_document, remove_document) and add_relation refuse global paths.

Every declared global is mandatory. Before serving, the server checks each one and aborts startup on any of:

• a missing directory, with global source "<id>" not found at "<path>" — clone it before starting the MCP server;
• a path that exists but is not a directory;
• a directory that cannot be read;
• a path that resolves to the project’s own .archcore/ or an ancestor of it;
• two sources that resolve to the same path.

An existing, readable source with zero recognized documents is a startup warning on stderr, not an error. An invalid settings.json also aborts startup rather than serving with globals silently dropped.

This fail-fast keeps the agent from running against silently incomplete context. See Global sources for declaration, vendoring, and precedence rules.

Installation

Automatic (recommended)

archcore init

archcore init auto-detects installed agents and configures MCP for each one. It writes 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 the full list.

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 variable: ARCHCORE_PROJECT_ROOT=/absolute/path/to/repo archcore mcp

Precedence: --project > ARCHCORE_PROJECT_ROOT > current working directory. The named path must exist and be a directory. It does not need to contain .archcore/ yet, because init_project can bootstrap it from the session.

--project is trusted as given. When an implicitly resolved root (ARCHCORE_PROJECT_ROOT or the working directory) sits inside an AI-host plugin install cache, the server refuses to start, and the error tells you to pass --project with the real project root. Some hosts launch the server from their plugin cache instead of your workspace, and treating that cache as the project would read the plugin’s bundled files as your project.

Example MCP config that pins an absolute project root:

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

Following the session’s working directory

From CLI v0.8.2, a server whose root is not pinned follows the working directory the client reports. On a tool call the server asks the client for its roots (roots/list) with a 500 ms timeout and reuses the decision for 2 s. It switches to a reported root only when every check passes:

• The root is a file:// URI that maps to an existing directory.
• The directory is not a plugin install cache.
• The directory contains .archcore/.
• Every global source declared there resolves.

Otherwise the server keeps the current root and writes one line to stderr per distinct reason; CLI troubleshooting lists the reasons. A tool call never fails because of the query. The instructions the server returns at initialize come from the root at start time. --project <path> or ARCHCORE_PROJECT_ROOT pins the root for the process lifetime and turns the query off.

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 wire Archcore into three of your agent’s lifecycle events:

• SessionStart injects a recap of your .archcore/ directory before you type anything, so the agent can reference your decisions, rules, and patterns from the first message.
• PreToolUse blocks a direct write to an .archcore/ document, and injects the documents that constrain the file about to be edited.
• PostToolUse reports structure problems, relation cascades, and precision findings after a document mutation.

PreToolUse is the only event that can deny an action; the rest are advisory. See Hooks for per-host event names, matchers, and output formats.

Hooks are optional, and MCP tools work without them. With hooks installed, the agent receives project context without being asked for it.

How the session-start hook works

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 emits a bounded project recap: corpus counts, the current branch, documents in progress, recently accepted documents, the staleness advisory when it is due, the most frequent tags, and the relation count
5. The agent receives this project context alongside the conversation

The recap is capped rather than exhaustive, so its length tracks the line budget instead of the corpus size. See Hooks for the exact caps and the degradation rules.

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

archcore hooks install writes one archcore-owned entry per host and event. For Claude Code, the SessionStart entry lands in .claude/settings.json:

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

The PreToolUse and PostToolUse entries use their own matchers and land alongside this one. See Hooks for the full per-host wiring.

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, the session recap saves little. The write guard and post-write checks still apply.
• Your agent doesn’t support hooks. MCP tools work without them.
• You prefer explicit control. You 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 has the per-agent support matrix and config paths.
• Hooks documents the three lifecycle events and what each one outputs.
• MCP tools reference is the full API spec.