MCP Server — ChatCLI como servidor (e ACP)

Além de ser um cliente MCP (consumir ferramentas externas — ver MCP Integration), o ChatCLI também pode ser um servidor: outros agentes/clientes — Claude Code, Claude Desktop, IDEs, editores, até outro ChatCLI — podem dirigir o ChatCLI via protocolo.

São dois subcomandos externos, ambos falando JSON-RPC sobre stdio (stdin/stdout carregam o protocolo; todo log vai para o file logger):

chatcli mcp-server (alias mcp-serve) — servidor MCP (Model Context Protocol). Negocia a revisão 2025-03-26 ou 2024-11-05.
chatcli acp — servidor ACP (Agent Client Protocol), para editores (Zed) e uso agente-a-agente.

`chatcli mcp-server`

Expõe a superfície completa do ChatCLI — não um subconjunto curado:

Tools do harness

Tool	O que faz
`ask_chatcli`	Chat com o pipeline completo de experiência do ChatCLI — memória longa e perfil do usuário, anexos de `/context` da sessão, skills fixadas e ativadas por trigger, retrieval de knowledge e compactação token-aware do histórico: o mesmo enriquecimento de um turno interativo. Mantém histórico server-side por `session`; aceita overrides de `provider` / `model` por chamada; `plain: true` pula o pipeline para um turno cru e barato.
`coder_task`	O agent loop completo em uma tarefa — recomendado para qualquer trabalho autônomo. Lê/edita arquivos, roda comandos e usa todas as built-in tools, memória, knowledge e qualquer servidor MCP que o próprio ChatCLI esteja conectado. O id de `session` escopa quais anexos de `/context` e knowledge bases a execução enxerga e carrega a própria conversa da execução: runs de agent/coder mantêm histórico por sessão entre chamadas, não um histórico global do processo. Aceita `provider` / `model` e toggles de `quality`.
`agent_task`	O loop orientado a comandos (ReAct), que propõe comandos de shell passo a passo. Prefira `coder_task` para trabalho geral. Mesmas opções de roteamento, qualidade e conversa/escopo por sessão.
`manage_session`	Persiste e restaura as conversas por trás do parâmetro `session` do `ask_chatcli` — save/load/attach/detach/status/list/delete/clear/active, mais `search` full-text no store de sessões salvas, `fork` para copiar uma sessão salva, e `policy_mode` para alternar o modo de política de segurança da sessão (`name: auto \| interactive \| status`). Compartilha o store do `/session` com o REPL interativo. `save` e `load` agora vinculam a sessão viva ao nome salvo, e `attach` vincula até a uma sessão que ainda não existe: cada turno é gravado (write-through) no arquivo e escritas de outras superfícies (REPL, gateway, outro servidor) são adotadas antes de cada turno — continuidade cross-surface; `detach` remove o vínculo, `status` o reporta. Sessões vivas também têm autosave por padrão como espelhos rolling `mcp-<name>` após cada turno (`CHATCLI_MCP_SESSION_AUTOSAVE`; sem ele segue `CHATCLI_SESSION_AUTOSAVE`), e o `clear` salva uma última vez antes de descartar.
`list_providers`	A superfície de roteamento: providers configurados, provider/modelo ativos e os modelos catalogados de cada provider.

O parâmetro quality mapeia para o namespace CHATCLI_QUALITY_*, então o chamador pode ligar plan, refine, verify, reflexion, convergence e lessons para uma única execução:

{ "name": "agent_task", "arguments": {
    "task": "audite o fluxo de auth",
    "provider": "DEVIN", "model": "gpt-5.6-sol",
    "quality": { "CHATCLI_QUALITY_ENABLED": "true" }
} }

Todas as plugin tools

Todos os plugins built-in e externos registrados são anunciados individualmente (37 em um build padrão): arquivos (read, search, tree, coder), web (websearch, webfetch, http, api-explorer), memória (memory, recall), knowledge (knowledge, context, compress, docs-flatten), visuais (diagram, graphview, image), além de moa, lsp, scheduler, session, osv, wikipedia, registry-tags, todo, tools, channels, send, proc, skill, speak…

