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 for what an Agent is and how to create one.

Modes

mcpctl chat <agent>                 # interactive REPL, new thread
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.

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.

--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:

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

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

mcpctl get thread c0abc… -o yaml

Examples

Quick gut-check on a deploy:

$ 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:

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