MCP와 도구

zqagent 실행 시 MCP(Model Context Protocol)로 외부 도구를 주입할 수 있습니다. 내장 OCR은 바로 사용할 수 있고 /tool add로 명령 도구도 만들 수 있습니다.

MCP 서버 설치

명령	설명
`/mcp`	서버, 연결 상태, 도구 수 나열
`/mcp add`	대화형 설치: 템플릿 선택 → 매개변수 입력 → 연결 후 저장
`/mcp add <name> stdio <cmd...>`	로컬 프로세스 수동 추가
`/mcp add <name> http\|sse <url>`	원격 엔드포인트 수동 추가
`/mcp import [file]`	구성 가져오기. 파일이 없으면 JSON을 붙여넣고 `EOF`로 종료
`/mcp rm\|enable\|disable\|refresh [name]`	제거 / 활성화 / 비활성화 / 도구 목록 새로고침

내장 템플릿: Filesystem, Memory, Sequential Thinking, GitHub, Fetch, PostgreSQL, OCR.

기존 구성 가져오기

/mcp import는 순수 배열, { "servers": [...] }, Claude Desktop / Cursor의 mcpServers 객체 형식을 지원합니다:

json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    },
    "remote": {
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" }
    }
  }
}

type을 생략하면 builtin / url / command에서 추론합니다. url이 /sse로 끝나면 SSE로 추론합니다.
command는 문자열일 수 있고 args 배열과 자동 병합됩니다. ${VAR} / ${env:VAR} 환경 변수 확장도 지원.
저장 시 배열 형식으로 .agent/mcp.json에 기록합니다(프로젝트와 함께 이동하며 git 커밋 가능). 같은 이름 항목을 가져올 때는 덮어쓸지 건너뛸지 개별 확인합니다.

내장 OCR

내장 OCR은 기본으로 활성화됩니다({ "name": "ocr", "type": "builtin", "builtin": "ocr" }). 도구 이름은 mcp__ocr__recognize입니다.

입력: imagePath(권장, 워크스페이스 내 경로), imageBase64, imageUrl. PDF는 페이지별로 인식합니다(maxPages 기본 5, dpi 기본 150).
엔진은 자동으로 단계적으로 대체됩니다: macOS Vision(Xcode Command Line Tools 필요) → tesseract + pdftoppm → 구성된 멀티모달 모델.
모두 사용할 수 없으면 error와 how_to_fix를 반환하며 시작이나 다른 도구를 막지 않습니다.
끄려면: /mcp disable ocr.

Linux 서버 이미지에는 tesseract-ocr, tesseract-ocr-chi-sim, poppler-utils가 내장되어 있습니다. 로컬 환경에서는 시스템 패키지 관리자로 설치할 수 있습니다:

# macOS
brew install tesseract tesseract-lang poppler
# Debian / Ubuntu
apt-get install -y tesseract-ocr tesseract-ocr-chi-sim poppler-utils

필요할 때 로드

MCP 도구가 많을 때(기본 16개 이상 또는 schema 합계 24000자 이상) 자동으로 필요할 때 로드 방식으로 전환합니다:

mcp__*를 전부 보내지 않고 mcp_search_tools(검색)와 mcp_call_tool(호출)을 사용합니다.
모델이 먼저 검색하고, 적중한 도구는 다음 턴에 로드됩니다(세션당 최대 40개). 메타 도구로 직접 호출할 수도 있습니다.
규모가 작으면 기존처럼 전부 주입되며 동작이 바뀌지 않습니다. ZQAGENT_MCP_LAZY=1|0으로 강제할 수 있습니다.

명령 도구

명령	설명
`/tool add <name> <cmd...>`	명령 도구 추가(shell 명령 실행)
`/tool rm\|disable\|enable <name>`	도구 제거 / 비활성화 / 활성화

즉시 반영과 저장

도구의 추가 / 제거 / 비활성화 / 교체는 다음 대화부터 즉시 반영되며 재시작이 필요 없습니다.

MCP 서버와 명령 도구 구성은 프로젝트와 함께 저장되며 git에 커밋해 팀과 공유할 수 있습니다. MCP가 주입하는 도구(내장 OCR 포함)는 기본적으로 고위험으로 처리되며 대화형 모드에서는 매번 승인이 필요합니다.

MCP와 도구 ​

MCP 서버 설치 ​

기존 구성 가져오기 ​

내장 OCR ​

필요할 때 로드 ​

명령 도구 ​

즉시 반영과 저장 ​

다음 단계 ​