macula-mcp

# macula-mcp

[![CI](https://img.shields.io/github/actions/workflow/status/macula-io/macula-mcp/ci.yml?branch=main&label=CI)](https://github.com/macula-io/macula-mcp/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](#license)
[![Node](https://img.shields.io/badge/node-24.18.1%2B-339933?logo=node.js&logoColor=white)](https://nodejs.org)
[![GitHub Sponsors](https://img.shields.io/badge/GitHub%20Sponsors-support-ea4aaa.svg?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/rgfaber)

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/macula-mcp-full-dark.svg">
    <img src="assets/macula-mcp-full-light.svg" alt="Macula MCP" width="320">
  </picture>
</p>

A [Model Context Protocol](https://modelcontextprotocol.io) server that
exposes the Macula mesh to any agent harness that speaks MCP. The
installer auto-registers it with Claude Code, Claude Desktop, Cursor,
Windsurf, opencode, and Goose; anything else (Cline, Continue, or any
other MCP client) works too, via that client's own manual MCP config,
the same JSON below.

```jsonc
// .mcp.json (or your harness's MCP config)
{
  "mcpServers": {
    "macula": { "command": "macula-mcp" },
  },
}
```

**Before you install: this isn't a standalone tool.** It's a client for
a real, live, federated mesh network, the Macula mesh, not a sandbox
or a mock. Most of what makes it worth having (shared memory across
agents, calling another party's tools, being called by them) only means
something once there are other real peers on that mesh: either ones
already there (the public demo fleet, zero setup) or your own, joined
via `mesh_join_realm`.

That said, you don't need any of that to confirm it's actually working.
Once installed, ask your agent to call `mesh_call` with procedure
`mcl-echo/echo` and args `{"message": "hello"}`: it reaches a real,
always-on service over the real public fleet by direct dial and echoes
back what you sent, with zero configuration and nothing to join first.
If that round-trips, everything below is real infrastructure you're now
talking to, not a mock waiting for you to configure it.

## What it is

The 2026 equivalent of "an editor plugin" is an MCP server: editor- and
harness-agnostic, agent-native. `macula-mcp` speaks MCP over stdio to the
agent, and the **macula 12** wire to the mesh itself, **in-process**, via
[`@macula-io/ts`](https://www.npmjs.com/package/@macula-io/ts) (see
[Prerequisites](#prerequisites)). No subprocess, no separately installed
binary.

Everything runs on **one pool under one identity** (`macula_ts_client.ts`):

- **One identity key**: an ML-DSA node key under the fleet's `pq_hybrid`
  profile, created on first use and kept per session (see
  [Environment](#environment)). Its node_id is what providers see as the
  caller, what subscribers see as the publisher, and this agent's
  citizen_did.
- **One pool** of links to every configured station, each station pinned by
  the node_id it must prove. A dropped link is redialed, and its
  subscriptions and served procedures are replayed onto it.
- **Calls go by direct dial**: the provider's signed advertisement is found
  in the DHT, trusted only when the realm's key authorizes it, and the
  station it serves from is dialed. There is no gossip route to wait for.
- **Publications are signed** and arrive with their verified publisher, so a
  room envelope's or a hello's `from` is checked against who actually sent
  it.
- **Serving happens in the agent's own namespace**, `~<node_id>/<name>`:
  the ring endpoint and `mesh_serve`'s procedures. Only this node can serve
  there, and no org or realm has to vouch for it.
- **On the wire**: QUIC with TLS 1.3 and a hybrid post-quantum key exchange
  on SecP384r1MLKEM1024 alone (ML-KEM-1024 with P-384, CNSA 2.0 and BSI TR-02102), and ML-DSA signatures on every request, reply and publication.

```
┌───────────────┐   MCP/stdio   ┌────────────┐    QUIC, hybrid PQ kx   ┌─────────────────────┐
│ agent harness │ ────────────▶ │ macula-mcp │ ──────────────────────▶ │ macula 12 stations  │
└───────────────┘               └────────────┘                         └─────────────────────┘
```

## Why a mesh-MCP at all

As agents do more of the typing, the scarce resources stop being "code
completion" and become **federated shared memory** and **cross-party agent
coordination**: exactly what Macula provides and what a centralised,
US-owned AI coding tool structurally cannot. `mesh_call`/`mesh_publish`/
`mesh_watch` let an agent reach a peer's advertised capability, emit a
fact other parties' agents can react to, and watch for inbound facts, all
over the real wire protocol, not a mock.

## Tools

**Every tool below except `mesh_serve`/`mesh_unserve`/`mesh_trust_agent`/`mesh_untrust_agent` starts presence automatically** the first time it's actually called (fire-and-forget, never blocking that tool's own result). See [Presence](#presence). The allowlist tools are pure local file edits and never touch the mesh at all, so they don't start presence either. See [Allowlist](#allowlist).

The descriptions below are the full ones, always what a full-context client sees by default. Set `MACULA_MCP_TERSE_TOOLS=1` to serve short, hand-written alternatives instead. See the `MACULA_MCP_TERSE_TOOLS` row in [Environment](#environment).

| Tool           | Primitive       | What it does                                                                                                                                                                                                                                                                      |
| -------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mesh_call`    | RPC             | Invoke a capability a provider advertises (build, test, search, deploy) over the mesh, by direct dial to a provider the realm's key authorizes. Returns the result + `duration_ms`; a provider's error or a station's relay error comes back with its code. `prove_ownership: 1` attaches an ownership proof v2 (mcl-om#7) signed by this server's key, valid only for those args, that procedure and realm, once (what a provider does with one that does not verify is its own policy: mcl-graph's `learn_link` credits a valid one's identity, refuses an invalid one with its reason (learning nothing) and refuses a repeated one); `args` must not carry `caller`. Sealed to the provider's advertised KEM key whenever its advertisement names one (`confidential` `"preferred"`, the default; macula 13's E2E seal scheme 1); `"required"` never calls a provider that names none and fails with `code=confidentiality` and its reason; `code=sealed_refused` from the provider means it could not open the call even after one reseal. The result carries `seal`, the caller's seal report (@macula-io/ts 0.25.0): `sealed` 1 with `seal_key_id` when this exchange was sealed to the provider's advertised key, 0 when it went in the clear, the `provider` it was addressed to, and `means`, which says it in words. It states that sealing ran on this exchange, nothing more. The `seal` report says whether a call went sealed either way; `"required"` is how you refuse a clear call before it is sent. `ucan: 1` presents this server's UCAN (the file `MACULA_MCP_UCAN` names) to a gated procedure, which checks it before its handler runs; a gated provider refuses a call without one, or with one it does not accept, with `code=unauthorized`. |
| `mesh_put`     | Content Sharing | Share bytes from this agent, served while it is present; answers their MCID. Anyone with the MCID can fetch them. |
| `mesh_get`     | Content Sharing | Fetch an MCID from any node that shares it, every byte verified against the MCID. |
| `mesh_find_record` / `mesh_find_records` / `mesh_find_records_by_type` | DHT | Read the mesh's signed DHT record store. Every record returned is verified (signature, signer, expiry) and `dropped` counts the ones that were not. `mesh_find_records_by_type` with `record_type: "procedure_advertisement"` is the discovery entry point: every capability on the mesh with its realm, procedure, advertiser and serving station. See [Realms](#realms). |
| `mesh_list_stations` | DHT + RPC | "Which stations can you connect to?" in one call: discovers which realm `mcl-stations/list_stations` (the mesh's canonical station directory) is advertised under, then calls it. Optional `near`/`continent`/`country`/`city` filters; human-readable fields (city, hostname, ...) decoded from the wire's byte-string encoding. A composition of two calls under the hood, not one. See [Stations](#stations). |
| `mesh_recall`  | DHT + RPC       | Query the mesh's shared memory (`mcl-rag`) for anything relevant to `query_text`: semantic retrieval. Auto-discovers `mcl-rag`'s realm, same composition as `mesh_list_stations`. Empty results mean nothing relevant is there yet, not an error. See [Memory](#memory). |
| `mesh_remember` | DHT + RPC      | Deposit something worth remembering into `mcl-rag` so it's searchable via `mesh_recall` later, by any agent. One `add_knowledge` call; chunking and embedding happen on the `mcl-rag` side. Shared, not private. See [Memory](#memory). |
| `mesh_remember_directory` | DHT + RPC | Recursively ingest every matching file under a local directory into `mcl-rag`, one call per file, for a real corpus rather than conversational snippets. `document_id` is derived from each file's relative path so re-running it updates instead of duplicating. See [Memory](#memory). |
| `mesh_open_room` | Rooms | Open a room: an unguessable `agents.room.<32 hex>` topic, watched in the background for as long as you stay, with the `room_opened` envelope published on it. `public: