> For the complete documentation index, see [llms.txt](https://docs.holons.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.holons.io/software/mcp-server.md).

# MCP Server

> **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](https://modelcontextprotocol.io) 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](/software/harvest-dashboard.md) 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](#tool-domains)

## 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.

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

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

```bash
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.

```ts
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](/software/holosphere.md) 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:

```ts
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](/software/harvest-dashboard.md) 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](/software/holosphere.md), 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](/software/harvest-dashboard.md) — the monorepo that contains `@holons/mcp-ui` alongside the other UI shells.
* [HolonsBot](/software/holonsbot.md) — the Telegram interface that shares the same core.
* [HoloSphere](/software/holosphere.md) — the distributed substrate every tool reads from and writes to.
* [Glossary](/getting-started/glossary.md) — vocabulary for holons, federation, value equation, and friends.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.holons.io/software/mcp-server.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.