MCP Server

Model Context Protocol server exposing the entire holonic core as callable tools

Status: early — @holons/mcp-ui is at 0.1.0. The tool surface and identity model are working but may evolve. Pin versions in production deployments and expect the occasional breaking change until 1.0.

The @holons/mcp-ui package is the canonical interface between AI agents and the Holons ecosystem. It implements the Model Context Protocol and exposes every public function in @holons/core as an independently-callable tool. With it, a Claude (or any MCP-compatible) agent can fully participate in a holon: create tasks, vote on proposals, log expenses, calculate scores, publish to federation, manage DNA, and more—without any custom integration.

This is what makes a Claude agent a first-class holon member rather than an external assistant.

What it is

• Name: holons-mcp-ui

• Location: harvest/packages/mcp-ui/ in the Harvest monorepo

• Replaces: the legacy HTTP API (port 3101) and the duplicate MCP wrappers under telegram-ui/mcp

• Tool count: ~100 tools across 14 domain modules

Transports

The server supports two transports out of the box:

stdio (default). Used by Claude Desktop, IDE integrations, and any MCP client that spawns a subprocess.

node packages/mcp-ui/dist/index.js

SSE over HTTP. Used when the server needs to be reachable over the network.

node packages/mcp-ui/dist/index.js --port 3200

When --port is set, the server exposes:

Method	Path	Purpose
GET	/sse	Open an SSE stream for an MCP session
POST	/messages	Send a client message to the open SSE session
GET	/	Health check — returns { name, version }

Identity model

Every tool call resolves an actor—the user the call is acting on behalf of. This is what makes writes attributable to a specific person (or agent) inside HoloSphere.

interface Actor {
  id: string | number;
  first_name?: string;
  username?: string;
}

The actor is resolved from environment variables, with per-call overrides possible:

Variable	Purpose	Default
HOLONS_ACTOR_ID	Acting user ID	mcp-ui
HOLONS_ACTOR_NAME	Display name	MCP-UI
HOLONS_ACTOR_USERNAME	@handle	(unset)

For an AI agent to participate as a known person, set these to that person's identity before launching the server.

HoloSphere connection

The server connects to the HoloSphere substrate using two environment variables:

Variable	Purpose	Default
HOLONS_PEER	Gun relay URL	https://gun.holons.io/gun
HOLONS_APP	HoloSphere app namespace	Holons

Every read and write—across every tool—lands in this namespace, which is also where the web dashboard, Telegram bot, and CLI write. All interfaces share one source of truth.

Tool domains

Each domain module exposes one tool per public function in the corresponding @holons/core domain. Tools are registered automatically at startup; missing domain files are skipped silently.

Domain	Tools	What it does
tasks	10	Create, update, plan, complete quests; manage participants and appreciation
council	13	Full proposal lifecycle — create, save, vote, tally, block, check agreement
dna	12	Holon DNA sequences and chromosomes — get, save, add, remove, validate, seed
settings	11	Per-holon and per-user configuration, with hex-grid integration
library	11	Shared resource catalog — CRUD, tagging, search
users	9	User CRUD and appreciation tracking
scoring	9	Value-equation evaluation — per user, per action, breakdown, full-holon
holosphere	8	Direct substrate access — put, get, getAll, delete, subscribe, history
checklists	7	Recurring and role-based checklist operations
expenses	6	Log shared costs, split expenses, calculate per-member shares
shopping	6	Shopping list items shared across a holon
calendar	5	Events, recurring events, scheduling
federation	3	Cross-holon publishing, federated snapshots, hex-coded settings
commands	2	Meta — dispatch a named command, list available commands

Each tool is a thin wrapper around a @holons/core function. The dependency surface for each tool is just two functions, injected at registration:

interface ToolDeps {
  getHoloSphere: () => Promise<any>;
  resolveActor: (override?: Partial<Actor>) => Actor;
}

This means a tool is stateless from the MCP server's perspective—every call resolves its actor and substrate fresh.

How agents use it

The two common patterns:

Claude Desktop / IDE integration. Configure the MCP client to launch node packages/mcp-ui/dist/index.js over stdio with the desired HOLONS_ACTOR_* and HOLONS_PEER / HOLONS_APP env vars. Claude can now call any of the ~100 tools as part of normal conversation.

Embedded agent (@holons/ai-ui). The AI UI package inside Harvest wraps @holons/core functions directly as Claude tool-use loop calls. The MCP server is what makes the same capability available to external agents and clients.

Relationship to the rest of the stack

@holons/core  ──┬──>  harvest-web (SvelteKit dashboard)
                ├──>  @holons/telegram-ui (Telegraf bot)
                ├──>  @holons/text-ui (CLI/REPL)
                ├──>  @holons/ai-ui (in-process Claude loop)
                └──>  @holons/mcp-ui  ──>  external MCP clients
                                                │
                                                ▼
                                       Claude Desktop, IDEs,
                                       custom agents, …

Every interface ultimately writes to HoloSphere, so an action taken through the MCP server is identical—in attribution, scoring, and federation propagation—to one taken in the Telegram bot or the web app.

See also

• Harvest Dashboard — the monorepo that contains @holons/mcp-ui alongside the other UI shells.

• HolonsBot — the Telegram interface that shares the same core.

• HoloSphere — the distributed substrate every tool reads from and writes to.

• Glossary — vocabulary for holons, federation, value equation, and friends.