# Copilot CLI

Configure o cliente MCP do Copilot CLI de token de portador direto com XMEMO_KEY e atribuição de instância estável.

- Canonical: https://docs.xmemo.dev/pt-br/docs/mcp/copilot-cli
- Locale: pt-BR
- Content-Locale: pt-BR
- Canonical-Content-Digest: 3d18b1df6bc7de8f1e1af14a294640eb5bf7a2d0176a2523f2f62b790b975e99
- Edition-Digest: fb8408cd5f9c25ce8f35e72776ed38356cac45fb977d8986dffda6d56a1d7f63
- Source-Revision: sha256:96e19501d8a5b0d1cc66043cdcd452344580fd7ffafd84f8562409ac6df29e12

## Pré-requisito

Use o GitHub Copilot CLI com seu suporte à configuração MCP. Esta rota é intencionalmente separada da rota OAuth do VS Code / GitHub Copilot Chat. O Copilot CLI oferece suporte a cabeçalhos HTTP personalizados em ~/.copilot/mcp-config.json ou conectividade de proxy local via memory-os-cli.

- Endpoint: https://xmemo.dev/mcp.
- Transporte: Streamable HTTP (type: "http" na configuração) ou proxy local (xmemo mcp proxy).
- Modo de autenticação: aplique Authorization por meio da interface de usuário/CLI oficial do MCP do Copilot ou uma referência de segredo compatível; não presuma a expansão de variáveis de ambiente (${env:…}) em valores de cabeçalho.
- Arquivo de configuração: ~/.copilot/mcp-config.json.
- Status de prontidão: a expansão direta de variáveis de ambiente em cabeçalhos do Copilot CLI é not-tested; o caminho de proxy local é verificado via MCP-SETUP-GUIDE.md do memory-os-cli.

## Instalação / configuração

Adicione o bloco de servidor XMemo em ~/.copilot/mcp-config.json sob mcpServers ou execute pelo proxy local do memory-os-cli. Não reutilize a entrada da chave servers do VS Code; o Copilot CLI é um caminho de cliente diferente.

- HTTP remoto direto: adicione o bloco XMemo a ~/.copilot/mcp-config.json com type: "http", url: "https://xmemo.dev/mcp", timeout: 30000 e tools: ["*"].
- Caminho do proxy local: execute xmemo setup copilot e mantenha xmemo mcp proxy em execução em um terminal em segundo plano (ancorado ao MCP-SETUP-GUIDE.md do memory-os-cli).
- A expansão direta de variáveis de ambiente em cabeçalhos (${env:XMEMO_KEY}) é not-tested e não é suportada pelos modelos do Core.

```bash
# Local proxy path (recommended if direct remote HTTP is unsupported):
xmemo login
xmemo setup copilot
xmemo mcp proxy  # keep running in a background terminal
```

## Definir a credencial

Defina o valor do cabeçalho Authorization usando a interface de usuário/CLI oficial do MCP do Copilot ou uma referência de segredo compatível (substituindo <replace-with-XMEMO_KEY-or-supported-secret-reference> pelo seu token real). Ao usar o proxy local, xmemo login gerencia a credencial automaticamente.

```bash
# For local proxy:
xmemo login
# For direct configuration, apply token through Copilot CLI or supported secret reference
```

## Gere / confirme XMEMO_AGENT_INSTANCE_ID

Gere um valor não secreto por instalação local do Copilot CLI, persista-o fora do git e reutilize-o após reinícios para manter estável a atribuição.

```bash
export XMEMO_AGENT_INSTANCE_ID='<stable-local-copilot-cli-instance-id>'
# Persist and reuse this value for the same local install
```

## Preservar o bloco de configuração existente

Use o bloco de configuração oficial do XMemo para Copilot CLI correspondente ao modelo do Core (mcp_config.py:267). Aplique o valor real de Authorization através da interface de usuário/CLI oficial do MCP do Copilot ou de uma referência de segredo compatível; não confie na expansão de cabeçalho não verificada ${env:XMEMO_KEY}.

```json
{
  "mcpServers": {
    "XMemo": {
      "type": "http",
      "url": "https://xmemo.dev/mcp",
      "tools": [
        "*"
      ],
      "timeout": 30000,
      "headers": {
        "Authorization": "Bearer <replace-with-XMEMO_KEY-or-supported-secret-reference>",
        "X-Memory-OS-Agent-ID": "copilot-cli",
        "X-Memory-OS-Agent-Instance-ID": "<stable-local-copilot-cli-instance-id>"
      }
    }
  }
}
```

## Reiniciar o cliente

Reinicie o Copilot CLI após alterar mcp-config.json. Se estiver usando o proxy local, verifique se 'xmemo mcp proxy' permanece em execução em um terminal em segundo plano antes de reiniciar o Copilot CLI.

## Teste com uma chamada real de recall

Faça a primeira chamada MCP somente para leitura. Esta é uma invocação real de recall, não um placeholder de health check, e não grava memória.

```text
recall({ query: "connection check", limit: 1 })
```

## Resposta esperada (formato literal)

Uma chamada bem-sucedida retorna o formato público de texto ranqueado abaixo; reference e content são valores reais do espaço de memória autorizado.

```text
### XMemo Memory Results:
1. Reference: <opaque-memory-id> | Location: <location>
   > <memory content>
```

## Erros comuns

O Copilot CLI é um cliente de token direto ou de proxy; erros comuns referem-se a tokens de autenticação, ciclo de vida do proxy ou aprovação de escopo.

- 401 invalid_token — XMEMO_KEY está ausente, expirado, revogado ou não expandido: verifique a referência de segredo ativa ou execute novamente xmemo login para o proxy local.
- 403 insufficient_scope — o token não concede memory:read: emita um token com o escopo necessário.
- Connection refused — se estiver usando proxy local, verifique se xmemo mcp proxy está em execução em um terminal em segundo plano.
- Literal '${env:XMEMO_KEY}' enviado no cabeçalho — o Copilot CLI pode não expandir variáveis de ambiente em valores de cabeçalho; use a referência de segredo ou o proxy local.
- Valores inválidos de XMEMO_AGENT_INSTANCE_ID são normalizados para nenhuma atribuição de instância em vez de gerar um erro de autenticação.

## Copilot CLI

Direct client: set XMEMO_KEY in the user environment or a supported secret reference, then replace the stable instance placeholder before applying the reviewed config.

```
{
  "mcpServers": {
    "XMemo": {
      "type": "http",
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}
```