# Copilot CLI

Configure the direct bearer-token Copilot CLI MCP client with XMEMO_KEY and stable instance attribution.

- Canonical: https://docs.xmemo.dev/docs/mcp/copilot-cli
- Locale: en-US
- Content-Locale: en-US
- Canonical-Content-Digest: c80778a10a4cda06075833e9b735a36a76f763a92f8ff44f244b6cf380be585f
- Edition-Digest: a696900f9d9809ff4c89c66b38b198d0811b7912d200751491433c0062adae6f
- Source-Revision: sha256:ec6d0eb09632b80b606b7f7bec6d12f962df0b38f1c1dda1dfd8676d15d43104

## Prerequisite

Use GitHub Copilot CLI with its direct MCP configuration support. This route is intentionally separate from the VS Code / GitHub Copilot Chat OAuth route.

- Endpoint: https://xmemo.dev/mcp.
- Transport: streamable-http.
- Auth mode: direct bearer token from XMEMO_KEY or a supported secret reference.
- Config file: ~/.copilot/mcp-config.json.

## Install / setup

Add the existing XMemo server block to ~/.copilot/mcp-config.json under mcpServers. Do not reuse the VS Code servers-key entry; Copilot CLI is a different client path.

- Keep the hosted URL and the 30000 millisecond timeout from the reviewed block.
- Keep tools set to ["*"] as shown in the existing block.
- Use the direct bearer configuration, not browser OAuth.

## Set the credential

Set XMEMO_KEY in the environment used to launch Copilot CLI, or use the supported secret reference. Never commit or paste the real token into mcp-config.json.

```bash
export XMEMO_KEY='<your-xmemo-token>'
```

## Generate / confirm XMEMO_AGENT_INSTANCE_ID

Generate one non-secret value per local Copilot CLI install, persist it outside git, and reuse it after restarts so attribution stays stable.

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

## Preserve the existing config block

Use the existing Copilot CLI XMemo configuration block rendered on this page. Preserve type, URL, tools, timeout, Authorization environment reference, and the copilot-cli agent identity; replace only local placeholders.

## Restart the client

Restart Copilot CLI after changing mcp-config.json or XMEMO_KEY so it loads a fresh direct MCP connection.

## Test with a real recall call

Make the first MCP call read-only. This is an actual recall invocation, not a health-check placeholder, and it does not write memory.

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

## Expected response (literal shape)

A successful call returns the public ranked text shape below; the reference and content are real values from the authorized memory space.

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

## Common Errors

Copilot CLI is a direct bearer-token client, so its failures differ from the VS Code OAuth route.

- 401 invalid_token — XMEMO_KEY is missing, expired, revoked, or otherwise invalid: verify the active CLI environment or secret reference, then restart.
- 403 insufficient_scope — the token does not grant memory:read: issue a token with the required scope.
- Invalid XMEMO_AGENT_INSTANCE_ID values are normalized to no instance attribution rather than raising an auth error: regenerate a stable value using allowed characters and persist it.

## 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": "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>"
      }
    }
  }
}
```