Copilot CLI

사전 요구 사항

MCP 구성 지원이 포함된 GitHub Copilot CLI를 사용합니다. 이 경로는 VS Code / GitHub Copilot Chat OAuth 경로와 의도적으로 분리되어 있습니다. Copilot CLI는 ~/.copilot/mcp-config.json의 맞춤 HTTP 헤더 또는 memory-os-cli를 통한 로컬 프록시 연결을 지원합니다.

• 엔드포인트: https://xmemo.dev/mcp.
• 전송 방식: Streamable HTTP (구성 내 type: "http") 또는 로컬 프록시 (xmemo mcp proxy).
• 인증 모드: Copilot의 공식 MCP UI/CLI 또는 지원되는 시크릿 참조를 통해 Authorization을 적용합니다. 헤더 값에서 환경 변수 확장(${env:…})을 가정하지 마십시오.
• 구성 파일: ~/.copilot/mcp-config.json.
• 준비 상태: Copilot CLI 헤더에서의 직접 환경 변수 확장은 not-tested 상태입니다. 로컬 프록시 경로는 memory-os-cli MCP-SETUP-GUIDE.md를 통해 검증되었습니다.

설치 / 설정

~/.copilot/mcp-config.json의 mcpServers 아래에 XMemo 서버 블록을 추가하거나 memory-os-cli 로컬 프록시를 통해 실행합니다. VS Code의 servers 키 항목을 재사용하지 마십시오. Copilot CLI는 다른 클라이언트 경로입니다.

• 직접 원격 HTTP: type: "http", url: "https://xmemo.dev/mcp", timeout: 30000 및 tools: ["*"]를 사용하여 ~/.copilot/mcp-config.json에 XMemo 블록을 추가합니다.
• 로컬 프록시 경로: xmemo setup copilot을 실행하고 백그라운드 터미널에서 xmemo mcp proxy를 계속 실행합니다 (memory-os-cli MCP-SETUP-GUIDE.md 기준).
• 헤더 내 직접 환경 변수 확장(${env:XMEMO_KEY})은 not-tested 상태이며 Core 템플릿에서 지원되지 않습니다.

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

자격 증명 설정

Copilot의 공식 MCP UI/CLI 또는 지원되는 시크릿 참조를 사용하여 Authorization 헤더 값을 설정합니다 (<replace-with-XMEMO_KEY-or-supported-secret-reference>를 실제 토큰으로 교체). 로컬 프록시를 사용할 때 xmemo login이 자격 증명을 자동으로 관리합니다.

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

XMEMO_AGENT_INSTANCE_ID 생성 / 확인

Copilot CLI 로컬 설치마다 secret이 아닌 값을 하나 생성하고 git 밖에 저장한 뒤 재시작 후에도 재사용하여 attribution을 안정적으로 유지합니다.

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

기존 구성 블록 유지

Core의 템플릿 (mcp_config.py:267)과 일치하는 신뢰할 수 있는 Copilot CLI XMemo 구성 블록을 사용합니다. Copilot의 공식 MCP UI/CLI 또는 지원되는 시크릿 참조를 통해 실제 Authorization 값을 적용하십시오. 검증되지 않은 ${env:XMEMO_KEY} 헤더 확장에 의존하지 마십시오.

{
  "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>"
      }
    }
  }
}

클라이언트 재시작

mcp-config.json을 변경한 후 Copilot CLI를 다시 시작하십시오. 로컬 프록시를 사용하는 경우 Copilot CLI를 다시 시작하기 전에 백그라운드 터미널에서 'xmemo mcp proxy'가 계속 실행 중인지 확인하십시오.

실제 recall 호출로 테스트

첫 MCP 호출은 읽기 전용으로 수행합니다. 이는 health-check placeholder가 아닌 실제 recall 호출이며 memory를 쓰지 않습니다.

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

예상 응답 (리터럴 형태)

성공한 호출은 아래의 공개 ranked text 형태를 반환합니다. reference와 content는 승인된 memory space의 실제 값입니다.

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

일반적인 오류

Copilot CLI는 직접 토큰 또는 프록시 클라이언트입니다. 일반적인 오류는 인증 토큰, 프록시 수명 주기 또는 스코프 승인과 관련이 있습니다.

• 401 invalid_token — XMEMO_KEY가 누락되었거나 만료되었거나 취소되었거나 확장되지 않음: 활성 시크릿 참조를 확인하거나 로컬 프록시용 xmemo login을 다시 실행하십시오.
• 403 insufficient_scope — 토큰이 memory:read를 부여하지 않음: 필요한 스코프가 있는 토큰을 발급하십시오.
• Connection refused — 로컬 프록시를 사용하는 경우 백그라운드 터미널에서 xmemo mcp proxy가 실행 중인지 확인하십시오.
• 헤더에 리터럴 '${env:XMEMO_KEY}' 전송됨 — Copilot CLI가 헤더 값의 환경 변수를 확장하지 못할 수 있습니다. 시크릿 참조 또는 로컬 프록시를 사용하십시오.
• 잘못된 XMEMO_AGENT_INSTANCE_ID 값은 인증 오류를 발생시키는 대신 인스턴스 귀속 없음으로 정규화됩니다.