@loftbox/mcp

LoftBox 공식 MCP(Model Context Protocol) 서버. AI 에이전트가 LoftBox 이메일 인프라의 admin 평면(메일박스·도메인/DNS·메시징·검색·라벨·웹훅·억제·첨부·이벤트)을 표준 MCP 툴로 다룰 수 있게 한다.

차별점: HITL 승인 게이트 통합 — 발송이 승인 정책에 걸리면 pending_approval 로 큐잉되고, approval_queue_list / message_approve / message_reject 툴로 사람이 검토·결정한다.

1차 릴리스 범위: local stdio transport. 원격(streamable HTTP) transport 와 공개 레지스트리/Smithery 등재는 후속. routines·workflow marketplace·operator timeline 등 확장 admin 평면은 2차.

설치 / 실행

LOFTBOX_API_KEY=lb_live_xxx npx -y @loftbox/mcp

Claude Desktop

claude_desktop_config.json 에 추가(examples/claude_desktop_config.json 참고):

{
  "mcpServers": {
    "loftbox": {
      "command": "npx",
      "args": ["-y", "@loftbox/mcp"],
      "env": { "LOFTBOX_API_KEY": "lb_live_your_key_here" }
    }
  }
}

Cursor / 기타 MCP 클라이언트

동일하게 command npx -y @loftbox/mcp, env LOFTBOX_API_KEY 를 등록한다.

환경변수

| 변수 | 필수 | 기본 | 설명 | |---|---|---|---| | LOFTBOX_API_KEY | ✅ | — | LoftBox API 키(Bearer). | | LOFTBOX_BASE_URL | | https://api.loftbox.net | API 베이스 URL. | | LOFTBOX_TIMEOUT_MS | | 30000 | 요청 타임아웃(ms). |

툴 (28)

| 그룹 | 툴 | |---|---| | agents | agent_create agent_get agent_list | | mailboxes | mailbox_create mailbox_list inbox_list inbox_ack | | messages | message_send message_get message_list(q 검색·label·status 필터) | | labels | label_add label_remove | | HITL | approval_queue_list message_approve message_reject | | HITL 정책 | approval_policy_list approval_policy_create | | threads | thread_list thread_messages | | domains | domain_create domain_list domain_status(DNS 안내) | | suppressions | suppression_list suppression_add suppression_remove | | attachments | attachment_list attachment_url | | events | event_list |

각 툴은 MCP annotations(readOnlyHint·destructiveHint·idempotentHint· openWorldHint)로 부수효과를 알린다.

웹훅 등록(webhook_create)은 signing secret 이 1회만 반환되고 MCP 결과/로그 어디로도 흘리면 유출 표면이 되므로 1차에서 제외했다. secret 안전 전달 설계 후 후속.

권한(scope) 주의

다음 툴은 admin scope API 키가 필요하다. 키 권한이 부족하면 명확한 403 안내를 반환한다(서버는 죽지 않음):

• message_approve, message_reject
• approval_policy_create
• suppression_add, suppression_remove

보안 주의

• API 키는 LOFTBOX_API_KEY env 로만 주입한다. 신뢰된 로컬 환경에서 실행할 것.
• attachment_url 은 단명 서명 URL 을 반환한다 — 공유 금지, 즉시 사용.
• 발송·승인·억제·정책 생성 등 비가역 작업은 destructiveHint 로 표시된다.

개발

npm install
npm run typecheck && npm run build && npm test

MIT License.