Cada tool carrega o usage embutido na descrição e a annotation readOnlyHint derivada da metadata de capabilities por-plugin do ChatCLI.
Os argumentos seguem o mesmo contrato do agente: envelope JSON ({"cmd":"read","args":{...}}) ou string plana.
Tools interativas que exigem terminal vivo (ask, voice, park) nunca são expostas — via stdio travariam para sempre.

Política de exposição — `CHATCLI_MCP_TOOLS`

Valor	Comportamento
`all` (default)	Todas as tools, incluindo write/exec — iniciar o servidor é o opt-in.
`safe`	Só tools cuja metadata de capabilities reporta read-only.
`read,search,recall`	Allowlist explícita (separada por vírgula, com ou sem `@`).

Skills como MCP prompts

Toda skill instalada é servida via prompts/list / prompts/get — o client pode puxar o catálogo inteiro de skills do ChatCLI como prompts prontos. Os templates de slash commands entram na mesma listagem, com o campo arguments do spec MCP (um argumento args derivado do argument-hint do comando; skills com argument-hint também o carregam): prompts/get com {"name":"review-pr","arguments":{"args":"1326 security"}} retorna o template completamente expandido, com linhas de pré-execução resolvidas pela política de segurança.

Estado local como MCP resources — `chatcli://`

Tudo que o usuário construiu no ChatCLI fica navegável (somente leitura) via resources/list / resources/read:

URI	Conteúdo
`chatcli://memory/index` · `longterm` · `profile` · `projects` · `stats`	Memória longa, perfil e projetos rastreados do usuário
`chatcli://contexts` · `chatcli://contexts/{name}`	Catálogo do store de `/context` e o conteúdo renderizado de cada contexto
`chatcli://knowledge/{kb}` · `chatcli://knowledge/{kb}/{source}?offset=N`	TOC da knowledge base e leitura paginada de documentos
`chatcli://skills` · `chatcli://skills/{name}`	Catálogo de skills com triggers (para o client reproduzir a semântica de ativação) e o corpo de cada skill
`chatcli://sessions` · `chatcli://sessions/{name}`	Nomes das sessões salvas e seu conteúdo JSON

Mutações passam pela superfície de tools (memory, context, manage_session, …). CHATCLI_MCP_RESOURCES=off desativa a superfície de resources por completo.

Continuidade cross-channel — o hub de conversas

O servidor entra no hub de conversas em modo resume: adota a conversa ativa do principal em vez de rotacioná-la, então um fio iniciado no REPL interativo ou num canal do gateway (Telegram, Slack…) continua de qualquer client MCP — e os turnos feitos via MCP aparecem de volta no REPL. CHATCLI_MCP_HUB=off desativa; CHATCLI_MCP_HUB_PRINCIPAL isola o fio do MCP sob um principal próprio.

Segurança unattended — `CHATCLI_MCP_DANGER`

O stdin carrega o protocolo, então o servidor roda unattended (toda confirmação interativa auto-aprova, como no gateway daemon). Comandos perigosos em chamadas exec do coder_task são sempre bloqueados independente da política; para o gate restante de comandos shell, CHATCLI_MCP_DANGER=block recusa comandos perigosos in-band (o modelo vê a recusa e replaneja) em vez de auto-aprovar. Default é allow, igual ao gateway.

Prompts de aprovação via elicitation

