GEODE는 MCP의 양쪽에 다 섭니다. 클라이언트로서 외부 MCP 서버의 도구를 에이전트 도구 목록에 합치고(core/mcp/), 서버로서 자신의 능력을 다른 MCP 호스트에 노출합니다 (geode-mcp, core/mcp_server.py).
클라이언트: 서버 설정과 우선순위
core/mcp/manager.py의MCPServerManager가 세 곳에서 서버 설정을 읽습니다. 같은 이름이 겹치면 더 가까운 쪽이 이깁니다.
| 우선 | 위치 | 역할 |
|---|---|---|
| 1 | .geode/config.toml의 [mcp.servers] | 프로젝트 override. |
| 2 | ~/.geode/config.toml의 [mcp.servers] | 전역 사용자 설정. |
| 3 | .claude/mcp_servers.json | 레거시 폴백 겸 설치 타깃. 앞 두 층에 없는 이름만 추가됩니다. |
서버 env의 ${VAR} 참조는 os.environ을 먼저 보고, 없으면 .env 값(전역 먼저, 프로젝트가 덮음) 으로 확장됩니다. 필수 env가 빈 값으로 해석된 서버는 연결을 시도하지 않고 건너뜁니다. 연결과 실패는MCP_SERVER_CONNECTED /MCP_SERVER_FAILED 훅으로 관측됩니다. 전송은 stdio입니다(core/mcp/stdio_client.py).
stdio 서버 연결이 실패하면 같은 서버는 짧은 시간 동안 실패로 기억됩니다. 도구 목록을 다시 만들 때 같은 프로세스를 즉시 재시도해 MCP_SERVER_FAILED 로그를 반복해서 쌓지 않기 위한 장치입니다. 운영자가 설정을 고쳤거나 서버를 강제로 재시작하는 경우에는 헬스 체크와 서버 재등록 경로가 이 실패 캐시를 비우고 다시 연결을 시도합니다.
클라이언트: 실행 경로와 가드
발견된 MCP 도구는 네이티브 도구와 합쳐져 에이전트에 노출됩니다(core/agent/loop/_tool_factory.py). 도구 수가 임계값을 넘으면 deferred loading이 켜져tool_search로 찾아 로드합니다. 검색 스코어링은core/mcp/registry.py에 있습니다.
- 서버 단위 승인. 처음 쓰는 서버는 사용자 확인을 거치고, 승인은 서버 단위로 기억됩니다 (
core/agent/tool_executor/executor.py). - 시크릿 마스킹. 결과의 텍스트 필드는 반환 전에
redact_secrets를 통과합니다. - 결과 크기 가드. 모든 도구 결과는
settings.max_tool_result_tokens(기본 25000)를 넘으면 요약을 보존한 채 잘립니다 (core/agent/tool_executor/result_token_guard.py). MCP 결과도 예외가 아닙니다. 200K 미만 컨텍스트 모델은 창의 5%로 한 번 더 조여집니다.
세션 안에서는 /mcp로 서버 상태, 도구 목록, 추가를 관리합니다.
서버: geode-mcp
geode-mcp는 GEODE의 1급 엔트리 포인트입니다. 에이전트 원샷(run_agent), 메모리 검색 (query_memory), 자기개선 루프의 2단계 propose/apply, 헬스 체크를 MCP 도구로 노출합니다. 저장소 루트의 .mcp.json이 이 서버를 stdio로 등록해 출하되므로, 이 프로젝트를 연 Claude Code 세션은 바로 쓸 수 있습니다. 수동 등록은 한 줄입니다.
claude mcp add geode -- geode-mcp
기본 전송은 stdio입니다. 클라이언트가 프로세스를 직접 띄우는 로컬 전용 경로입니다. 원격 접근은 --http로 streamable HTTP 전송을 켭니다.
geode-mcp --http --host 127.0.0.1 --port 8765
| 바인드 | 토큰 | 동작 |
|---|---|---|
| loopback | 없음 | 허용하되 경고 로그. stdio와 같은 신뢰 경계입니다. |
| loopback 아님 | 없음 | 거부, exit code 2. run_agent가 bash와 파일 도구까지 닿는 원격 실행 표면이므로 토큰 없는 네트워크 바인드는 fail-loud입니다. |
| 아무 곳 | GEODE_MCP_TOKEN | bearer 토큰 인증. 시크릿이므로 C-2 계약대로~/.geode/.env에 둡니다. 기동 시 공유load_env_files 승격이 먼저 돌아 거기 적힌 토큰을 찾습니다. |
실패 모드
| 증상 | 원인 | 해법 |
|---|---|---|
| 서버가 목록에 있는데 도구가 없음 | 필수 env 미해석으로 연결 건너뜀 | /mcp로 상태를 보고, 참조된 ${VAR}를 .env에 채웁니다. |
MCP_SERVER_FAILED 로그가 많음 | 서버 명령을 찾지 못하거나 필수 환경이 빠짐. launchd로 띄운 serve는 셸보다 PATH가 좁을 수 있음 | ~/.geode/logs/serve.log에서 실패 서버 이름을 보고 command -v npx, command -v codex, command -v uvx가 serve 환경에서도 보이게 맞춥니다. 수정 후 serve를 재시작하면 실패 캐시가 비워집니다. |
| MCP 결과가 잘려서 옴 | 결과 크기 가드 작동 | 정상 동작입니다. 더 좁은 쿼리로 다시 호출하거나 max_tool_result_tokens를 조정합니다. |
geode-mcp --http가 exit 2 | 비 loopback 바인드에 토큰 없음 | GEODE_MCP_TOKEN을 ~/.geode/.env나 환경에 설정합니다. |
다음
- CLI와 슬래시 명령. geode-mcp 도구 표면의 전체 레퍼런스.
- 리서치·탐색과 llms.txt. 외부 호스트에서 query_memory를 쓰는 맥락.
- 도구와 툴셋. deferred loading의 자세한 동작.