> ## 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 (Model Context Protocol)

> Integre ferramentas externas via Model Context Protocol com suporte aos transports stdio, SSE e Streamable HTTP, além de autorização OAuth 2.1 para servidores remotos.

O **MCP (Model Context Protocol)** e um protocolo aberto para interoperabilidade de ferramentas com modelos de IA. O ChatCLI integra com servidores MCP, permitindo que a IA acesse ferramentas externas como sistema de arquivos, buscas web, bancos de dados e qualquer serviço compatível.

***

## Visão Geral

```text theme={"system"}
ChatCLI <-> MCP Manager <-> MCP Server (stdio | sse | http)
                              |
                         Ferramentas externas
                         (filesystem, search, DB, ...)
```

<Steps>
  <Step title="Carrega configuração">
    O MCP Manager carrega a configuração de servidores MCP.
  </Step>

  <Step title="Inicia servidores">
    Inicia os servidores configurados (stdio, SSE ou Streamable HTTP).
  </Step>

  <Step title="Descobre ferramentas">
    Descobre as ferramentas disponíveis em cada servidor.
  </Step>

  <Step title="Expoe ao modelo">
    Expoe as ferramentas ao modelo de IA como `ToolDefinition`.
  </Step>

  <Step title="Roteia chamadas">
    Roteia chamadas de ferramentas para o servidor correto.
  </Step>
</Steps>

***

## Configuração

### O subcomando `chatcli mcp` (recomendado)

Gerencie servidores pelo shell — mesma experiência do `claude mcp add`, escrevendo em `~/.chatcli/mcp_servers.json` atomicamente (chaves de extensão mantidas à mão sobrevivem ao rewrite; re-adicionar um nome substitui a entrada):

```bash theme={"system"}
# servidor stdio (tudo após -- é a linha de comando do servidor)
chatcli mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/Documents
chatcli mcp add github --env GITHUB_TOKEN=ghp_xxx -- npx -y @modelcontextprotocol/server-github

# servidores remotos (SSE / HTTP streamable)
chatcli mcp add --transport http notion https://mcp.notion.com/mcp
chatcli mcp add --transport sse asana https://mcp.asana.com/sse

# servidores remotos autenticados — header cru (compatível com Claude Code)…
chatcli mcp add --transport sse private https://api.company.com/sse --header "X-API-Key: sua-chave"

# …ou auth tipada com o segredo no ambiente (expandido por request)
chatcli mcp add --transport http secure https://api.example.com/mcp --bearer '${MCP_TOKEN}'
chatcli mcp add --transport sse corp https://mcp.corp.com/sse --basic 'user:${LDAP_PASS}'
chatcli mcp add --transport sse api https://mcp.x.com/sse --auth-header 'X-API-Key: ${KEY}'

chatcli mcp list            # tabela dos servidores configurados
chatcli mcp get <nome>      # JSON completo de um servidor
chatcli mcp remove <nome>   # remove
```

Outros flags do `add`: `--cwd DIR` (diretório de trabalho do stdio), `--description TEXTO`, `--disabled` (adiciona sem habilitar).

### Arquivo de Configuração

Crie `~/.chatcli/mcp_servers.json`:

```json theme={"system"}
{
  "mcpServers": [
    {
      "name": "filesystem",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-filesystem", "/workspace"],
      "enabled": true
    },
    {
      "name": "web-search",
      "transport": "sse",
      "url": "http://localhost:8080/sse",
      "enabled": true,
      "overrides": ["@webfetch", "@websearch"]
    },
    {
      "name": "database",
      "transport": "stdio",
      "command": "/usr/local/bin/mcp-postgres",
      "args": ["--connection-string", "postgresql://localhost/mydb"],
      "env": {
        "PGPASSWORD": "secret"
      },
      "enabled": true
    }
  ]
}
```

#### O que um servidor herda

