> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server — ChatCLI como servidor (e ACP)

> chatcli mcp-server expõe a superfície COMPLETA do ChatCLI via MCP: chat com o pipeline completo de experiência (memória, contextos, skills, knowledge), os loops agent/coder reais com roteamento de provider por chamada e toggles de qualidade, todas as built-in tools, todas as skills como prompts, o estado local como resources chatcli:// e continuidade de conversa cross-channel. chatcli acp expõe o ChatCLI via Agent Client Protocol com modos chat/agent/coder, streaming ao vivo e cancelamento.

Além de ser um **cliente** MCP (consumir ferramentas externas — ver [MCP Integration](/pt/extensions/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.

<Info>
  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.
</Info>

***

## `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](/pt/coder/coder-security#modo-de-politica-da-sessao-policy) 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](/pt/context/session-management#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:

```json theme={"system"}
{ "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](/pt/extensions/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](/pt/gateway/conversation-hub) 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](/pt/server/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](/pt/coder/coder-security#modo-de-politica-da-sessao-policy): 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

```bash theme={"system"}
claude mcp add chatcli -- chatcli mcp-server
```

Ou em um config JSON:

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

<Note>
  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.
</Note>

***

## `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**.

```bash theme={"system"}
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](/pt/context/session-management#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](/pt/server/acp)**.

***

## Veja também

* [ACP — ChatCLI dentro da sua IDE](/pt/server/acp) — o servidor ACP a fundo: setup de IDE, slash commands, dialogs de permissão
* [MCP Integration](/pt/extensions/mcp-integration) — ChatCLI como **cliente** MCP, incluindo o `chatcli mcp add`
* [Variáveis de Ambiente](/pt/reference/environment-variables) — `LLM_PROVIDER`, `LLM_MODEL`, `CHATCLI_MCP_TOOLS`
* [Referência de Comandos](/pt/reference/command-reference) — subcomandos externos


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.