mcp-exports

사내 MCP 서버들을 위한 공용 단일 사용 다운로드 호스트입니다.

https://exports.example.com · 호스트 포트 8114 · 고객 로그인 없음

MCP server  --POST /put  (service token)-->  mcp-exports  -->  download URL
customer    --GET  /d/{token} (no auth)  -->  mcp-exports  -->  the file, once

존재 이유

일주일 분량의 통화 기록을 인라인으로 반환하는 도구는 약 530,000 토큰을 소비합니다. 같은 데이터를 CSV로 제공하면 1MB이고 1.6초 만에 생성됩니다. 그래서 내보내기는 링크를 반환합니다. 첫 번째 버전은 MCP 서버 자체에서 그 링크를 제공했는데, 세 가지 방식으로 문제가 발생했습니다:

1. MCP 호스트는 Anthropic 전용 IP 허용 목록 뒤에 있습니다. 하지만 다운로드를 가져오는 것은 임의의 주소에 있는 고객의 브라우저입니다. 별도의 호스트 이름은 두 액세스 정책이 충돌하지 않게 해줍니다. MCP에 필요한 스트리밍 설정을 담은 프록시 설정에서 경로 예외를 뚫는 대신 말입니다.

2. MCP 컨테이너는 푸시할 때마다 재배포되며, 인메모리 저장소도 함께 사라졌습니다. 그 결과 대화 중에 유효한 링크가 무효화되었습니다.

3. 저장소는 하나의 프로세스에 속해 있었기 때문에, 두 번째 워커는 무작위로 404를 반환했습니다.

Related MCP server: agent-secret

보안 모델, 명확히 말하면

다운로드 URL은 **권한(capability)**입니다. 그것을 가진 사람은 누구나 로그인 없이 파일을 얻습니다. 이는 우리가 이미 제공하는 NetSapiens 녹음 URL 및 Odoo 포털 PDF와 같은 트레이드오프이며, 채팅 창에서 클릭했을 때 링크가 작동하게 만드는 이유이기도 합니다. 이것은 인증이 아닙니다. 그리고 약점은 실제로 존재합니다. URL은 전달될 수 있고, 프록시에 기록될 수 있으며, 대화 기록에 영원히 남을 수 있습니다.

그래서 설계는 실제로 도움이 되는 것에 의존합니다:

업로드는 인증됩니다 — 서버별 베어러 토큰을 사용합니다. 공개 호스트에 파일을 게시하는 것은 인터넷이 마음대로 할 수 있는 일이 아니기 때문입니다. 서비스는 허용 목록이 비어 있으면 시작을 거부합니다.

API

POST /put?filename=x.csv&sensitivity=data|financial&customer=Acme%20Movers
     &ttl=3600&max_downloads=1
     Authorization: Bearer <server token>
  -> 201 {download_url, filename, size, expires_in_seconds, expires_at,
          max_downloads, single_use}

GET  /d/{token}   -> 200 the file (then it is gone), or 404
GET  /healthz     -> counters + bytes held

ttl은 그대로 따르지 않고 상한이 적용됩니다 — 일주일을 요청하면 MCP_EXPORTS_TTL_MAX를 받게 되며, 응답은 실제로 받은 값을 알려줍니다.

MCP 서버에서 사용하기

서버에 client/export_client.py를 복사하고 MCP_EXPORTS_URL + MCP_EXPORTS_TOKEN을 설정하세요. ExportClient.from_env()는 구성되지 않은 경우 None을 반환하므로, 서버는 항상 실패하는 도구를 광고하는 대신 호스트가 실제로 연결된 곳에서만 내보내기 도구를 제공할 수 있습니다.

인라인 행으로 폴백하지 않고 오류를 발생시킵니다. 호스트가 다운되면 안전한 저하가 없습니다. 행을 반환하는 것이 내보내기가 방지하려는 실패 모드이기 때문입니다.

배포

Portainer → Stacks → Repository, refs/heads/main, 포트 8114. MCP 서버별로 토큰을 생성하세요:

python -c "import secrets; print(secrets.token_urlsafe(32))"

NPM: exports.example.com → 10.0.0.10:8114, Access List 없음 (그게 핵심입니다), Websockets 끔, 표준 타임아웃.

테스트

python -m pytest tests -q

47개의 테스트, 네트워크 없음. 이 테스트는 보안 속성을 구체적으로 다룹니다: 단일 사용이 실제로 바이트를 삭제하는지, 모든 잘못된 토큰 형태가 구별 불가능한지, 파일 이름이 이스케이프하거나 헤더를 주입할 수 없는지, 금융 TTL이 더 짧은지, 그리고 Dockerfile이 root 권한을 내려놓기 전에 볼륨 마운트 지점을 chown하는지 — 그렇게 하지 않으면 named volume이 root 소유로 생성되어 모든 업로드가 EACCES로 실패합니다.