Um servidor stdio começa com o ambiente do processo pai (para `npx`, `uvx` e `docker` acharem binários e caches) mais o seu mapa `env`, cujos valores expandem `${VAR}` contra o pai. Os segredos do próprio ChatCLI nunca cruzam essa fronteira: `CHATCLI_ENCRYPTION_KEY` (e `_PREVIOUS`), `CHATCLI_JWT_SECRET`, `CHATCLI_AUTH_DIR`, `CHATCLI_AUDIT_LOG_PATH` e `CHATCLI_MANAGED_CONFIG` são removidos antes do spawn. Um servidor que precise de fato de um deles opta explicitamente nomeando-o no seu `env` (`"CHATCLI_AUDIT_LOG_PATH": "${CHATCLI_AUDIT_LOG_PATH}"`). Plugins executáveis recebem o mesmo ambiente filtrado. Chaves de API de provedores não são filtradas — servidores e launchers as usam legitimamente.

### Capacidades estendidas do servidor

Além do mínimo (`name`, `command`, `args`, `env`, `transport`, `enabled`, `overrides`), o entry de cada servidor aceita um conjunto de campos opt-in cobrindo os mesmos casos suportados por Claude Code, Cline, Cursor e AWS EKS MCP — auto-aprovação de tools, filtragem `enabledTools`/`disabledTools`, timeouts próprios, working directory, headers HTTP custom e autenticação HTTP (`bearer`/`basic`/`header`, compartilhada por `sse` e `http`), além de metadados (`description`, `tags`, `category`) que aparecem em `/mcp status`.

Qualquer chave fora do schema tipado é preservada verbatim no round-trip (catch-all `Extensions`), então copiar uma config de outro cliente funciona sem perder anotações vendor-specific.

Referência completa com semântica, exemplos e troubleshooting: [Configuração de MCP Servers](/pt/reference/mcp-config).

### Variáveis de Ambiente

```bash theme={"system"}
CHATCLI_MCP_ENABLED=true
CHATCLI_MCP_CONFIG=~/.chatcli/mcp_servers.json
```

### Via Flag do Servidor

```bash theme={"system"}
chatcli server --mcp-config ~/.chatcli/mcp_servers.json
```

***

## Transportes

