MCP Agent Mail

왜 쓰나요

핵심 기능

에이전트별 고유 identity와 영속적인 수신함/발신함
모든 에이전트에 걸친 메시지 이력 전문 검색 (FTS5)
자발적 파일 lease — 경로를 점유하고 작업 완료 후 해제
HTTP 전용 FastMCP (Streamable HTTP), Docker로 배포 가능
포렌식을 위한 해시 체인 감사 로그
SaaS 의존성 없음 — 자체 인프라에서 실행

라이브 데모

실제 사용 모습

mcp-agent-mail.replay ▶ 준비됨

0/0

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcp-agent-mail": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8765/mcp"
      ]
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "mcp-agent-mail": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8765/mcp"
      ]
    }
  }
}

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "mcp-agent-mail": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8765/mcp"
      ]
    }
  }
}

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcp-agent-mail": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8765/mcp"
      ]
    }
  }
}

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "mcp-agent-mail",
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8765/mcp"
      ]
    }
  ]
}

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

{
  "context_servers": {
    "mcp-agent-mail": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "mcp-remote",
          "http://127.0.0.1:8765/mcp"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add mcp-agent-mail -- npx -y mcp-remote http://127.0.0.1:8765/mcp

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: MCP Agent Mail

동일 모노레포에서 3개의 Claude Code 세션을 병합 충돌 없이 조율

👤 병렬 에이전트 세션을 운영하는 팀 ⏱ ~30 min intermediate

언제 쓸까: 기능 브랜치별로 에이전트를 생성했는데 같은 파일을 계속 점유하려 할 때.

사전 조건

각 에이전트에서 접근 가능한 Docker 호스트 — docker compose up --build로 :8765 포트 노출
각 에이전트의 고유 identity — whoami 첫 호출 시 등록됨; CLAUDE.md에 고정

흐름

Identity 확인

Use mcp-agent-mail. Register me as claude-feature-auth and list active leases.✓ 복사됨

→ Identity 저장됨; lease 목록 반환
편집 전 파일 점유

Before editing src/auth/*, take a 30-min lease and announce intent in the #refactor thread.✓ 복사됨

→ Lease 승인됨; 다른 에이전트에게 메시지 표시
인계

Done with the auth module. Release leases, post a summary to #refactor with the diff range.✓ 복사됨

→ Lease 해제됨; 스레드 업데이트

결과: 3개의 에이전트가 서로의 편집을 덮어쓰지 않고 동일 레포에서 병렬 작업 완료.

함정

Lease는 자발적 — 에이전트가 무시할 수 있음 — CLAUDE.md에 규칙 추가: '편집 전 항상 lease 확인, 먼저 의도를 알릴 것'

함께 쓰기: filesystem · github

연관된 레포를 작업하는 에이전트 간 작업 인계

👤 프론트엔드/백엔드 에이전트를 동시에 관리하는 개발자 ⏱ ~20 min intermediate

언제 쓸까: 백엔드 에이전트가 API 변경을 완료했고, 프론트엔드 에이전트가 적응해야 할 때.

흐름

전송

From claude-backend: send claude-frontend a message titled 'New /v2/orders schema' with the OpenAPI diff.✓ 복사됨

→ 메시지 전송됨; 프론트엔드 에이전트 수신함 카운트 증가
수신

From claude-frontend: read inbox, summarize new messages, propose component updates.✓ 복사됨

→ 프론트엔드 에이전트가 변경 사항을 확인하고 작업 시작

결과: 직접 프롬프트를 복붙하지 않아도 에이전트 간 비동기 인계 완료.

함정

머신 간 identity 혼동 — hostname에 identity를 바인딩하거나 긴 랜덤 접미사 사용

모든 에이전트 메시지와 lease의 포렌식 추적 확보

👤 운영팀 / 에이전트 오동작 디버깅 ⏱ ~15 min intermediate

언제 쓸까: 에이전트가 새벽 3시에 이상한 작업을 했고 누가 무엇을 지시했는지 재구성이 필요할 때.

흐름

검색

Search messages between 02:00 and 04:00 mentioning 'database migration'.✓ 복사됨

→ 해시 앵커가 포함된 항목 반환
체인 검증

Verify the audit chain hasn't been tampered.✓ 복사됨

→ 체인 유효; 변조 감지 이상 없음

결과: 포스트모텀을 위한 에이전트 통신의 신뢰할 수 있는 기록.

함정

DB가 무한정 증가 — 보존 주기 설정; 월별 S3 아카이브

함께 쓰기: filesystem

조합

다른 MCP와 조합해 10배 효율

mcp-agent-mail + filesystem

병렬 에이전트를 위한 lease-후-편집 규율

mcp-agent-mail + github

다른 에이전트가 구독하는 스레드에 PR 알림 게시

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
whoami	(없음)	에이전트의 첫 호출	무료
send_message	to, subject, body, thread?	다른 에이전트에게 작업 인계할 때	무료
read_inbox	since?, limit?	세션 시작 시 — 대기 중인 항목 확인	무료
claim_lease	path, ttl_min, reason	다른 에이전트가 건드릴 수 있는 파일 편집 전	무료
release_lease	lease_id	커밋 후 / 작업 완료 시	무료
search_messages	query, from?, to?	포렌식 또는 컨텍스트 재발굴 시	무료

비용 및 제한

운영 비용

API 쿼터: 자체 호스팅; 하드웨어 사양에 따라 제한
호출당 토큰: 매우 적음 — 조율 호출당 약 50–200 token 오버헤드
금액: 무료 (MIT)
팁: 실행 비용은 저렴함; 실제 비용은 이중 작업을 피함으로써 절감되는 에이전트 호출 비용

보안

권한, 시크릿, 파급범위

최소 스코프: 에이전트 호스트와 메일 서버 간 네트워크 접근

자격 증명 저장: 선택적 bearer token (환경 변수)

데이터 외부 송신: 자체 인프라 내 유지 — 서드파티 호출 없음

절대 부여 금지: TLS + 인증 없이 공개 노출

메시지에 포함된 내용은 영구 검색 가능 — 비밀 정보 붙여넣기 금지

문제 해결

자주 발생하는 오류와 해결

:8765 포트 연결 거부

Docker 컨테이너 실행 중 및 포트 포워딩 확인; docker ps 점검

확인: curl http://127.0.0.1:8765/health

Identity 충돌

랜덤 접미사 추가하거나 hostname에 바인딩

오래된 에이전트가 lease를 점유 중

Lease는 TTL에 따라 자동 만료됨; 기본 TTL을 줄이거나 관리자 도구로 강제 해제

대안

MCP Agent Mail 다른 것과 비교

대안	언제 쓰나	단점/장점
공유 CLAUDE.md만 사용	에이전트 2개 이하, 낮은 동시성	상태 없음 — 에이전트들이 같은 파일을 읽는 것에 의존
에이전트별 Git 브랜치	완전한 격리가 필요할 때	병합 비용 증가; 실시간 신호 없음