Clientes que declaram a capability elicitation no initialize ganham um contrato melhor: regras ask da política do coder e comandos exec perigosos do coder_task abrem um formulário via elicitation/create no cliente, em vez do comportamento cego acima. Quando a ação tem um pattern de política persistível, o formulário oferece o vocabulário completo do terminal como um enum decision — allow_once, allow_always, deny_once, deny_always — e as opções always persistem uma regra no coder_policy.json, exatamente como o prompt do terminal (comandos exec nunca ganham as opções always, por design). Comandos exec perigosos mantêm o formulário booleano approve simples. Qualquer coisa que não seja um accept explícito com uma decisão de allow nega — decline, cancel ou falha de transporte — e o modelo replaneja in-band. Clientes sem a capability (a maioria dos CLIs wrapeados) mantêm exatamente o contrato da seção anterior; nenhum request servidor→cliente é enviado a eles. Alguns clientes declaram a capability mas nunca renderizam o formulário de fato — o run ficaria congelado esperando uma resposta até o cliente matar a chamada. Por isso cada round-trip de aprovação é limitado por CHATCLI_MCP_PERMISSION_TIMEOUT (uma duração Go como 90s/10m ou segundos puros; default 600s; 0/off eleva o limite para um teto de 24h — nunca verdadeiramente ilimitado; a mesma variável limita os dialogs de permissão do ACP). Clientes MCP que impõem seu próprio timeout de tools/call mais curto matam a chamada inteira antes — ajuste a variável abaixo do limite do seu cliente para manter o run vivo. Um formulário sem resposta nega fail-safe — nunca auto-aprova, já que o formulário pode estar visível com o usuário prestes a negar — e o modelo é informado de que o pedido ficou sem resposta (não que o usuário negou), então ele continua sem a ação e consegue explicar o que houve. Depois do primeiro timeout, os próximos pedidos do mesmo run falham rápido em vez de travar de novo. Se o seu cliente insiste em declarar elicitation sem exibir dialogs, defina CHATCLI_MCP_ELICITATION=off para desligar a ponte por completo e restaurar o contrato unattended da seção anterior. Para pular os formulários numa sessão inteira, a action policy_mode da tool manage_session (name: auto) coloca a sessão em automode de política: regras ask auto-aprovam enquanto regras deny e operações safety-immune continuam travando; name: interactive restaura os formulários.

Sem provider configurado? Ainda é útil

Um client MCP traz o próprio modelo — as tools diretas do ChatCLI não precisam de LLM local. Sem key/OAuth no ChatCLI, as tools que dependem de LLM (ask_chatcli, agent_task, coder_task) simplesmente somem do tools/list, e todas as tools diretas continuam funcionando (memória persistente, knowledge bases, LSP, diagramas, scheduler… dirigidas pelo modelo do chamador). Configure um provider e reinicie para habilitar as tools do harness.

O ambiente que o cliente MCP repassa

Um cliente MCP sobe o servidor como processo filho sem o seu shell profile: CHATCLI_DOTENV e tudo que você exporta no .zshrc/.bashrc não chegam nele, e o diretório de trabalho é o que o cliente escolheu. Por isso o ChatCLI descobre o arquivo de ambiente como $CHATCLI_DOTENV → ./.env → ~/.chatcli/.env → ~/.env, o primeiro que existir vence — mantenha o seu em um dos caminhos do home e o servidor enxerga exatamente o que o seu terminal enxerga. O que o cliente precisar fixar explicitamente vai no bloco env dele. Essa é a explicação usual para dois sintomas: providers que funcionam no terminal sumirem do tools/list, e o Bedrock responder pela conta AWS errada (sem AWS_PROFILE/BEDROCK_PROFILE o SDK cai no profile default, e a cadeia de credenciais falha com o enganoso no EC2 IMDS role found). O log de boot registra qual arquivo carregou, e os erros de credencial nomeiam o profile, o arquivo de ambiente em efeito e o comando aws sso login para renovar a sessão.

Conectando do Claude Code

claude mcp add chatcli -- chatcli mcp-server

Ou em um config JSON:

{
  "mcpServers": {
    "chatcli": {
      "command": "chatcli",
      "args": ["mcp-server"],
      "env": { "LLM_PROVIDER": "CLAUDEAI", "LLM_MODEL": "claude-sonnet-4-6" }
    }
  }
}

