Configure the direct bearer-token Copilot CLI MCP client with XMEMO_KEY and stable instance attribution.
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.
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.
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.
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.
### 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 MCP configuration
Configuration file: ~/.copilot/mcp-config.json
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>"
}
}
}
}
Client readiness
- Evidence required
- Marketplace pending
- See /product/docs#client-capability-matrix; the direct Copilot CLI path still needs current client evidence.