<Tabs>
  <Tab title="stdio">
    O transporte `stdio` inicia um processo local e se comunica via stdin/stdout usando JSON-RPC 2.0:

    ```json theme={"system"}
    {
      "name": "filesystem",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-filesystem", "/workspace"]
    }
    ```

    **Uso**: Servidores locais distribuidos como pacotes npm, binarios standalone ou scripts.
  </Tab>

  <Tab title="SSE (HTTP+SSE)">
    O transporte `sse` conecta a um servidor HTTP remoto que expõe **dois endpoints** — `/sse` para o stream e `/messages` para os POSTs JSON-RPC, conforme o modelo original da spec MCP:

    ```json theme={"system"}
    {
      "name": "remote-tools",
      "transport": "sse",
      "url": "http://mcp-server:8080/sse"
    }
    ```

    O listener do GET `/sse` é **supervisionado**: queda de conexão (proxy idle timeout, server restart) dispara reconnect com backoff exponencial + jitter (500 ms → 30 s cap), pending RPCs sobrevivem ao reconnect, e push notifications no mesmo stream alimentam [MCP Channels](/pt/gateway/mcp-channels).

    **Uso**: servidores remotos baseados no modelo HTTP+SSE (servers anteriores à spec 2025-03-26 ou que mantêm esse modelo por compatibilidade).
  </Tab>

  <Tab title="http (Streamable HTTP)">
    O transporte `http` conecta a um servidor remoto que expõe **um único endpoint** conforme a spec MCP **2025-03-26** (Streamable HTTP). Adotado pelo SDK oficial e por hosts como Cloudflare Workers MCP, FastMCP, mcp.deepwiki.com e gateways MCP gerenciados:

    ```json theme={"system"}
    {
      "name": "remote-tools",
      "transport": "http",
      "url": "https://mcp-server.example.com/mcp/",
      "auth": {
        "type": "bearer",
        "token": "${MCP_TOKEN}"
      }
    }
    ```

    Cada chamada é um POST único; a resposta pode chegar como JSON one-shot, como SSE upgrade no mesmo response (carregando a resposta e notificações `notifications/*` intercaladas) ou como `202 Accepted` para notificações cliente→servidor. Se o servidor emitir `Mcp-Session-Id` no `initialize`, o transport captura e ecoa em todas as chamadas seguintes.

    Push notifications server-initiated são lidas por um **listener GET separado** (opt-in pela spec). O ChatCLI inicia o listener logo após `initialize`; servidores que não implementam push respondem 405/404/501 no GET e o listener para limpo, sem retry. Quando o listener está ativo, push messages chegam em `/channel list` e podem disparar rules de trigger — veja [MCP Channels](/pt/gateway/mcp-channels).

    **Uso**: servidores construídos contra a spec atual do MCP. Quando em dúvida entre `sse` e `http`, hit o endpoint com `curl` — quem responde no GET com `event: endpoint` é `sse`; quem responde no POST diretamente com JSON ou SSE upgrade é `http`.

    <Note>A barra final na `url` é significativa. Vários servidores Streamable HTTP só respondem em `/mcp/` e 307-redirecionam `/mcp`. Detalhes e troubleshooting completos: [Configuração de MCP Servers — http (Streamable HTTP)](/pt/reference/mcp-config#http-streamable-http).</Note>
  </Tab>
</Tabs>

***

## Autorização OAuth 2.1 (servidores remotos)

Servidores MCP remotos (`http`/`sse`) cada vez mais protegem o acesso com **OAuth 2.1** em vez de um token estático — o **servidor MCP da AWS** é o caso motivador. O ChatCLI suporta isso de ponta a ponta e **não precisa de client ID, secret ou endpoints na sua config**: tudo é descoberto em runtime.

Quando um servidor responde a uma requisição com `401` e um desafio OAuth, o ChatCLI:

<Steps>
  <Step title="Descobre o authorization server">
    Lê o header `WWW-Authenticate`, busca a Protected Resource Metadata (RFC 9728) e então a Authorization Server Metadata (RFC 8414) para aprender os endpoints de authorization, token e registro.
  </Step>

  <Step title="Registra um cliente dinamicamente">
    Registra um cliente público PKCE via Dynamic Client Registration (RFC 7591) — você nunca cola um `client_id`.
  </Step>

  <Step title="Roda o fluxo no navegador">
    Abre o navegador para o fluxo authorization-code + PKCE via callback no localhost, vinculando o token ao servidor pelo resource indicator (RFC 8707).
  </Step>

  <Step title="Guarda e renova o token">
    Persiste os tokens de acesso/refresh no **cofre de auth criptografado** (AES-256-GCM, o mesmo do `/auth login`) e os renova de forma transparente daí em diante.
  </Step>
</Steps>

### Autorizando um servidor

Com um servidor remoto configurado, autorize-o de duas formas:

<CodeGroup>
  ```bash Você (o comando) theme={"system"}
  # abre o navegador, guarda o token, reconecta o servidor
  /mcp login aws-mcp

  # esquece a credencial guardada (e para o servidor)
  /mcp logout aws-mcp
  ```

  ```text O agente (automaticamente) theme={"system"}
  # Quando uma chamada de tool precisa de autorização, o erro instrui o
  # modelo a autorizar, e ele mesmo invoca a tool built-in @mcp-login:
  MCP tool error: MCP server "aws-mcp" requires OAuth authorization.
  Call @mcp-login with {"server":"aws-mcp"} to authorize, then retry.
  ```
</CodeGroup>

O `/mcp status` mostra um servidor aguardando autorização com o estado `🔒 authorization required` e uma dica de login. Após um login bem-sucedido o servidor reconecta e suas ferramentas `mcp_*` ficam disponíveis.

### Quando o refresh token expira

Refresh tokens eventualmente morrem no lado do servidor (o sign-in da AWS retorna `TOKEN_EXPIRED`; servidores OAuth padrão retornam `invalid_grant`). O ChatCLI trata esses erros como **terminais**: a renovação automática para imediatamente em vez de retentar para sempre, a falha fica registrada para que as chamadas de tool falhem rápido sem round-trips extras, e o servidor é marcado `🔒 authorization required` — mesmo no meio da sessão, muito depois do handshake inicial. As chamadas de tool exibem a dica acionável do `@mcp-login` (o agent consegue se reautorizar sozinho, abrindo seu navegador), e um `/mcp login <nome>` recupera manualmente. Falhas transitórias (oscilações de rede, 5xx) mantêm o comportamento normal de retry.

<Note>
  Nenhuma mudança de config é necessária para um servidor OAuth — basta adicioná-lo como um servidor `http`/`sse` normal (`chatcli mcp add --transport http aws-mcp https://…/mcp`). A primeira chamada de tool dispara o pedido de autorização. Para fixar a porta do callback loopback (para allowlists estritas de redirect-URI), defina `CHATCLI_MCP_OAUTH_PORT` (padrão `8765`; cai numa porta efêmera se estiver ocupada).
</Note>

A autenticação estática `bearer`/`basic`/`header` documentada acima continua valendo para servidores que aceitam um token já emitido; o OAuth é usado apenas quando um servidor ativamente o exige.

***

## Nomeacao de Ferramentas

Ferramentas MCP são automaticamente prefixadas com `mcp_` e recebem a descrição do servidor de origem:

```text theme={"system"}
Nome original: read_file
Nome no ChatCLI: mcp_read_file
Descrição: [MCP:filesystem] Reads a file from the filesystem
```

<Info>O prefixo `mcp_` evita colisões com ferramentas nativas do ChatCLI.</Info>

***

## Overrides de Built-ins (Shadow + Fallback)

Quando um servidor MCP oferece uma ferramenta que **substitui** um plugin nativo (ex: `@webfetch`, `@websearch`), use o campo `overrides` para declarar quais built-ins ele substitui. O ChatCLI **esconde automaticamente** os built-ins listados enquanto o servidor MCP estiver conectado. Se o servidor **desconectar**, os built-ins são **restaurados imediatamente** — o usuário nunca perde a capacidade.

### Por que usar overrides?

Sem `overrides`, o LLM vê duas ferramentas que fazem a mesma coisa (ex: `@webfetch` e `mcp_web_fetch`) e escolhe aleatoriamente. Com `overrides`, o comportamento é **determinístico**: o LLM só vê a ferramenta MCP, sem ambiguidade.

### Configuração

Adicione `overrides` na configuração do servidor MCP:

<Tabs>
  <Tab title="CLI (mcp_servers.json)">
    ```json theme={"system"}
    {
      "mcpServers": [
        {
          "name": "web-tools",
          "transport": "sse",
          "url": "http://mcp-web:8080/sse",
          "enabled": true,
          "overrides": ["@webfetch", "@websearch"]
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Helm (values.yaml)">
    ```yaml theme={"system"}
    mcp:
      enabled: true
      servers:
        - name: web-tools
          transport: sse
          url: "http://mcp-web:8080/sse"
          enabled: true
          overrides: ["@webfetch", "@websearch"]
    ```
  </Tab>

  <Tab title="Operator (Instance CRD)">
    ```yaml theme={"system"}
    apiVersion: platform.chatcli.io/v1alpha1
    kind: Instance
    metadata:
      name: my-chatcli
    spec:
      mcp:
        enabled: true
        servers:
          - name: web-tools
            transport: sse
            url: "http://mcp-web:8080/sse"
            enabled: true
            overrides: ["@webfetch", "@websearch"]
    ```
  </Tab>
</Tabs>

### Como funciona

```text theme={"system"}
MCP server "web-tools" CONECTADO + overrides: ["@webfetch", "@websearch"]
  LLM vê:     mcp_web_fetch, mcp_web_search, @coder, ...
  LLM NÃO vê: @webfetch, @websearch  (escondidos)

MCP server "web-tools" DESCONECTOU (crash, rede, etc.)
  LLM vê:     @webfetch, @websearch, @coder, ...  (restaurados automaticamente)
  Log:         "MCP server 'web-tools' disconnected, restoring built-in overrides"
```

<Note>
  O sync de shadow acontece **a cada turno de conversa**, não apenas no startup. Isso significa que se o MCP server cair no meio de uma conversa, os built-ins voltam **na próxima mensagem** — sem restart necessário.
</Note>

### Regras importantes

| Regra | Detalhe |
| :- | :- |
| **Nomes exatos** | Use o nome completo do built-in, incluindo o `@` (ex: `"@webfetch"`, não `"webfetch"`) |
| **Múltiplos servers** | Vários servers podem declarar overrides diferentes. Se dois servers fazem override do mesmo built-in, basta **um** estar conectado para manter o shadow |
| **Server desabilitado** | `"enabled": false` no server = overrides **não** se aplicam (server nunca conecta) |
| **Override parcial** | Você pode fazer override de apenas um built-in (ex: só `@websearch`) e manter os outros visíveis |
| **Sem efeito no @coder** | O `@coder` não pode ser overridden via MCP — suas subcommands são tools nativas do modo /coder |

<Warning>
  O campo `overrides` não desinstala nem modifica o plugin built-in. Ele apenas o **esconde do prompt** do LLM. O plugin continua disponível internamente e volta automaticamente quando necessário. Isso é **shadow, não delete**.
</Warning>

***

## Deploy via Helm

<Tabs>
  <Tab title="Servidores MCP Inline">
    ```yaml theme={"system"}
    # values.yaml
    mcp:
      enabled: true
      servers:
        - name: filesystem
          transport: stdio
          command: npx
          args: ["-y", "@anthropic/mcp-server-filesystem", "/workspace"]
          enabled: true
        - name: web-tools
          transport: sse
          url: "http://mcp-web:8080/sse"
          enabled: true
          overrides: ["@webfetch", "@websearch"]  # esconde built-ins quando conectado
    ```
  </Tab>

  <Tab title="ConfigMap Existente">
    ```yaml theme={"system"}
    mcp:
      enabled: true
      existingConfigMap: "my-mcp-config"
    ```
  </Tab>
</Tabs>

O Helm chart cria automaticamente um ConfigMap com o `mcp_servers.json` e monta em `/etc/chatcli/mcp/`. O servidor só o lê no startup: um `helm upgrade` que muda `mcp.servers` recria os pods (anotação `checksum/mcp` no pod), enquanto um `existingConfigMap` editado exige `kubectl rollout restart deploy/<release>`.

***

## Deploy via Operator (Instance CRD)

Quando usando o ChatCLI Operator, configure MCP diretamente no recurso `Instance`:

```yaml theme={"system"}
apiVersion: platform.chatcli.io/v1alpha1
kind: Instance
metadata:
  name: my-chatcli
spec:
  provider: CLAUDEAI
  model: claude-sonnet-4-6
  mcp:
    enabled: true
    servers:
      - name: filesystem
        transport: stdio
        command: npx
        args: ["-y", "@anthropic/mcp-server-filesystem", "/workspace"]
        enabled: true
      - name: github
        transport: stdio
        command: npx
        args: ["-y", "@anthropic/mcp-server-github"]
        env:
          GITHUB_TOKEN: "ghp_xxxxx"
        enabled: true
      - name: remote-search
        transport: sse
        url: "http://mcp-search:8080/sse"
        enabled: true
        overrides: ["@webfetch", "@websearch"]  # esconde built-ins quando conectado
```

Ou referencie um ConfigMap existente:

```yaml theme={"system"}
spec:
  mcp:
    enabled: true
    existingConfigMap: "my-mcp-servers"
```

O controller automaticamente:

1. Gera um ConfigMap `<instance>-mcp` com `mcp_servers.json`
2. Monta em `/etc/chatcli/mcp/` (read-only)
3. Passa `--mcp-config /etc/chatcli/mcp/mcp_servers.json` ao container
4. Reinicia os pods quando o ConfigMap de MCP muda, seja o gerado a partir de `servers` ou o seu `existingConfigMap` (anotação `chatcli.io/mounted-configmaps-hash`), já que o servidor só o lê na subida

<Info>O CRD `MCPSpec` espelha exatamente o formato do `mcp_servers.json`. Cada campo do `MCPServerSpec` corresponde a um campo do JSON — incluindo `overrides` para shadow de built-ins.</Info>

***

## Verificando Status

O MCP Manager expoe o status de cada servidor:

```go theme={"system"}
statuses := mcpMgr.GetServerStatus()
for _, s := range statuses {
    fmt.Printf("Server: %s, Connected: %v, Tools: %d\n",
        s.Name, s.Connected, s.ToolCount)
}
```

Para verificar se uma ferramenta e MCP:

```go theme={"system"}
if mcpMgr.IsMCPTool("mcp_read_file") {
    result, err := mcpMgr.ExecuteTool(ctx, "read_file", args)
}
```

***

## Servidores MCP Populares

| Servidor | Descrição | Instalação |
| :- | :- | :- |
| `@anthropic/mcp-server-filesystem` | Acesso ao sistema de arquivos | `npx -y @anthropic/mcp-server-filesystem /path` |
| `@anthropic/mcp-server-github` | Integração com GitHub | `npx -y @anthropic/mcp-server-github` |
| `@anthropic/mcp-server-postgres` | Queries PostgreSQL | `npx -y @anthropic/mcp-server-postgres` |
| `@anthropic/mcp-server-slack` | Integração com Slack | `npx -y @anthropic/mcp-server-slack` |

<Tip>Consulte [modelcontextprotocol.io](https://modelcontextprotocol.io) para a lista completa de servidores MCP disponíveis.</Tip>

***

## MCP no Modo Client (TTY)

<Info>
  Desde a versão mais recente, o MCP funciona diretamente no modo interativo (TTY), não apenas no modo servidor.
  O ChatCLI auto-detecta o arquivo `~/.chatcli/mcp_servers.json` e inicializa os servidores automaticamente ao iniciar.
</Info>

As ferramentas MCP são expostas nos **3 modos** do ChatCLI:

| Modo | Como funciona |
| :- | :- |
| **Chat** | Ferramentas listadas no system prompt como contexto informativo |
| **Agent** | Ferramentas invocaveis via `<tool_call name="mcp_<tool>" args='...' />` |
| **Coder** | Mesmo mecanismo do Agent mode |

### Deferred Schemas (Economia de Tokens)

Para economizar tokens no system prompt, o ChatCLI usa **deferred schemas**:

1. Apenas **nome + descrição** são enviados no prompt (lightweight)
2. Antes do primeiro uso, o modelo consulta o catálogo com `@tools describe` e recebe o bloco completo: **servidor de origem**, descrição, JSON Schema de parâmetros e forma de invocação
3. O modelo invoca com os argumentos corretos

```text theme={"system"}
Prompt: "mcp_read_file: [MCP:filesystem] Reads a file from the filesystem"

Modelo: <tool_call name="@tools" args='{"cmd":"describe","args":{"name":"mcp_read_file"}}' />
→ retorna servidor, descrição e JSON Schema completo

Modelo invoca com args → execução real
```

`@tools list` também indexa as tools MCP junto com as builtins, **agrupadas por servidor de origem** — cada entrada carrega a tag `[MCP:servidor]`, então o modelo sempre sabe de qual servidor a tool vem.

Como fallback, se o modelo invocar uma tool MCP **sem os parâmetros obrigatórios**, o schema completo é retornado como feedback para correção.

**Descrições no índice são limitadas**: a descrição de cada tool no índice do system prompt é reduzida à primeira linha, com teto de 160 caracteres. Servidores MCP corporativos trazem descrições de vários parágrafos — com 100+ tools conectadas, só as descrições sem clamp somam dezenas de KB a **cada requisição**, exatamente o piso de payload que estoura limites de corpo de proxy/WAF corporativo (veja [Context Recovery](/pt/context/context-recovery)). A descrição completa e o schema continuam a um `@tools describe` de distância.

<Tip>Isso pode economizar centenas de tokens por turno quando há muitas ferramentas MCP conectadas — e com servidores corporativos verbosos, dezenas de KB por requisição.</Tip>

### Dynamic tool discovery

Alguns servidores MCP têm uma **lista de tools dinâmica** (a capability `tools.listChanged`): conectam expondo um catálogo mínimo e o expandem em runtime. O HTTP Toolkit é o caso canônico — expõe só `start` ao conectar, e depois que o `start` roda ele registra as tools reais e emite uma notificação `notifications/tools/list_changed`.

O ChatCLI trata isso de ponta a ponta:

1. A notificação dispara um **refresh debounced por servidor** (rajadas coalescem numa única chamada `tools/list`). O refresh roda de forma assíncrona — um round-trip síncrono a partir da goroutine leitora do transport causaria deadlock no pump de resposta.
2. O registry é **reconciliado**: tools novas adicionadas, schemas alterados substituídos, tools que sumiram removidas — tocando apenas as tools daquele servidor.
3. No próximo turn boundary o agente é avisado do que mudou, para usar as tools novas imediatamente:

```text theme={"system"}
🔌 Catálogo de ferramentas MCP atualizado (http-toolkit: +12/-0) — novas tools disponíveis para o agente
```

O modelo recebe os nomes das tools adicionadas/removidas e o lembrete de fazer `@tools describe` antes do primeiro uso. Dispatch de tools, `@tools list/describe` e o completer leem o registry vivo, então a mudança fica visível em todo lugar de uma vez. O evento `tools/list_changed` também é registrado no [inbox de canais](/pt/gateway/mcp-channels) para auditoria — mas, como evento de protocolo tratado, **não** incha o contador de unread.

Controlado por `CHATCLI_MCP_DYNAMIC_TOOLS` (default ligado); aparece em `/config integrations`.

***

## Comando `/mcp`

Gerencie servidores MCP diretamente do terminal interativo. Todos os subcomandos que aceitam um nome de servidor têm **autocomplete** — pressione `Tab` após `/mcp <subcomando>` para listar os servidores configurados.

| Subcomando | Argumento | Descrição |
| :- | :- | :- |
| `/mcp` ou `/mcp status [nome]` | Opcional | Status de todos os servidores (sem nome) ou de um específico |
| `/mcp tools [nome]` | Opcional | Lista todas as tools (sem nome) ou apenas as do servidor `<nome>` |
| `/mcp start <nome>` | Obrigatório | Inicia um servidor parado (ou que falhou na inicialização) |
| `/mcp stop <nome>` | Obrigatório | Para um servidor sem removê-lo da config — `start` depois ressuscita |
| `/mcp restart [nome]` | Opcional | Reinicia um servidor (com nome) ou **todos** (sem nome) |
| `/mcp reload` | — | Re-lê `mcp_servers.json` e reconcilia (mesma lógica do hot-reload, manual) |
| `/mcp logs <nome>` | Obrigatório | Últimas 200 linhas de stderr do servidor (ring buffer em memória) |
| `/mcp login <nome>` | Obrigatório | Roda o fluxo de autorização OAuth de um servidor remoto e o reconecta (abre o navegador) |
| `/mcp logout <nome>` | Obrigatório | Esquece a credencial OAuth guardada de um servidor e o para |

### Exemplo: status e logs

```text theme={"system"}
> /mcp status

╭── 🔌 MCP SERVERS
│  ● filesystem    connected     3 tools  (2m 15s)
│  ● web-search    connected     2 tools  (2m 15s)
│  ○ database      disconnected
│    ↳ start MCP server "mcp-postgres": exec: not found
│
│  Total: 3 servers, 5 tools available
╰──────────────────────────────────────────────────────

> /mcp logs filesystem

╭── 📜 MCP LOGS — filesystem
│  Server starting on /workspace
│  Loaded 12 file watchers
│  Tool list: read_file, write_file, list_dir
╰──────────────────────────────────────────────────────
```

### Semântica de start/stop

| Cenário | Comportamento |
| :- | :- |
| `/mcp stop foo` em um servidor rodando | Mata o processo, drop das tools; **mantém a entry** no manager |
| `/mcp start foo` depois de `stop` | Ressuscita usando a config atual em memória; tools voltam |
| Hot-reload (edição do JSON) com `foo` parado pelo usuário | `Reload` **respeita** o stop manual; só reinicia se a config de `foo` mudar |
| `/mcp restart` (sem nome) | Stop all + start all com **novo `mcpCtx`** — equivale a um reset completo |
| `/mcp restart foo` | Stop + start apenas de `foo`, preservando o ctx global e os outros servidores |
| Servidor que falhou no startup (LastError setado) | `/mcp start foo` limpa `LastError` e retenta — útil para retry após corrigir o command/env |

<Note>
  A diferença entre `/mcp restart` e `/mcp reload`:

  * **`/mcp restart`** força um restart **mesmo se a config não mudou** (útil para "recarregar credentials" após editar shell env).
  * **`/mcp reload`** é um diff-and-apply contra `mcp_servers.json` — não reinicia nada que não tenha mudado.
</Note>

### Buffer de logs por servidor

Cada servidor stdio mantém um **ring buffer de 200 linhas** alimentado pelo stderr do processo filho. Isso significa que:

* `/mcp logs <nome>` mostra as últimas 200 linhas **sem precisar de `--debug`**;
* Servidores muito tagarelas não consomem memória ilimitada — linhas antigas saem do início;
* Capturas como `npm 404`, panic stacks e mensagens de inicialização ficam disponíveis mesmo após o startup terminar.

<Tip>
  Combinação útil para diagnosticar conexão: `/mcp status` (estado), depois `/mcp logs <nome>` (o motivo). Sem precisar reiniciar com `LOG_LEVEL=debug`.
</Tip>

***

## Push notifications — MCP Channels

Além de tools (request/response), o ChatCLI aceita **push notifications** de qualquer servidor MCP nos três transports. Notifications são mensagens JSON-RPC **sem `id`** (a forma que a spec reserva para "o server quer me dizer algo, não pediu nada em troca"). O ChatCLI captura, persiste e injeta automaticamente nas próximas conversas, e — opcionalmente — aciona o agent via rules de trigger.

### O essencial

* **Funciona em `stdio`, `sse` e `http`** — cada transport tem seu próprio listener:
  * `sse`: o GET `/sse` que já carrega tool responses recebe notifications no mesmo stream.
  * `http`: um GET separado no endpoint (opt-in pelo cliente, opcional pela spec) puxa notifications. Servidores que não suportam respondem 405/404/501 e o listener para limpo, sem retry.
  * `stdio`: linhas JSON-RPC no stdout sem `id` são tratadas como notifications.
* **Persistência durável** em `~/.chatcli/mcp/channels.jsonl` (até 10 MiB, rota­ciona, recarrega no boot).
* **Auto-injection** das 5 mais recentes no system prompt de `chat`/`agent`/`coder` (uncached pra não trashar cache).
* **Filtro per-server**: campo `channels` em `mcp_servers.json` aceita allow-list literal.
* **Rules engine opcional** em `~/.chatcli/mcp/triggers.json` com 3 modos: `notify` (banner discreto, default), `confirm` (yes/no manual), `auto` (executa o agent — requer whitelist de tools).
* **Slash commands**: `/channel list`, `/channel ack`, `/channel pause`, `/channel rules`, `/channel confirm <id>`, `/channel run <seq>`, `/channel inject`.

### Exemplo mínimo — server com channels

```json theme={"system"}
{
  "name": "prom-alerts",
  "transport": "sse",
  "url": "https://prom-alerts.internal/sse",
  "enabled": true,
  "channels": ["alerts/critical", "alerts/error"]
}
```

Com isso, alerts caem em `/channel list`, aparecem no banner do próximo prompt e são injetados automaticamente no contexto do agent.

### Exemplo — trigger que investiga falhas de CI

`~/.chatcli/mcp/triggers.json`:

```json theme={"system"}
{
  "rules": [
    {
      "name": "ci-investigator",
      "server": "ci-monitor",
      "channel": "ci-pipeline",
      "contentRegex": "(?i)fail|broken",
      "mode": "confirm",
      "prompt": "Investigate this CI failure: {{content}}",
      "rateLimit": "5m"
    }
  ]
}
```

Cada falha de CI cita o user com um prompt no banner; `/channel confirm <id>` aceita e o agent começa a investigar.

<Note>
  Documentação completa de channels, rules e troubleshooting: [MCP Channels](/pt/gateway/mcp-channels). Schema completo do campo `channels` e referência do `triggers.json`: [MCP Config](/pt/reference/mcp-config#channel-subscriptions-channels).
</Note>

***

## Próximos passos

<CardGroup cols={2}>
  <Card title="MCP Channels" icon="message" href="/pt/gateway/mcp-channels">
    Push messages dos três transports (`stdio`, `sse`, `http`) com persistência durável, filtro por servidor e rules engine (notify/confirm/auto).
  </Card>

  <Card title="Plugins agênticos" icon="puzzle-piece" href="/pt/agents/agentic-plugins">
    Sistema de plugins do ChatCLI — comparativo com MCP.
  </Card>

  <Card title="Tool Use Nativo" icon="wrench" href="/pt/agents/native-tool-use">
    APIs nativas Anthropic/OpenAI que potencializam MCP.
  </Card>

  <Card title="Configuração MCP" icon="gear" href="/pt/reference/mcp-config">
    Formato completo de `mcp_servers.json` e exemplos.
  </Card>
</CardGroup>


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