O agent e o coder renderizam no stdout; o backend captura essa saída durante a execução e devolve como resultado da tool. Chamadas diretas de tool também são capturadas, então um plugin falante nunca corrompe o canal do protocolo. Chamadas longas não bloqueiam o loop de leitura — as requests despacham concorrentemente, que é o que faz o cancelamento funcionar.

`chatcli acp`

Um servidor Agent Client Protocol completo: sessões com modos chat/agent/coder, tool calls e plano estruturados, slash commands e dialogs nativos de permissão da IDE — o caminho para rodar o ChatCLI dentro de IDEs JetBrains e do Zed.

chatcli acp

Updates estruturados — runs de agent/coder emitem frames nativos tool_call/tool_call_update, agent_thought_chunk e plan; a IDE renderiza tool calls colapsáveis e um plano ao vivo em vez de um transcript em stream.
Slash commands — /coder, /config, /model e uma allowlist headless são anunciados ao cliente e funcionam da caixa de prompt da IDE.
Dialogs de permissão — comandos perigosos e regras ask da política de segurança disparam session/request_permission (dialog nativo da IDE com allow/reject, once/always) em vez de auto-aprovar/bloquear cego.
Cancelamento — session/cancel interrompe um prompt em voo e fecha qualquer tool call aberta.
Restauração de sessão — session/load (capability loadSession: true) traz de volta um session id anterior (estado vivo, ou o espelho de autosave mcp-<id> após restart) e faz replay da conversa no cliente; o /session da caixa de prompt opera por sessão e vincula a sessões nomeadas para continuidade cross-surface.

Setup completo (JetBrains ~/.jetbrains/acp.json, agent_servers do Zed), a superfície de comandos, o modelo de segurança e os detalhes do protocolo vivem na página dedicada: ACP — ChatCLI dentro da sua IDE.

Veja também

ACP — ChatCLI dentro da sua IDE — o servidor ACP a fundo: setup de IDE, slash commands, dialogs de permissão
MCP Integration — ChatCLI como cliente MCP, incluindo o chatcli mcp add
Variáveis de Ambiente — LLM_PROVIDER, LLM_MODEL, CHATCLI_MCP_TOOLS
Referência de Comandos — subcomandos externos

Início

Primeiros Passos

Conceitos Fundamentais

Funcionalidades

Segurança

Suporte

MCP Server — ChatCLI como servidor (e ACP)

`chatcli mcp-server`

Tools do harness

Todas as plugin tools

Política de exposição — `CHATCLI_MCP_TOOLS`

Skills como MCP prompts

Estado local como MCP resources — `chatcli://`

Continuidade cross-channel — o hub de conversas

Segurança unattended — `CHATCLI_MCP_DANGER`

Prompts de aprovação via elicitation

Sem provider configurado? Ainda é útil

O ambiente que o cliente MCP repassa

Conectando do Claude Code

`chatcli acp`

Veja também

​chatcli mcp-server

​Tools do harness

​Todas as plugin tools

​Política de exposição — CHATCLI_MCP_TOOLS

​Skills como MCP prompts

​Estado local como MCP resources — chatcli://

​Continuidade cross-channel — o hub de conversas

​Segurança unattended — CHATCLI_MCP_DANGER

​Prompts de aprovação via elicitation

​Sem provider configurado? Ainda é útil

​O ambiente que o cliente MCP repassa

​Conectando do Claude Code

​chatcli acp

​Veja também

`chatcli mcp-server`

Tools do harness

Todas as plugin tools

Política de exposição — `CHATCLI_MCP_TOOLS`

Skills como MCP prompts

Estado local como MCP resources — `chatcli://`

Continuidade cross-channel — o hub de conversas

Segurança unattended — `CHATCLI_MCP_DANGER`

Prompts de aprovação via elicitation

Sem provider configurado? Ainda é útil

O ambiente que o cliente MCP repassa

Conectando do Claude Code

`chatcli acp`

Veja também