mcpctl/docs/chat.md

# `mcpctl chat`

Open an interactive chat session with an `Agent`, or send a single message
in one shot. See [agents.md](agents.md) for what an Agent is and how to
create one.

## Modes

```bash
mcpctl chat <agent>                 # interactive REPL, new thread
mcpctl chat <agent> --project <p>   # same agent, viewing project p
mcpctl chat <agent> --thread <id>   # interactive REPL, resume thread
mcpctl chat <agent> -m "hi"         # one-shot, prints reply, no REPL
mcpctl chat <agent> -m "hi" --no-stream  # one-shot, single JSON response (no SSE)
```

Streaming is on by default. Text deltas land on stdout as they arrive; tool
calls and tool results print to stderr in dim brackets so the chat output
stays clean.

## Two lenses on the same agent

`mcpctl chat alice` is the person **on their own** — their system prompt, their
own pinned brain, no project tools.

`mcpctl chat alice --project sre` is the **same person viewing one of their
teams**: the project's Prompts join the system block, the project's MCP servers
become callable tools, and if that membership carries a brain override, that
Llm answers instead of alice's pinned one.

```bash
mcpctl attach-agent alice --project sre --role sre   # join first
mcpctl chat alice --project sre
```

The agent must actually be a member. Naming a project it has not joined is an
error naming the fix, not a silent fallback to some other project's context:

```
Agent 'alice' is not a member of project 'payments'.
Join it with: mcpctl attach-agent alice --project payments
```

(The legacy single-project pin on the agent still counts as membership in that
one project for this release — see [agents.md](agents.md#team-membership-an-agent-joins-many-projects).)

Threads stay scoped to the **agent**, not to (agent, project) — switching
`--project` mid-conversation changes the context layer, not the history.

## Project chat

Chat directly with a **project** — no Agent needed. The session sees the
project's Prompts as system context, can call every tool from the project's
attached MCP servers, and uses the project's own LLM (`llmProvider`, with
`llmModel` as an optional served-model override).

```bash
mcpctl chat --project sre                 # REPL scoped to project "sre"
mcpctl chat --project sre -m "what alerts fired overnight?"
mcpctl chat --project sre --thread <id>   # resume a past conversation
```

- **Prompts + tools** come from the project and stay current — anything you
  add to the project later shows up automatically in the next turn.
- **LLM:** set it once with `mcpctl patch project sre llmProvider=<llm-name>`
  (and optionally `llmModel=<served-model>`). Chat errors clearly if unset.
- **History is saved inside the project**, attributed to you. List and resume:
  ```bash
  mcpctl get threads --project sre         # your threads for this project
  mcpctl chat --project sre --thread <id>
  ```
  Delete one you own (admins with `delete:projects` can delete anyone's):
  ```bash
  mcpctl delete thread <id> --project sre
  ```

### Reading secrets (`--allow-secrets`)

By default the model cannot read secret values — it only benefits from them
indirectly (the project's tools run authenticated). Opt in with
`--allow-secrets` to expose a `get_secret` tool the model can call:

```bash
mcpctl chat --project sre --allow-secrets
```

This is gated: it requires the flag **and** your `view:secrets` permission,
and it is off by default. Secret values the model reads land in the chat
context and thread history, so use it deliberately.

RBAC: project chat and its threads route through `run:projects:<name>`.

## Per-call flags

All optional. They override the agent's `defaultParams` for this session
only — use the in-REPL `/save` slash-command to persist the current set
back to the agent.

```bash
--system <text>              # replace agent.systemPrompt for this session
--system-file <path>         # read --system text from a file
--system-append <text>       # append to the agent system block (after project Prompts)
--personality <name>         # apply a personality overlay for this turn
                             # (additive — see docs/personalities.md)
--temperature <n>            # 0..2
--top-p <n>                  # 0..1
--top-k <n>                  # integer; Anthropic-only, OpenAI ignores
--max-tokens <n>             # cap on assistant tokens
--seed <n>                   # reproducibility (provider-dependent)
--stop <text>                # stop sequence (repeatable, up to 4)
--allow-tool <name>          # repeat to allowlist project MCP tools
--extra <key=value>          # provider-specific knob (repeatable)
--no-stream                  # disable SSE; single JSON response
```

`--extra` is the LiteLLM-style escape hatch: pass anything the underlying
adapter understands. Numeric values are auto-parsed (`--extra
repetition_penalty=1.1`); strings stay strings.

## In-REPL slash-commands

```
/set KEY VALUE      adjust an override for the rest of the session
                    (temperature, top-p, top-k, max-tokens, seed, stop,
                     or any provider-specific knob — unknown keys go
                     into `extra`)
/system <text>      set systemAppend for this turn onward (empty = clear)
/tools              list MCP servers the agent can call as tools
/clear              start a fresh thread (same agent)
/save               PATCH agent.defaultParams = current overrides
                    (systemOverride / systemAppend are NOT persisted)
/quit, /exit        leave the REPL (Ctrl-D works too)
```

## Threads

Threads persist server-side. To resume:

```bash
mcpctl get threads --agent reviewer
mcpctl chat reviewer --thread <id>
```

A `mcpctl get thread <id>` reads the message log:

```bash
mcpctl get thread c0abc… -o yaml
```

## Examples

**Quick gut-check on a deploy:**

```bash
$ mcpctl chat reviewer -m "is fulldeploy.sh safe to run on the current branch?"
Yes — I checked: tests are green on commit 727e7d6 and there's no
in-flight migration. The k8s context is worker0-k8s0 (production); confirm
that's intended before running.
(thread: cm9k…)
```

**Resuming with overrides:**

```bash
$ mcpctl chat deployer --thread cm9k… --temperature 0.0 --max-tokens 256
> walk me through what changed since the last deploy
…
```

**Pinning sampling defaults to the agent:**

```
$ mcpctl chat deployer --temperature 0.0 --max-tokens 8000
> /save
(saved current overrides as agent.defaultParams)
> /quit
```

## Troubleshooting

- **No agents appear in `tools/list`** — check the agent has a project
  attach (`mcpctl describe agent <name>`). The mcplocal plugin only
  exposes agents on their attached project's session.

- **Tool calls fail with `Project not found`** — the agent has no project
  attach. Either attach it (`mcpctl edit agent <name>` and set the project
  field), or expect text-only chat.

- **Anthropic agents can't call tools** — known limitation; the Anthropic
  adapter doesn't translate OpenAI tool format yet. Use LiteLLM or a
  direct OpenAI-compatible provider for tool-using agents until the
  translator ships.

- **`mcpctl chat <agent>` returns 404** — the agent name doesn't resolve.
  `mcpctl get agents` to confirm spelling.

- **REPL feels stuck** — agent tool calls can take minutes (e.g. running a
  Grafana query). Watch stderr for `[tool_call: …]` / `[tool_result: …]`
  brackets; those tell you the loop is alive.