@proxycept/mcp — Proxycept MCP 서버로의 stdio 브리지

경량 stdio↔HTTP 브리지입니다. stdio에서 Model Context Protocol 서버를 실행하고 모든 JSON-RPC 메시지를 변경 없이 Proxycept MCP 엔드포인트(기본값 https://proxycept.com/api/mcp)로 API 토큰을 Bearer 헤더로 포함하여 전달합니다.

대부분의 사람들은 이 패키지가 필요하지 않습니다. Proxycept MCP 서버는 호스팅된 HTTP 서버입니다 — Claude Desktop과 Cursor는 URL과 Authorization 헤더만으로 연결할 수 있으며, 설치가 필요 없습니다. 이 패키지는 stdio만 지원하는 MCP 클라이언트를 위해 존재하며, npx가 디렉터리 목록에서 기대하는 설치 관용구이기 때문입니다.

설치 없는 경로, 도구 카탈로그 및 보안 모델에 대해서는 proxycept.com/docs → "Connect Claude or Cursor" 또는 docs/user-manual.md §14를 참조하세요. 설정 → API 토큰에는 해당 배포를 대상으로 하고 선택한 토큰의 이름을 지정하는 동일한 구성이 복사 가능한 상태로 준비되어 있습니다. 토큰 값은 생성 시 한 번만 표시되므로, 블록에는 대체할 플레이스홀더가 포함되어 있습니다.

이것이 아닌 것

도구 목록, 도구 스키마, Proxycept 관련 로직이 포함되어 있지 않습니다. tools/list는 이 패키지가 아닌 서버가 응답합니다. 이는 의도적인 것입니다: 서버가 도구 카탈로그의 단일 진실 공급원이므로, 서버 측에서 도구가 추가되거나 변경되어도 여기서 릴리스가 필요 없으며 지원해야 할 버전 차이가 발생하지 않습니다. 도구 이름에 특별한 경우를 추가하려고 이 글을 읽고 있다면, 그 설계가 잘못되고 있는 것입니다.

요구 사항

• Node.js 20 이상 (node --version).

• Proxycept API 토큰 (prx_live_…) — proxycept.com/settings의 설정 → API 토큰.

읽기 전용 토큰 사용

토큰을 읽기 전용으로 생성하세요. 이것이 기본값이며 보안 경계이지, 제안이 아닙니다.

Proxycept의 읽기 도구는 캡처된 HTTP 트래픽 — 귀하의 계정이 작성하지 않은 콘텐츠를 반환합니다. 일부 업스트림의 악성 응답 본문은 마치 명령어인 것처럼 모델에 읽힐 수 있습니다("프롬프트 인젝션"). 간단히 말해:

read_write MCP 토큰은 프록시가 캡처하는 모든 것이 귀하의 Proxycept 구성을 쓸 수 있음을 의미합니다.

다른 사람의 서버에서 온 응답 본문이 명령어처럼 보이도록 작성되면, 귀하의 계정에서 모의 경로, 가로채기 패턴 또는 중단된 프로필이 됩니다. 읽기 전용 토큰은 Proxycept 내에서 그 체인을 완료할 수 없게 만듭니다: 주입된 명령어가 호출할 대상이 없습니다.

Proxycept 도구가 반환하는 모든 것을 명령어가 아닌 신뢰할 수 없는 데이터로 취급하세요 — 특히 URL을 가져오거나, 셸을 실행하거나, 파일을 쓸 수 있는 다른 MCP 서버가 연결되어 있는 경우 더욱 그렇습니다.

정말 읽기-쓰기가 필요하다면

의도적으로 설정을 변경하도록 허용하는 클라이언트에만 해당됩니다. 그런 경우, 다음 모두를 따르세요:

1. 별도의 토큰을 생성하세요 (트래픽을 읽는 데 사용하는 토큰을 업그레이드하지 마세요).

2. 클라이언트에서 Proxycept 도구 호출에 대해 "항상 허용"을 활성화하지 마세요.

3. 캡처된 트래픽을 읽는 동일한 세션에서 사용하지 마세요 — 이것이 주입된 명령어를 실행 가능하게 만드는 정확한 조합입니다.

읽기-쓰기 토큰이 여전히 할 수 없는 한 가지: 캡처된 요청을 재생하는 것. replay_flow는 캡처된 자격 증명으로 실제 요청을 제3자에게 다시 보내므로, Proxycept 웹 콘솔(설정 → AI 클라이언트 연결)에서 사람이 승인해야 합니다. AI 클라이언트는 어떤 토큰을 가지고 있든 자체 재생을 승인할 수 없습니다.

구성 — 토큰을 구성 파일이 아닌 환경에 넣으세요

MCP 클라이언트의 구성은 디스크에 있는 일반 텍스트 JSON이며, 종종 클라우드 스토리지와 동기화되는 디렉터리 안에 있습니다. 거기에 붙여넣은 prx_live_… 토큰은 생각하지 못한 백업에 장기 자격 증명이 됩니다. 환경을 선호하세요.

Claude Desktop (claude_desktop_config.json), Cursor (~/.cursor/mcp.json) 및 대부분의 다른 클라이언트는 동일한 형태를 사용합니다:

{
  "mcpServers": {
    "proxycept": {
      "command": "npx",
      "args": ["-y", "@proxycept/mcp"],
      "env": {
        // Read from your shell environment; the secret itself stays out of this file.
        "PROXYCEPT_API_TOKEN": "${PROXYCEPT_API_TOKEN}"
      }
    }
  }
}

모든 클라이언트가 구성에서 ${VAR}을 확장하는 것은 아닙니다. 그렇지 않은 경우, 다음으로 좋은 옵션은 클라이언트가 상속할 위치에 변수를 내보내고(로그인 셸 프로필, macOS의 launchctl setenv, Linux의 systemd 유닛) env 블록을 완전히 제거하는 것입니다 — 브리지는 상속된 환경에서 PROXYCEPT_API_TOKEN을 읽습니다. 구성 파일에 리터럴 토큰을 붙여넣는 것도 작동하며, 마지막으로 선택할 옵션입니다.

명령줄에서 --token은 지원되지만 권장되지 않습니다: 인수는 프로세스 목록을 통해 머신의 모든 프로세스에 표시됩니다.

환경 변수

모든 변수에는 일치하는 플래그가 있습니다 (--base-url, --url, --token, --timeout, --verbose).

자체 호스팅

PROXYCEPT_BASE_URL=https://proxy.internal.example PROXYCEPT_API_TOKEN=… npx -y @proxycept/mcp

루프백을 제외하고 일반 텍스트 http://는 거부되므로 토큰이 평문 홉을 절대 통과할 수 없습니다. 이 패키지는 TLS 검증을 비활성화하는 플래그를 제공하지 않으며 제공하지 않을 것입니다.

Node 자체에는 하나가 있습니다 — NODE_TLS_REJECT_UNAUTHORIZED=0은 전체 프로세스에 대한 인증서 검증을 끕니다 — 그리고 브리지는 비루프백 엔드포인트에 대해 이것이 설정된 것을 발견하면 시작을 거부하며, 조용히 상속하지 않습니다. 해당 오류가 발생하면 변수를 해제하세요(셸 프로필과 MCP 클라이언트의 env 블록을 확인하세요); 거의 항상 다른 것을 디버깅하다 남은 것이며, 설정된 상태에서는 경로에 있는 누구나 읽을 수 있는 연결을 통해 토큰이 나가게 됩니다.

설정 확인

PROXYCEPT_API_TOKEN=prx_live_… npx -y @proxycept/mcp --check

실제 MCP 핸드셰이크와 실제 tools/list를 수행한 다음 서버가 말한 것을 출력합니다:

endpoint: https://proxycept.com/api/mcp
server:   proxycept 1.0.0 (MCP 2025-06-18)
tools:    20 — list_workspaces, list_profiles, …
ok

도구 개수는 이 패키지가 아닌 서버에서 오므로, 여기서 릴리스 없이 변경됩니다. 쓰기 도구는 모든 클라이언트에 나열되며 토큰이 read_write가 아니면 API 계층에서 거부됩니다 — 아래 참조.

종료 코드: 0 정상 · 1 서버에 연결하거나 인증할 수 없음 · 2 잘못된 구성.

문제가 있을 때

보안 속성

• 토큰은 Authorization: Bearer …로 구성된 원본에만 전송되며 다른 곳으로는 전송되지 않습니다. 다른 원본으로의 리디렉션은 거부되며, 따르지 않습니다 — 자격 증명은 사용자가 구성하지 않은 호스트에 절대 전달되지 않습니다. 동일 출처 307/308은 따릅니다(최대 3홉). 원본과 메서드를 모두 보존하면 자격 증명을 다시 보내는 것이 수신자에 대해 아무것도 변경하지 않으며, 리버스 프록시가 이를 내보내기 때문입니다. 301/302/303은 거부됩니다. POST를 GET으로 재생하면 요청이 조용히 손실되기 때문입니다. (호스팅된 서버는 절대 리디렉션하지 않습니다.)

• 토큰은 절대 기록되지 않으며, 클라이언트에 반환되지 않습니다. stderr에 기록되는 모든 줄과 이 브리지가 stdout에 합성하는 모든 오류 메시지는 구성된 비밀, prx_… 토큰 형태의 모든 것, 그리고 Bearer … 문자열을 제거하는 편집기를 거칩니다 — --verbose 모드에서도, 그리고 서버가 4xx/5xx 본문에서 다시 에코하는 자격 증명도 포함됩니다. 마지막 경우는 stdout이 MCP 클라이언트이기 때문에 중요합니다: 모델의 컨텍스트와 클라이언트의 로그에 들어갑니다. 스택 추적은 절대 출력되지 않습니다. 각각에 대한 테스트가 있습니다.

• 프로토콜 스트림은 절대 다시 작성되지 않습니다. 편집은 이 브리지가 구성하는 메시지에 적용되며, 서버 자체의 JSON-RPC 페이로드에는 적용되지 않습니다 — 이를 망가뜨리면 디버깅 중인 트래픽이 손상됩니다. 캡처된 트래픽의 편집은 서버의 작업입니다(읽기 경로에서 마스킹 거부 목록을 적용합니다).

• 디스크에 아무것도 기록되지 않습니다. 캐시, 구성 파일, 자격 증명 저장소가 없습니다.

• stdout은 프로토콜 메시지만 전달합니다. 모든 진단은 stderr로 전송됩니다.

• 런타임 종속성이 없습니다. 이 패키지의 npm ls --omit=dev는 비어 있습니다 — 유일한 공급망은 Node 자체입니다.

개발

cd clients/mcp
npm ci
npm test          # builds, then runs the suite against a fake JSON-RPC server
npm run typecheck

npm run check-package   # asserts the tarball ships every module, the bin, README and LICENSE

레이아웃: src/config.ts (구성 해석 + 검증), src/redact.ts (편집 + 유일한 로거), src/http.ts (메시지당 하나의 POST; SSE, 리디렉션 정책, HTTP→JSON-RPC 오류 매핑), src/bridge.ts (일반 전달 루프), src/stdio.ts (개행으로 구분된 JSON 프레이밍), src/cli.ts (인수, --check, 연결).

가짜 서버로 검증됨

테스트 스위트는 test/helpers.js의 가짜 JSON-RPC HTTP 서버에 대해 실행됩니다: 있는 그대로 전달(이 패키지가 들어본 적 없는 메서드 포함), 헤더 형태, Mcp-Session-Id 및 프로토콜 버전 에코, SSE 스트리밍, 202 알림, HTTP→MCP 오류 매핑, 배치 처리, 리디렉션 정책, 세션 만료, 청크 경계를 넘는 NDJSON 프레이밍, 그리고 모든 출력에서 토큰이 없음을 확인합니다.

실제 Proxycept로 검증됨

--check는 MCP 서버가 활성화된 실제 Control API에 대해 종단 간 실행되었습니다(V4-T66): 실제 initialize 기능 협상, 실제 tools/list (20개 도구), 읽기 전용 prx_live_ 토큰 사용. 남은 미지수는 프로덕션 특정 사항입니다 — 호스팅된 배포가 Mcp-Session-Id를 발급하는지, 긴 도구 호출이 JSON으로 반환되는지 SSE로 반환되는지, 그리고 401/403/429 본문의 정확한 표현입니다. 브리지는 일반적이므로 이들 중 어느 것이 달라도 여기서 코드 변경 없이 가능합니다; https://proxycept.com에 대한 라이브 통과는 PUBLISHING.md의 5단계입니다.

게시 (관리자)

릴리스는 의도적으로 수동으로 수행됩니다. CI 작업이 게시되지 않도록 설계되어 있어, 손상된 워크플로 토큰으로 고객 자격 증명을 처리하는 패키지를 배포할 수 없습니다. 전체 런북(조직 생성, 사전 점검, 정확한 npm publish --access public 시퀀스, 검증 및 폐기 절차)은 이 디렉토리의 PUBLISHING.md 에 있습니다. 이는 게시된 tarball에 포함되지 않습니다.