GEODE는 MCP의 양쪽에 다 섭니다. 클라이언트로서 외부 MCP 서버의 도구를 에이전트 도구 목록에 합치고(core/mcp/), 서버로서 자신의 능력을 다른 MCP 호스트에 노출합니다 (geode-mcp, core/mcp_server.py).
클라이언트: 서버 설정과 우선순위
core/mcp/manager.py의MCPServerManager가 세 곳에서 서버 설정을 읽습니다. 같은 이름이 겹치면 더 가까운 쪽이 이깁니다.
manager는 기존 호출 경로를 유지하는 facade입니다. 설정·env는config_catalog.py, stdio 연결과 재시작은connection_pool.py, 도구 발견·호출·결과 보정은tool_runtime.py, signal/atexit 정리는lifecycle.py가 각각 소유합니다.
| 우선 | 위치 | 역할 |
|---|---|---|
| 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 로그를 반복해서 쌓지 않기 위한 장치입니다. 운영자가 설정을 고쳤거나 서버를 강제로 재시작하는 경우에는 헬스 체크와 서버 재등록 경로가 이 실패 캐시를 비우고 다시 연결을 시도합니다.
실행 신뢰와 broker 경계
서버 설정은 명령을 찾기 위한 매니페스트일 뿐 승인 자체가 아닙니다. 아래 mcp:filesystem ID를확장 신뢰 정책에서도 같은 execution과 capability로 승인해야 합니다.
[mcp.servers.filesystem] command = "/usr/bin/acme-mcp" args = ["--workspace", "/work"] execution = "brokered" capabilities = ["stdio"] resource_keys = ["workspace"] [mcp.servers.filesystem.env] LOG_LEVEL = "warning"
| 모드 | 실행 계약 |
|---|---|
trusted | 운영자가 완전히 신뢰한 호환 경로입니다. 기존처럼 sandbox 없이 실행되고 프로세스 환경을 상속합니다. |
brokered | 기본 거부·네트워크 차단 OS sandbox 안에서 시스템 runtime 읽기와 격리 scratch만 허용하고, 설정에 적힌 env만 전달합니다. 지원되는 sandbox-exec 또는 bwrap가 없으면 실행하지 않습니다. |
읽기 전용 여부는 MCP tool annotation의 readOnlyHint로 판단합니다. 그 외 도구는 config에 하나 이상의 정적resource_keys가 있어야 하며, 없으면 dispatch 전에 거부됩니다. GEODE는 MCP 인자 이름을 보고 resource identity를 추측하지 않습니다.
클라이언트: 실행 경로와 가드
발견된 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에 채웁니다. |
서버가 REJECTED 또는 DEGRADED | 정책 누락·불일치, broker sandbox 부재, 명령 또는 env 해석 실패 | runtime health의 extensions에서 정확한 reason을 확인합니다. brokered 서버를 sandbox 없는 trusted 경로로 자동 하향하지 않습니다. |
| 변경 도구가 resource-key 오류로 거부됨 | 쓰기 가능한 도구인데 server config에 resource_keys가 없음 | 실제 변경 대상을 대표하는 보수적 정적 key를 매니페스트에 선언합니다. |
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의 자세한 동작.