mcpctl/README.md

# mcpctl

**kubectl for MCP servers.** A management system for [Model Context Protocol](https://modelcontextprotocol.io) servers — define, deploy, and connect MCP servers to Claude using familiar kubectl-style commands.

```
mcpctl get servers
NAME             TRANSPORT   REPLICAS   DOCKER IMAGE                              DESCRIPTION
grafana          STDIO       1          grafana/mcp-grafana:latest                Grafana MCP server
home-assistant   SSE         1          ghcr.io/homeassistant-ai/ha-mcp:latest    Home Assistant MCP
docmost          SSE         1          10.0.0.194:3012/michal/docmost-mcp:latest Docmost wiki MCP
```

## What is this?

mcpctl manages MCP servers the same way kubectl manages Kubernetes pods. You define servers declaratively in YAML, group them into projects, and connect them to Claude Code or any MCP client through a local proxy.

**The architecture:**

```
Claude Code  <--STDIO-->  mcplocal (local proxy)  <--HTTP-->  mcpd (daemon)  <--Docker-->  MCP servers
```

- **mcpd** — the daemon. Runs on a server, manages MCP server containers (Docker/Podman), stores configuration in PostgreSQL.
- **mcplocal** — local proxy. Runs on your machine, presents a single MCP endpoint to Claude that merges tools from all your servers. Handles namespacing (`grafana/search_dashboards`), plugin execution (gating, content pipelines), and prompt delivery.
- **mcpctl** — the CLI. Talks to mcpd (via mcplocal or directly) to manage everything.

## Quick Start

### 1. Install

```bash
# From RPM repository (Fedora/RHEL)
sudo tee /etc/yum.repos.d/mcpctl.repo <<'EOF'
[mcpctl]
name=mcpctl
baseurl=https://mysources.co.uk/api/packages/michal/rpm
enabled=1
gpgcheck=0
EOF
sudo dnf install mcpctl

# Or build from source
git clone https://mysources.co.uk/michal/mcpctl.git
cd mcpctl
pnpm install
pnpm build
pnpm rpm:build   # requires bun and nfpm
```

### 2. Connect to a daemon

```bash
# Login to an mcpd instance
mcpctl login --mcpd-url http://your-server:3000

# Check connectivity
mcpctl status
```

### 3. Create your first secret

Secrets store credentials that servers need — API tokens, passwords, etc.

```bash
mcpctl create secret grafana-creds \
  --data GRAFANA_URL=http://grafana.local:3000 \
  --data GRAFANA_SERVICE_ACCOUNT_TOKEN=glsa_xxxxxxxxxxxx
```

### 4. Create your first server

Browse available templates, then create a server from one:

```bash
mcpctl get templates                  # List available server blueprints
mcpctl describe template grafana      # See required env vars, health checks, etc.

mcpctl create server my-grafana \
  --from-template grafana \
  --env-from-secret grafana-creds
```

mcpd pulls the image, starts a container, and keeps it running. Check on it:

```bash
mcpctl get instances            # See running containers
mcpctl logs my-grafana          # View server logs
mcpctl describe server my-grafana  # Full details
```

### 5. Create a project

A project groups servers together and configures how Claude interacts with them.

```bash
mcpctl create project monitoring \
  --description "Grafana dashboards and alerting" \
  --server my-grafana \
  --proxy-model content-pipeline
```

### 6. Connect Claude Code

Generate the `.mcp.json` config for Claude Code:

```bash
mcpctl config claude --project monitoring
```

This writes a `.mcp.json` that tells Claude Code to connect through mcplocal. Restart Claude Code and your Grafana tools appear:

```
mcpctl console monitoring   # Preview what Claude sees
```

### Connect prime-agent

Prime-agent (Claude's open-source counterpart) talks to the same proxy MCP
gateway over HTTP rather than stdio. Register a project and sync its skills
into `~/.prime/agent/`:

```bash
mcpctl config prime-agent --project monitoring
```

This:

1. Provisions the project's bearer credential in `~/.prime/agent/auth.json`
   (`mcp:monitoring`, written 0600) — either from `--token <pat>`, an existing
   entry that is still active server-side, or a freshly minted project token.
   This happens first: if no credential can be provisioned the command stops
   here with a non-zero exit and leaves `settings.json` alone, so the project
   you are currently on keeps working.
2. Registers the proxy MCP gateway in `~/.prime/agent/settings.json` as
   `mcpServers.monitoring = { "type": "http", "url": "https://mcp.ad.itaz.eu/projects/monitoring/mcp" }`
   (merging with any existing servers and preserving all other settings), and
   unmounts the previously active mcpctl project so exactly one is live.
   Servers you configured by hand are never touched.
3. Writes a `.mcpctl-project` marker (only if none exists higher up, and never
   from `$HOME`) so later syncs resolve the project. Skip with `--skip-marker`.
4. Syncs the project's skills into `~/.prime/agent/skills/<name>/` as markdown
   skills. The shared tree is ownership-tracked per project: it never deletes
   another project's skills or an untracked hand-authored skill.
5. Installs a `/mcpctl` project-switcher extension into
   `~/.prime/agent/extensions/` so you can switch mcpctl projects from inside
   the prime-agent UI (skip with `--skip-extension`).

Re-sync later with:

```bash
mcpctl skills sync --agent prime-agent --project monitoring
```

Skip individual steps as needed:

```bash
mcpctl config prime-agent --project monitoring --token mcpctl_pat_xxx   # provide token, don't mint
mcpctl config prime-agent --project monitoring --skip-skills            # don't sync skills
mcpctl config prime-agent --project monitoring --skip-extension         # don't install /mcpctl switcher
mcpctl config prime-agent --project monitoring --skip-marker            # don't touch .mcpctl-project here
```

The `/mcpctl` switcher runs with `--skip-extension --skip-marker`, so switching
projects from inside prime-agent never re-scopes whichever repository
prime-agent happened to be started in.

See [docs/prime-agent-extension.md](docs/prime-agent-extension.md) for full details.

Preview the change without writing anything:

```bash
mcpctl config prime-agent --project monitoring --dry-run
```

`config claude` registers in **user scope** by default — one `mcpctl` MCP server
in `~/.claude.json` that applies in every directory and window, so you wire it
once rather than per checkout. Use `--scope project` (or `-o`) for a repo that
wants its own pinned project.

Inside Claude Code:

- `/mcpctl [project]` — switch projects, then reconnect the `mcpctl` server from
  `/mcp` (no restart)
- the active project shows in the status line at the bottom of the screen

See [docs/claude-integration.md](docs/claude-integration.md) for full details.

### Connect pi

[pi](https://github.com/earendil-works/pi) does not support MCP, but it supports
**extensions** and **skills**. mcpctl ships a native pi integration that talks
JSON-RPC directly to mcplocal over HTTP — no MCP library, no `~/.claude`
dependency, so it keeps working even if you drop Claude entirely.

```bash
mcpctl config pi --project monitoring
```

This installs the `mcpctl` pi extension into `~/.pi/agent/extensions/mcpctl/`,
registers it (plus a pi skills dir) in `~/.pi/agent/settings.json`, persists the
active project in `~/.mcpctl/pi-state.json`, and runs an initial skills sync into
`~/.pi/agent/skills/`. Then start pi and the project's MCP tools are registered as
native pi tools (`mc_<project>_<tool>`).

Inside pi:

- `/mcpctl` — status, **switch project** (from the GUI), refresh tools, sync skills
- gated projects auto-ungate: call `begin_session` once and the full tool set opens
- re-sync with `mcpctl skills sync --agent pi --project monitoring`

See [docs/pi-extension.md](docs/pi-extension.md) for full details.

### Connect opencode

[opencode](https://opencode.ai) supports MCP natively *and* exposes an API for
its own MCP registry, so mcpctl mounts the project through the running app —
which means you can **switch projects from the TUI without restarting**.

```bash
mcpctl config opencode --project monitoring
```

This mints (or reuses) the project's gateway token into
`~/.mcpctl/opencode-state.json` (0600 — the token never lands in
`opencode.json`), installs a server plugin into
`~/.config/opencode/plugin/mcpctl.ts` and a TUI plugin into
`~/.config/opencode/mcpctl/`, registers the latter in
`~/.config/opencode/tui.json`, and syncs skills into
`~/.config/opencode/skill/`.

Inside opencode:

- `/mcpctl` (or `<leader>m`) — **switch project** from a filterable picker;
  takes effect on the next turn, no restart
- `/mcpctl-status` — active project, mount state, gateway URL
- `/mcpctl-skills` — re-sync this project's skills
- the active project shows as `mcpctl:<project>` in the prompt footer, next to
  the model name

Skip individual steps as needed:

```bash
mcpctl config opencode --project monitoring --token mcpctl_pat_xxx  # provide token, don't mint
mcpctl config opencode --project monitoring --skip-skills           # don't sync skills
mcpctl config opencode --project monitoring --skip-plugin           # state only, leave plugins alone
mcpctl config opencode --project monitoring --skip-marker           # don't touch .mcpctl-project here
mcpctl config opencode --project monitoring --dry-run               # print the plan, write nothing
```

Re-sync skills on their own with
`mcpctl skills sync --agent opencode --project monitoring`.

See [docs/opencode-extension.md](docs/opencode-extension.md) for full details.

### Run Claude Code on the homelab LLM

The homelab gateway (LiteLLM in front of vLLM) already serves the Anthropic
Messages API, so Claude Code can talk to it directly — no bridge:

```bash
claude-vllm --init                          # write ~/.config/mcpctl/claude-vllm.jsonc (0600)
claude-vllm                                 # use it
claude-vllm --model deepseek-v4-max
claude-vllm --list                          # show what it would use
claude-vllm -- -p "summarise this repo"     # args after -- go to claude
```

It reads its own config (shaped like `opencode.jsonc`, but a separate file),
falling back to `~/.pi/agent` or `~/.prime/agent` so it works before you have
written one. The key may be a literal in the 0600 file, `${ENV_VAR}`, or an env
var name — it is never stored in the tool.

See [docs/claude-vllm.md](docs/claude-vllm.md), including why routing this
through mcpctl would add surface without adding capability.

## Declarative Configuration

Everything can be defined in YAML and applied with `mcpctl apply`:

```yaml
# infrastructure.yaml
secrets:
  - name: grafana-creds
    data:
      GRAFANA_URL: "http://grafana.local:3000"
      GRAFANA_SERVICE_ACCOUNT_TOKEN: "glsa_xxxxxxxxxxxx"

servers:
  - name: my-grafana
    description: "Grafana dashboards and alerting"
    fromTemplate: grafana
    envFrom:
      - secretRef:
          name: grafana-creds

projects:
  - name: monitoring
    description: "Infrastructure monitoring"
    proxyModel: content-pipeline
    servers:
      - my-grafana
```

```bash
mcpctl apply -f infrastructure.yaml
```

Round-trip works too — export, edit, re-apply:

```bash
mcpctl get all --project monitoring -o yaml > state.yaml
# edit state.yaml...
mcpctl apply -f state.yaml
```

## Plugin System (ProxyModel)

ProxyModel is mcpctl's plugin system. Each project is assigned a **plugin** that controls how Claude interacts with its servers.

There are two layers:
- **Plugins** — TypeScript hooks that intercept MCP requests/responses (gating, tool filtering, etc.)
- **Pipelines** — YAML-defined content transformation stages (pagination, summarization, etc.)

### Built-in Plugins

Plugins compose through inheritance. A plugin can `extend` another plugin and inherit all its hooks:

```
gate                   → gating only (begin_session + prompt delivery)
content-pipeline       → content transformation only (pagination, section-split)
default                → extends both gate AND content-pipeline (inherits all hooks from both)
```

| Plugin | Gating | Content pipeline | Description |
|--------|:-:|:-:|---|
| **gate** | Yes | No | `begin_session` gate with prompt delivery |
| **content-pipeline** | No | Yes | Content transformation (paginate, section-split) |
| **default** | Yes | Yes | Extends both — gate + content pipeline combined |

The `default` plugin doesn't reimplement anything — it inherits the gating hooks from `gate` and the content hooks from `content-pipeline`. Custom plugins can extend built-in ones the same way.

**Gating** means Claude initially sees only a `begin_session` tool. After calling it with a task description, relevant prompts are delivered and the full tool list is revealed. This keeps Claude's context focused.

```bash
# Gated with content pipeline (default — extends gate + content-pipeline)
mcpctl create project home --server my-ha --proxy-model default

# Ungated, content pipeline only
mcpctl create project tools --server my-grafana --proxy-model content-pipeline

# Gated only, no content transformation
mcpctl create project docs --server my-docs --proxy-model gate
```

### Plugin Hooks

Plugins intercept MCP requests/responses at specific lifecycle points. When a plugin extends another, it inherits all the parent's hooks. If both parent and child define the same hook, the child's version wins.

| Hook | When it fires |
|------|--------------|
| `onSessionCreate` | New MCP session established |
| `onSessionDestroy` | Session ends |
| `onInitialize` | MCP `initialize` request — can inject instructions |
| `onToolsList` | `tools/list` — can filter/modify tool list |
| `onToolCallBefore` | Before forwarding a tool call — can intercept |
| `onToolCallAfter` | After receiving tool result — can transform |
| `onResourcesList` | `resources/list` — can filter resources |
| `onResourceRead` | `resources/read` — can intercept resource reads |
| `onPromptsList` | `prompts/list` — can filter prompts |
| `onPromptGet` | `prompts/get` — can intercept prompt reads |

When multiple parents define the same hook, lifecycle hooks (`onSessionCreate`, `onSessionDestroy`) chain sequentially. All other hooks require the child to override — otherwise it's a conflict error.

### Content Pipelines

Content pipelines transform tool results through ordered stages before delivering to Claude:

| Pipeline | Stages | Use case |
|----------|--------|----------|
| **default** | `passthrough` → `paginate` (8KB pages) | Safe pass-through with pagination for large responses |
| **subindex** | `section-split` → `summarize-tree` | Splits large content into sections, returns a summary index |

#### How `subindex` Works

1. Upstream returns a large tool result (e.g., 50KB of device states)
2. `section-split` divides content into logical sections (2KB-15KB each)
3. `summarize-tree` generates a compact index with section summaries (~200 tokens each)
4. Client receives the index and can request specific sections via `_section` parameter

### Configuration

Set per-project:

```yaml
kind: project
name: home-automation
proxyModel: default
servers:
  - home-assistant
  - unifi-network
```

Via CLI:

```bash
mcpctl create project monitoring --server grafana --proxy-model content-pipeline
```

### Custom ProxyModels

Place YAML files in `~/.mcpctl/proxymodels/` to define custom pipelines:

```yaml
kind: ProxyModel
metadata:
  name: my-pipeline
spec:
  stages:
    - type: section-split
      config:
        minSectionSize: 1000
        maxSectionSize: 10000
    - type: summarize-tree
      config:
        maxTokens: 150
        maxDepth: 2
  appliesTo: [toolResult, prompt]
  cacheable: true
```

Inspect available plugins and pipelines:

```bash
mcpctl get proxymodels              # List all plugins and pipelines
mcpctl describe proxymodel default  # Pipeline details (stages, controller)
mcpctl describe proxymodel gate     # Plugin details (hooks, extends)
```

### Custom Stages

Drop `.js` or `.mjs` files in `~/.mcpctl/stages/` to add custom transformation stages. Each file must `export default` an async function matching the `StageHandler` contract:

```javascript
// ~/.mcpctl/stages/redact-keys.js
export default async function(content, ctx) {
  // ctx provides: contentType, sourceName, projectName, sessionId,
  //               originalContent, llm, cache, log, config
  const redacted = content.replace(/([A-Z_]+_KEY)=\S+/g, '$1=***');
  ctx.log.info(`Redacted ${content.length - redacted.length} chars of secrets`);
  return { content: redacted };
}
```

Stages loaded from disk appear as `local` source. Use them in a custom ProxyModel YAML:

```yaml
kind: ProxyModel
metadata:
  name: secure-pipeline
spec:
  stages:
    - type: redact-keys        # matches filename without extension
    - type: section-split
    - type: summarize-tree
```

**Stage contract reference:**

| Field | Type | Description |
|-------|------|-------------|
| `content` | `string` | Input content (from previous stage or raw upstream) |
| `ctx.contentType` | `'toolResult' \| 'prompt' \| 'resource'` | What kind of content is being processed |
| `ctx.sourceName` | `string` | Tool name, prompt name, or resource URI |
| `ctx.originalContent` | `string` | The unmodified content before any stage ran |
| `ctx.llm` | `LLMProvider` | Call `ctx.llm.complete(prompt)` for LLM summarization |
| `ctx.cache` | `CacheProvider` | Call `ctx.cache.getOrCompute(key, fn)` to cache expensive results |
| `ctx.log` | `StageLogger` | `debug()`, `info()`, `warn()`, `error()` |
| `ctx.config` | `Record<string, unknown>` | Config values from the ProxyModel YAML |

**Return value:**

```typescript
{ content: string; sections?: Section[]; metadata?: Record<string, unknown> }
```

If `sections` is returned, the framework stores them and presents a table of contents to the client. The client can drill into individual sections via `_resultId` + `_section` parameters on subsequent tool or prompt calls.

### Section Drill-Down

When a stage (like `section-split`) produces sections, the pipeline automatically:

1. Replaces the full content with a compact table of contents
2. Appends a `_resultId` for subsequent drill-down
3. Stores the full sections in memory (5-minute TTL)

Claude then calls the same tool (or `prompts/get`) again with `_resultId` and `_section` parameters to retrieve a specific section. This works for both tool results and prompt responses.

```
# What Claude sees (tool result):
3 sections (json):
[users] Users (4K chars)
[config] Config (1K chars)
[logs] Logs (8K chars)

_resultId: pm-abc123 — use _resultId and _section parameters to drill into a section.

# Claude drills down:
→ tools/call: grafana/query  { _resultId: "pm-abc123", _section: "logs" }
← [full 8K content of the logs section]
```

### Hot-Reload

Stages and ProxyModels reload automatically when files change — no restart needed.

- **Stages** (`~/.mcpctl/stages/*.js`): File watcher with 300ms debounce. Add, edit, or remove stage files and they take effect on the next tool call.
- **ProxyModels** (`~/.mcpctl/proxymodels/*.yaml`): Re-read from disk on every request, so changes are always picked up.

Force a manual reload via the HTTP API:

```bash
curl -X POST http://localhost:3200/proxymodels/reload
# {"loaded": 3}

curl http://localhost:3200/proxymodels/stages
# [{"name":"passthrough","source":"built-in"},{"name":"redact-keys","source":"local"},...]
```

### Built-in Stages Reference

| Stage | Description | Key Config |
|-------|------------|------------|
| `passthrough` | Returns content unchanged | — |
| `paginate` | Splits large content into numbered pages | `pageSize` (default: 8000 chars) |
| `section-split` | Splits content into named sections by structure (headers, JSON keys, code boundaries) | `minSectionSize` (500), `maxSectionSize` (15000) |
| `summarize-tree` | Generates LLM summaries for each section | `maxTokens` (200), `maxDepth` (2) |

`section-split` detects content type automatically:

| Content Type | Split Strategy |
|-------------|---------------|
| JSON array | One section per array element, using `name`/`id`/`label` as section ID |
| JSON object | One section per top-level key |
| YAML | One section per top-level key |
| Markdown | One section per `##` header |
| Code | One section per function/class boundary |
| XML | One section per top-level element |

### Pause Queue (Model Studio)

The pause queue lets you intercept pipeline results in real-time — inspect what the pipeline produced, edit it, or drop it before Claude receives the response.

```bash
# Enable pause mode
curl -X PUT http://localhost:3200/pause -d '{"paused":true}'

# View queued items (blocked tool calls waiting for your decision)
curl http://localhost:3200/pause/queue

# Release an item (send transformed content to Claude)
curl -X POST http://localhost:3200/pause/queue/<id>/release

# Edit and release (send your modified content instead)
curl -X POST http://localhost:3200/pause/queue/<id>/edit -d '{"content":"modified content"}'

# Drop an item (send empty response)
curl -X POST http://localhost:3200/pause/queue/<id>/drop

# Release all queued items at once
curl -X POST http://localhost:3200/pause/release-all

# Disable pause mode
curl -X PUT http://localhost:3200/pause -d '{"paused":false}'
```

The pause queue is also available as MCP tools via `mcpctl console --stdin-mcp`, which gives Claude direct access to `pause`, `get_pause_queue`, and `release_paused` tools for self-monitoring.

## LLM Providers

ProxyModel stages that need LLM capabilities (like `summarize-tree`) use configurable providers. Configure in `~/.mcpctl/config.yaml`:

```yaml
llm:
  - name: vllm-local
    type: openai-compatible
    baseUrl: http://localhost:8000/v1
    model: Qwen/Qwen3-32B
  - name: anthropic
    type: anthropic
    model: claude-sonnet-4-20250514
    # API key from: mcpctl create secret llm-keys --data ANTHROPIC_API_KEY=sk-...
```

Providers support **tiered routing** (`fast` for quick summaries, `heavy` for complex analysis) and **automatic failover** — if one provider is down, the next is tried.

```bash
# Check active providers
mcpctl status   # Shows LLM provider status

# View provider details
curl http://localhost:3200/llm/providers
```

## Pipeline Cache

ProxyModel pipelines cache LLM-generated results (summaries, section indexes) to avoid redundant API calls. The cache is persistent across mcplocal restarts.

### Namespace Isolation

Each combination of **LLM provider + model + ProxyModel** gets its own cache namespace:

```
~/.mcpctl/cache/openai--gpt-4o--content-pipeline/
~/.mcpctl/cache/anthropic--claude-sonnet-4-20250514--content-pipeline/
~/.mcpctl/cache/vllm--qwen-72b--subindex/
```

Switching LLM providers or models automatically uses a fresh cache — no stale results from a different model.

### CLI Management

```bash
# View cache statistics (per-namespace breakdown)
mcpctl cache stats

# Clear all cache entries
mcpctl cache clear

# Clear a specific namespace
mcpctl cache clear openai--gpt-4o--content-pipeline

# Clear entries older than 7 days
mcpctl cache clear --older-than 7
```

### Size Limits

The cache enforces a configurable maximum size (default: 256MB). When exceeded, the oldest entries are evicted (LRU). Entries older than 30 days are automatically expired.

Size can be specified as bytes, human-readable units, or a percentage of the filesystem:

```typescript
new FileCache('ns', { maxSize: '512MB' })   // fixed size
new FileCache('ns', { maxSize: '1.5GB' })   // fractional units
new FileCache('ns', { maxSize: '10%' })     // 10% of partition
```

## Resources

| Resource | What it is | Example |
|----------|-----------|---------|
| **server** | MCP server definition | Docker image + transport + env vars |
| **instance** | Running container (immutable) | Auto-created from server replicas |
| **secret** | Key-value credentials | API tokens, passwords |
| **template** | Reusable server blueprint | Community server configs |
| **project** | Workspace grouping servers | "monitoring", "home-automation" |
| **llm** | Server-managed LLM provider | OpenAI / Anthropic / vLLM endpoint + key |
| **agent** | LLM persona pinned to one Llm | "I review security; ask after each major change" |
| **prompt** | Curated content for Claude | Instructions, docs, guides |
| **promptrequest** | Pending prompt proposal | LLM-submitted, needs approval |
| **rbac** | Access control bindings | Who can do what |
| **serverattachment** | Server-to-project link | Virtual resource for `apply` |

## Agents

An **Agent** is an LLM persona — a pinned `Llm`, a system prompt, an optional
project attach, and LiteLLM-style sampling defaults. Once attached to a
project, the agent inherits the project's prompts (merged into its system
block, sorted by priority) and gets to call the project's MCP servers as
tools during chat.

Every agent is also exposed back to MCP clients as a virtual server named
`agent-<name>` with one tool `chat`. So another Claude session connecting to
the same project sees, e.g., `agent-reviewer/chat` in `tools/list` with the
description "I review security design — ask me after each major change."
That's how agents consult each other.

```bash
# 1) point at an LLM. For your in-cluster qwen3-thinking via LiteLLM:
mcpctl create secret litellm-key --data API_KEY=sk-…
mcpctl create llm qwen3-thinking \
  --type openai \
  --model qwen3-thinking \
  --url http://litellm.nvidia-nim.svc.cluster.local:4000/v1 \
  --api-key-ref litellm-key/API_KEY

# 2) create an agent, pinned to that Llm and attached to a project
mcpctl create agent reviewer \
  --llm qwen3-thinking \
  --project mcpctl-dev \
  --description "I review security design — ask me after each major change." \
  --system-prompt-file ./prompts/reviewer.md \
  --default-temperature 0.2 --default-max-tokens 4096

# 3) chat with it (interactive REPL — Ctrl-D to exit)
mcpctl chat reviewer

# Or one-shot
mcpctl chat reviewer -m "Look at PR #42 and tell me what's risky."

# Resume a thread
mcpctl get threads --agent reviewer
mcpctl chat reviewer --thread <id>
```

Full reference: [docs/agents.md](docs/agents.md). User-facing chat guide:
[docs/chat.md](docs/chat.md).

### Personalities

Same agent, different prompt bundles per turn. A **Personality** is a named
overlay attached to an agent — when selected at chat time it appends extra
prompts to the system block without replacing the agent's own prompt or
project prompts. Think VLAN on top of ethernet: the underlying agent still
works without one; with one, segmentation kicks in.

```bash
# Make a personality on an existing agent
mcpctl create personality grumpy --agent reviewer --description "Be terse and slightly grumpy"

# Add an agent-direct prompt (always-on for this agent — no toggle)
mcpctl create prompt always-terse --agent reviewer --content "Always be terse." --priority 8

# Use it
mcpctl chat reviewer --personality grumpy
```

For binding prompts to personalities and the API surface, see
[docs/personalities.md](docs/personalities.md). The browser editor at
`https://mcpctl.ad.itaz.eu/ui/` covers the same flow with Monaco-based
prompt editing — paste a session token (`mcpctl auth login`) or PAT to log
in.

### Virtual LLMs

A user's local LLM (`vllm-local`, Ollama, …) can publish itself into
mcpd's `Llm` registry so anyone authorized sees it under `mcpctl get llm`
and can chat with it via `mcpctl chat-llm <name>`. Inference is relayed
through the publishing mcplocal's SSE control channel — mcpd never holds
the local URL or API key.

```fish
# In ~/.mcpctl/config.json, opt the provider in with `publish: true`:
#   { "name": "vllm-local", "type": "openai", "model": "...", "publish": true }
systemctl --user restart mcplocal

mcpctl get llm
# NAME             KIND     STATUS    TYPE     MODEL                          TIER  ID
# qwen3-thinking   public   active    openai   qwen3-thinking                 fast  ...
# vllm-local       virtual  active    openai   Qwen/Qwen2.5-7B-Instruct-AWQ   fast  ...

mcpctl chat-llm vllm-local
> hello?
```

Lifecycle: 30 s heartbeats, 90 s heartbeat-stale → inactive, 4 h
inactive → auto-deleted. A reconnecting mcplocal adopts the same row
via a sticky `providerSessionId`. Full design: [docs/virtual-llms.md](docs/virtual-llms.md).

## Commands

```bash
# List resources
mcpctl get servers
mcpctl get instances
mcpctl get projects
mcpctl get prompts --project myproject

# Detailed view
mcpctl describe server grafana
mcpctl describe project monitoring

# Create resources
mcpctl create server <name> [flags]
mcpctl create secret <name> --data KEY=value
mcpctl create project <name> --server <srv> [--proxy-model <plugin>]
mcpctl create prompt <name> --project <proj> --content "..."

# Modify resources
mcpctl edit server grafana          # Opens in $EDITOR
mcpctl patch project myproj proxyModel=default
mcpctl apply -f config.yaml         # Declarative create/update

# Delete resources
mcpctl delete server grafana

# Logs and debugging
mcpctl logs grafana                 # Container logs
mcpctl console monitoring           # Interactive MCP console
mcpctl console --inspect            # Traffic inspector
mcpctl console --audit              # Audit event timeline
mcpctl console --stdin-mcp          # Claude monitor (MCP tools for Claude)

# Backup (git-based)
mcpctl backup                       # Status and SSH key
mcpctl backup log                   # Commit history
mcpctl backup restore list          # Available restore points
mcpctl backup restore diff abc1234  # Preview a restore
mcpctl backup restore to abc1234 --force  # Restore to a commit

# Project management
mcpctl --project monitoring get servers       # Project-scoped listing
mcpctl --project monitoring attach-server grafana
mcpctl --project monitoring detach-server grafana
```

## Templates

Templates are reusable server configurations. Create a server from a template without repeating all the config:

```bash
# Register a template
mcpctl create template home-assistant \
  --docker-image "ghcr.io/homeassistant-ai/ha-mcp:latest" \
  --transport SSE \
  --container-port 8086

# Create a server from it
mcpctl create server my-ha \
  --from-template home-assistant \
  --env-from-secret ha-secrets
```

### Persistent volumes

Instances are immutable — any server edit recreates them — so by default
anything an MCP server writes to its container filesystem is lost at that point.
A server (or template) can declare volumes that outlive its instances:

```bash
mcpctl create server docs \
  --from-template docs-mcp \
  --volume data:/data:20:longhorn      # NAME:/mount/path[:SIZE_GB[:STORAGE_CLASS]]
```

```yaml
# ...or declaratively
volumes:
  - name: data
    mountPath: /data
    sizeGb: 20
    storageClass: longhorn
```

The backing store is named after the **server**, not the instance —
`mcpctl-<server>-<name>` — which is what lets the data survive. On Kubernetes
that is a PVC created in the servers namespace on first start and left in place
afterwards; on Docker it is a named volume. Neither is deleted when an instance
or the server goes away, so reclaiming the space is a deliberate
`kubectl delete pvc` / `docker volume rm`.

Notes:

- Claims are `ReadWriteOnce`, so a server with volumes is limited to one
  replica. Asking for more is rejected at validation rather than leaving the
  extra replicas unschedulable.
- A fresh claim mounts `root:root`, so mcpctl sets the pod's `fsGroup` to
  **1000** — the conventional non-root uid in node/python images. Override with
  `fsGroup` on the volume if an image uses a different one; containers running
  as root are unaffected either way.
- `storageClass` defaults to `MCPD_VOLUME_STORAGE_CLASS`, and is omitted
  entirely when neither is set. **Set it explicitly on any cluster with more
  than one default StorageClass**, where an omitted class binds
  nondeterministically.
- Growing a volume is an explicit `kubectl edit pvc` (the class must allow
  expansion). mcpctl never resizes an existing claim, because most PVC fields
  are immutable after binding.
- Backups capture the volume *declaration*, not its contents.

### Web search and docs lookup

The `duckduckgo`, `searxng` and `docs-mcp` templates give an agent web search and
version-pinned library documentation. All are self-hosted and none needs an API key.
`duckduckgo` needs no backing service at all:

```bash
mcpctl create server websearch --from-template duckduckgo
```

See [docs/web-search.md](docs/web-search.md) for the SearXNG engine setup (including
the `json` format setting, without which every search silently returns nothing) and
the `docs-mcp` index-persistence caveat.

## Gated Sessions

Projects using the `default` or `gate` plugin are **gated**. When Claude connects to a gated project:

1. Claude sees only a `begin_session` tool initially
2. Claude calls `begin_session` with a description of its task
3. mcplocal matches relevant prompts and delivers them
4. The full tool list is revealed

This keeps Claude's context focused — instead of dumping 100+ tools and pages of docs upfront, only the relevant ones are delivered based on the task at hand.

```bash
# Gated (default)
mcpctl create project monitoring --server grafana --proxy-model default

# Ungated (direct tool access)
mcpctl create project tools --server grafana --proxy-model content-pipeline
```

## Prompts

Prompts are curated content delivered to Claude through the MCP protocol. They can be plain text or linked to external MCP resources (like wiki pages).

```bash
# Create a text prompt
mcpctl create prompt deployment-guide \
  --project monitoring \
  --content-file docs/deployment.md \
  --priority 7

# Create a linked prompt (content fetched live from an MCP resource)
mcpctl create prompt wiki-page \
  --project monitoring \
  --link "monitoring/docmost:docmost://pages/abc123" \
  --priority 5
```

Claude can also **propose** prompts during a session. These appear as prompt requests that you can review and approve:

```bash
mcpctl get promptrequests
mcpctl approve promptrequest proposed-guide
```

## Interactive Console

The console lets you see exactly what Claude sees — tools, resources, prompts — and call tools interactively:

```bash
mcpctl console monitoring
```

The traffic inspector watches MCP traffic from other clients in real-time:

```bash
mcpctl console --inspect
```

### Claude Monitor (stdin-mcp)

Connect Claude itself as a monitor via the inspect MCP server:

```bash
mcpctl console --stdin-mcp
```

This exposes MCP tools that let Claude observe and control traffic:

| Tool | Description |
|------|------------|
| `list_models` | List configured LLM providers and their status |
| `list_stages` | List all available pipeline stages (built-in + custom) |
| `switch_model` | Change the active LLM provider for pipeline stages |
| `get_model_info` | Get details about a specific LLM provider |
| `reload_stages` | Force reload custom stages from disk |
| `pause` | Toggle pause mode (intercept pipeline results) |
| `get_pause_queue` | List items held in the pause queue |
| `release_paused` | Release, edit, or drop a paused item |

## Architecture

```
┌──────────────┐           ┌─────────────────────────────────────────┐
│ Claude Code  │   STDIO   │           mcplocal (proxy)              │
│              │◄─────────►│                                         │
│ (or any MCP  │           │  Namespace-merging MCP proxy            │
│  client)     │           │  Gated sessions + prompt delivery       │
│              │           │  Per-project endpoints                  │
└──────────────┘           │  Traffic inspection                     │
                           └──────────────┬──────────────────────────┘
                                          │ HTTP (REST + MCP proxy)
                                          │
                           ┌──────────────┴──────────────────────────┐
                           │              mcpd (daemon)              │
                           │                                         │
                           │  REST API (/api/v1/*)                   │
                           │  MCP proxy (routes tool calls)          │
                           │  PostgreSQL (Prisma ORM)                │
                           │  Docker/Podman container management     │
                           │  Health probes (STDIO, SSE, HTTP)       │
                           │  RBAC enforcement                       │
                           │                                         │
                           │  ┌───────────────────────────────────┐  │
                           │  │     MCP Server Containers         │  │
                           │  │                                   │  │
                           │  │  grafana/  home-assistant/  ...   │  │
                           │  │  (managed + proxied by mcpd)      │  │
                           │  └───────────────────────────────────┘  │
                           └─────────────────────────────────────────┘
```

Clients never connect to MCP server containers directly — all tool calls go through mcplocal → mcpd, which proxies them to the right container via STDIO/SSE/HTTP. This keeps containers unexposed and lets mcpd enforce RBAC and health checks.

**Tool namespacing**: When Claude connects to a project with servers `grafana` and `slack`, it sees tools like `grafana/search_dashboards` and `slack/send_message`. mcplocal routes each call through mcpd to the correct upstream server.

## Project Structure

```
mcpctl/
├── src/
│   ├── cli/          # mcpctl command-line interface (Commander.js)
│   ├── mcpd/         # Daemon server (Fastify 5, REST API)
│   ├── mcplocal/     # Local MCP proxy (namespace merging, gating)
│   ├── db/           # Database schema (Prisma) and migrations
│   └── shared/       # Shared types and utilities
├── deploy/           # Docker Compose for local development
├── stack/            # Production deployment (Portainer)
├── scripts/          # Build, release, and deploy scripts
├── examples/         # Example YAML configurations
└── completions/      # Shell completions (fish, bash)
```

## Development

```bash
# Prerequisites: Node.js 20+, pnpm 9+, Docker/Podman

# Install dependencies
pnpm install

# Start local database
pnpm db:up

# Generate Prisma client
cd src/db && npx prisma generate && cd ../..

# Build all packages
pnpm build

# Run tests
pnpm test:run

# Development mode (mcpd with hot-reload)
cd src/mcpd && pnpm dev
```

## License

MIT