# Colibri MCP client examples

The live USB includes `/usr/local/bin/colibri-mcp`, an MCP server that exposes
Colibri status, glasspane snapshots, task lists, and skills to MCP-capable
editors/assistants.

Default posture is read-only. Colibri write tools are available only when the
MCP server process is launched with `COLIBRI_MCP_WRITE=1`. External MCP tool
calls are available only when launched with `COLIBRI_MCP_EXTERNAL_CALL=1`.

## Generic MCP client config

Most MCP clients accept a config shaped like `mcpServers`. Use one of:

- `mcp-readonly.json` — safe default profile
- `mcp-trusted-write.json` — explicit trusted profile with Colibri write tools enabled
- `mcp-external-call.json` — explicit trusted profile for external MCP tool calls
- `external-mcp.sample.json` — example external MCP server registry

## Quick checks

```sh
colibri-mcp tools
COLIBRI_MCP_WRITE=1 colibri-mcp tools
colibri-mcp socket-path
COLIBRI_MCP_EXTERNAL_CONFIG=/usr/local/share/clawdie-iso/mcp-examples/external-mcp.sample.json \
  colibri-mcp tools
```

## Claude Code example

If your Claude Code version supports `claude mcp add`, adapt:

```sh
claude mcp add colibri /usr/local/bin/colibri-mcp
claude mcp add colibri-write --env COLIBRI_MCP_WRITE=1 /usr/local/bin/colibri-mcp
```

If your version uses a JSON config file instead, copy the matching object from
`mcp-readonly.json` or `mcp-trusted-write.json`.

## Zed / Cursor example

Zed, Cursor, and other MCP-capable editors may use slightly different config
file paths or wrapper keys by version. The server object is the important part:

```json
{
  "command": "/usr/local/bin/colibri-mcp",
  "args": [],
  "env": {}
}
```

For a write-capable profile, add:

```json
{
  "env": { "COLIBRI_MCP_WRITE": "1" }
}
```

Only enable the write profile for trusted workspaces/sessions.

## External MCP server prototype

Newer Colibri builds can also use `colibri-mcp` as a small MCP host/client for
other stdio MCP servers. Copy the sample registry into the live config path and
edit it for the servers you actually want:

```sh
mdo -u root mkdir -p /usr/local/etc/colibri
mdo -u root cp /usr/local/share/clawdie-iso/mcp-examples/external-mcp.sample.json \
  /usr/local/etc/colibri/external-mcp.json
```

Read-only discovery works by default through these tools:

- `colibri_external_mcp_servers`
- `colibri_external_mcp_list_tools`

Calling external MCP tools requires an explicit trusted profile:

```json
{
  "command": "/usr/local/bin/colibri-mcp",
  "args": [],
  "env": {
    "COLIBRI_MCP_EXTERNAL_CALL": "1"
  }
}
```

External MCP tool calls are intentionally separate from `COLIBRI_MCP_WRITE=1`.
