---
title: Core MCP
scope: 3dmk
type: documentation
subject: core-mcp
group: Code/Schema
status: current
version: "2.1.3"
source: https://3dmk.com/documentation#core-mcp
author: Nick Olson
contact:
  email: 3dmk@3dmk.com
  site: https://3dmk.com
license: CC BY 4.0
license_url: https://creativecommons.org/licenses/by/4.0/
attribution: Nick Olson, 3dmk.com
---

# Core MCP

Core Model Context Protocol (MCP) is the tool server that every Claude session in the development environment talks to. MCP is the standard way an agent calls outside tools. One Rust program serves 107 tools in 11 groups. Some run on the developer’s machine, and the rest forward to the services that own the data.

*Figure: One local server, two relays in priority order. The drawing is on the page.*

## Role

Core MCP gives an agent one place to reach the whole environment. The agent sees a single list of tools and never needs to know where a tool runs. File search, Git, Docker, and PowerShell run beside the agent on the developer’s machine. Documentation, work tracking, notes, and session records live in services. Core MCP forwards those calls.

The program runs in two modes from the same build.

| Mode | Where it runs | Job |
|---|---|---|
| Proxy mode | Each developer machine, started by Claude | Serves every tool over standard input and output, runs local tools, and forwards the rest |
| Service mode | A container or a background service on a server | Accepts forwarded calls over HTTP and passes each one to the service that owns it |

Service mode runs no local tools. It has no file access, no Git, no shell, and no Docker access. It needs only the network, so its container needs no mounted volumes.

## Proxy MCP servers

The two proxy MCP servers in the diagram are service mode instances on two different servers. The local Core MCP holds them as an ordered list. Each forwarded call goes to the first one that answers.

A proxy maps each tool name to one request on the service behind it. Seele tools go to Seele, and Scrolls tools go to Scrolls. Notepad and session tools go to the NervHQ service. The proxy looks up Seele and Scrolls in Consul on every call, so a moved service needs no redeploy.

## How proxies are added

Two mechanisms add a proxy, and both leave the tool list unchanged:

- Relay list: the local server reads an ordered list of proxy addresses when Claude starts it

- Registered hosts: any host in the Registry with a Core MCP address becomes a target on the next call

The relay list sets failover. When a proxy fails to connect, Core MCP tries the next one and skips the failed proxy for 30 seconds. Calls return to the first proxy once it answers again. An error from a live proxy comes back as it is and never fails over.

Registered hosts need no restart. Core MCP reads the host from the Registry on each call that names one. A new server joins with one `registry_host_add` call that includes its Core MCP address. A call that names an unknown host returns the hosts that accept forwarded calls.

## Running a tool on another host

Most tools take an optional `remote_host` argument. Without it, a tool runs where its group runs. With it, Core MCP looks up that host in the Registry and sends the call to the Core MCP address on the host’s record.

The named host answers only the tools its own Core MCP serves. A relay in service mode serves the forwarded groups, so a forwarded tool skips the relay list and goes to that host. Registry additions and `bootstrap` run only where the agent runs.

## Tool groups

Each group covers one area of the environment. The table gives each group’s tool count, where its tools run, and what they do.

| Group | Tools | Runs | What it does |
|---|---|---|---|
| Registry | 14 | Local, against the Registry service | Reads and changes the records for themes, projects, sources, and hosts, plus code snapshots |
| Global docs | 2 | Local, on the developer’s machine | Reads and writes documents in the documentation repositories, with front matter kept current |
| Seele | 4 | Forwarded through a proxy to Seele | Searches, reads, writes, and imports documentation nodes |
| Scrolls | 50 | Forwarded through a proxy to Scrolls | Creates, reads, updates, closes, and deletes work items from themes down to subtasks, plus agents and progress views |
| Notepad | 6 | Forwarded through a proxy to NervHQ | Keeps short notes by scope and key, with bulk writes and cleanup |
| Session | 7 | Forwarded through a proxy to NervHQ | Registers active sessions, takes heartbeats, closes stale sessions, and reads recorded ones |
| Git | 8 | Local, on the developer’s machine | Reads repository state and history, and stages, commits, and pushes changes |
| Code and files | 4 | Local, on the developer’s machine | Searches file contents, lists directories, builds a structural code snapshot, and runs SQL against PostgreSQL |
| Ops | 6 | Local, except the session record, which goes through a proxy to NervHQ | Runs PowerShell, starts a bootstrap, sets up a repository, finds stale containers, and records a session |
| Publishing | 1 | Local, where the publishing command line is installed | Passes any command to the publishing command line and returns its JSON result |
| Docker | 5 | Local, against any Docker host in the Registry | Lists and inspects containers, reads logs, runs lifecycle actions, and runs Compose commands |

Tools load on demand by group, so a session carries only the groups its work needs. The `publishing` tool passes its arguments through unchanged, so a new publishing command needs no change to Core MCP.

## Builds

The default build turns on every tool. The two document tools sit behind build features, so a build can drop either one. A dropped tool stays in the list and returns an error that names the missing feature.

A secondary development machine uses a build without the document tools. Every other tool stays on, and its forwarded tools reach the same proxies as the main machine.