sovereign-mcp-gateway

Model Context Protocol 서버용 게이팅 프록시. MCP 클라이언트를 서버 대신 게이트웨이에 연결하세요. 게이트웨이는 나열한 모든 업스트림에 연결하고, 해당 도구 카탈로그를 하나로 병합하며, 모든 호출을 실행할 서버에 도달하기 전에 검증 체인을 통과시킵니다.

pip install sovereign-mcp-gateway
sovereign-mcp-gateway --init          # writes gateway.json from the servers you already run
sovereign-mcp-gateway --config gateway.json --check

--init는 이미 보유한 MCP 구성(Claude Desktop, Claude Code, Cursor, VS Code 또는 Windsurf)을 읽고 동일한 서버를 프록시하는 gateway.json을 작성하므로, 첫 실행 시 구성 오류가 아닌 작동하는 구성이 생성됩니다. 게이트웨이 자신의 항목은 가져오지 않습니다. 자기 자신을 프록시하게 되기 때문입니다.

게이트웨이 자체가 MCP 서버이므로, MCP를 지원하는 모든 클라이언트는 변경 없이 작동합니다.

기본 설치만으로도 작동하는 게이트웨이입니다. 선택적 확장 4개가 그 위에 추가 레이어를 더합니다 — 설치 참조.

차단하는 것

에이전트가 GitHub 이슈를 읽는데, 그 본문에 사용자가 아닌 모델을 겨냥한 지시가 담겨 있습니다. 에이전트는 설득당해 git_commit을 호출합니다.

동일한 도구, 동일한 인수, 동일한 서버. 차이는 거부할 수 있는 위치에 무언가가 있었는지 여부입니다.

워크스루 읽기: 에이전트가 이슈를 읽습니다 — 또는 직접 실행:

pip install "sovereign-mcp-gateway[all]" mcp-server-git
python examples/poisoned_issue.py

Related MCP server: Agentrim MCP

라이브러리가 아닌 프록시인 이유

라이브러리는 서버를 작성한 사람이 채택해야 합니다. 프록시는 수정할 수 없는 서버를 보호합니다 — 대부분의 서버가 그렇습니다. 유용한 MCP 서버는 다른 사람이 유지 관리하는 게시된 패키지이기 때문입니다.

또한 에이전트가 도달할 수 있는 모든 서버에 걸쳐 정책을 한 곳에 두고 감사 추적을 하나로 유지할 수 있습니다. 아무도 동기화하지 않는 서버별 구성을 두는 대신 말입니다.

구성

이미 실행 중인 것에서 시작

$ sovereign-mcp-gateway --init

Wrote gateway.json

  imported 3 servers from Claude Desktop
    /Users/you/Library/Application Support/Claude/claude_desktop_config.json
  imported 1 server from VS Code (project)

  upstreams: fetch, git, sqlite, time

  skipped:
    sovereign - this gateway - importing it would proxy itself
    notion    - no command, probably a remote/SSE server
    git       - already imported from another client

하지 않는 네 가지: 자신을 가져오지 않고, 하위 프로세스로 실행할 수 없는 원격 서버를 가져오지 않으며, --force 없이 기존 파일을 덮어쓰지 않고, 선택하지 않은 deny_tools 목록을 작성하지 않습니다. 파일을 작성하고, 무엇을 가져왔고 무엇을 남겼는지 알려준 다음 중지합니다.

--init과 함께 --config PATH를 전달하면 ./gateway.json이 아닌 다른 위치에 작성합니다.

실행 후 클라이언트에서 해당 서버들을 게이트웨이 단일 항목으로 교체하세요. 둘 다 남겨두면 에이전트가 프록시를 통해서뿐만 아니라 직접 서버에도 접속하게 되고, 감사 추적에는 트래픽의 절반만 표시됩니다.

{
  "servers": {
    "git":    {"command": "mcp-server-git",    "args": ["--repository", "/repo"]},
    "sqlite": {"command": "mcp-server-sqlite", "args": ["--db-path", "/data.db"]}
  },
  "policy": {"deny_tools": ["git__git_reset"], "pii_policy": "warn"},
  "audit":  {"path": "gateway-audit.jsonl"}
}

클라이언트가 보기 전에 연결을 확인하세요:

sovereign-mcp-gateway --config gateway.json --check

SOVEREIGN GATEWAY - configuration check
upstreams: 2
layers:   policy -> intent -> text-filter -> frozen-verify -> audit

EXPOSED AS                             UPSTREAM TOOL
git__git_status                        git.git_status
git__git_reset                         git.git_reset          [DENIED]
sqlite__read_query                     sqlite.read_query
...
18 tools exposed.

체인

policy → intent → text-filter → frozen-verify → [ call executes ] → output-verify → logic-rules → audit

설치

기본 설치는 스텁이 아닌 작동하는 게이트웨이입니다:

pip install sovereign-mcp-gateway

이것으로 policy → frozen-verify → audit이 제공되며, 이미 업스트림이 노출하지 않는 도구, 잘못된 유형의 인수, 선언되지 않은 매개변수, 거부 목록의 도구, 인수의 프롬프트 주입을 거부합니다. 다른 것은 필요 없습니다.

각 확장이 그 위에 레이어를 추가합니다:

원하는 것을 조합하거나 모두 가져오세요:

pip install "sovereign-mcp-gateway[text]"             # one extra
pip install "sovereign-mcp-gateway[text,intent]"      # several
pip install "sovereign-mcp-gateway[all]"              # every layer

네 가지 확장 모두 작은 순수 Python 패키지입니다 — [all]은 컴파일된 의존성이나 실행할 서비스를 추가하지 않습니다.

부분 설치는 눈에 띄게 성능이 저하됩니다. 게이트웨이는 시작 시 활성 레이어를 출력하므로 실제로 실행 중인 것을 항상 확인할 수 있습니다:

layers:   policy -> frozen-verify -> audit                                  # base
layers:   policy -> intent -> text-filter -> frozen-verify -> audit         # [all]

레이어가 해당 줄에 없으면 실행 중이 아닙니다 — 설치했다고 생각하는 것과 무관합니다.

종단 간 검증

실제 업스트림으로 실행되는 mcp-server-git 및 mcp-server-sqlite를 대상으로, 실제 MCP 클라이언트로 구동:

이후 저장소에는 여전히 커밋이 하나 있고 데이터베이스에는 정확히 있어야 할 행만 있습니다 — 게이트웨이 자체 보고를 신뢰하지 않고 직접 열어 확인했습니다. 10개 호출에 대한 감사 기록 11개; 그중 하나라도 편집하면 체인이 깨집니다.

이 사례들은 스크린샷이 아닌 테스트 스위트입니다: pytest tests/ -v.

레이어 C: N-모델 합의

다른 모든 레이어는 결정적이고 로컬입니다. 레이어 C는 예외입니다: 여러 독립적인 모델에게 도구 결과에서 동일한 구조화된 문서를 추출하도록 요청하고, 각 답변을 정규화한 다음 SHA-256 해시를 비교합니다. 합의는 문장이 아닌 해시로 결정됩니다.

구성하지 않으면 꺼져 있습니다. 호출당 비용과 지연 시간이 발생하는 유일한 레이어이고, 도구 출력을 모델에 보내는 유일한 레이어이기 때문입니다.

{
  "servers": { "...": {} },
  "consensus": {
    "providers": [
      {"type": "local", "model": "llama3.1:8b"},
      {"type": "local", "model": "qwen2.5:7b", "base_url": "http://localhost:11434/v1"},
      {"type": "openrouter", "model": "anthropic/claude-3.5-sonnet",
       "api_key_env": "OPENROUTER_API_KEY"}
    ]
  }
}

두 가지 공급자 유형: local (OpenAI 호환 엔드포인트 — Ollama, vLLM, LM Studio; base_url 기본값은 http://localhost:11434/v1) 및 openrouter (키는 명명된 환경 변수에서 읽으며, 구성에 절대 기록되지 않음).

게이트웨이가 런타임이 아닌 시작 시 적용하는 세 가지 규칙:

• 공급자 최소 2개. 하나의 모델은 스스로와 의견이 다를 수 없습니다. 하나의 합의는 모든 호출에서 일치를 보고하는데, 이는 검증처럼 보이기 때문에 레이어가 없는 것보다 나쁩니다.

• 중복 모델 없음. 동일한 모델의 인스턴스 두 개가 일치하는 것은 독립적 검증이 아닙니다.

• API 키가 없으면 시작을 거부합니다. 레이어 없이 실행하는 것으로 대체되지 않습니다.

모든 공급자는 temperature = 0으로 실행되며, 생성자에서 강제됩니다.

레이어를 신뢰하기 전에 모델이 일치하는지 확인

--check는 구성된 모델에 대해 실제 합의 호출 한 번을 실행하고 무슨 일이 일어났는지 알려줍니다. 이것은 생각보다 중요합니다:

LAYER C  - probing the configured models with one real call
--------------------------------------------------------------
  OK. The configured models produced identical documents.
  Layer C will pass ordinary output rather than refusing it.

합의는 정규화된 해시를 비교하므로, 의미상 모두 올바르지만 구조가 다른 두 모델은 절대 일치하지 않습니다. 스키마를 그대로 반향하는 더 약한 모델은 —

{"branch": {"type": "string", "value": "main"}}   instead of   {"branch": "main"}

— 모든 호출에서 영원히 불일치하며, 게이트웨이는 "모델이 의견이 달랐다"고 정확히 읽히는 이유로 모든 것을 거부합니다. 실제로 그랬기 때문입니다.

프로브는 세 가지 결과를 구분합니다:

sovereign-mcp-gateway[consensus] 또는 [all]을 설치하세요 — HTTP 공급자에는 requests가 필요하며, 핵심 라이브러리는 의도적으로 의존하지 않습니다.

--check는 활성 레이어도 나열하므로 한눈에 확인할 수 있습니다:

layers:   policy -> intent -> text-filter -> frozen-verify -> consensus -> audit

해당 줄에 consensus가 없으면 구성에 무엇이 있든 실행 중이 아닙니다.

네임스페이싱

namespace가 켜져 있으면(기본값) 도구가 git__git_status로 노출됩니다. 동일한 도구 이름을 제공하는 두 업스트림은 충돌하거나, 서로를 가리거나, 잘못된 네임스페이스를 통해 도달할 수 없습니다. 업스트림이 하나뿐인 경우에만 끄세요.

정책

"policy": {
  "deny_tools":  ["git__git_reset", "write_query"],
  "allow_tools": null,
  "pii_policy":  "warn",
  "fail_closed": true,
  "rate_limit_interval": 0
}

• **deny_tools**는 노출된 이름(git__git_reset) 또는 업스트림 도구 이름(git_reset, 해당 업스트림이 있는 모든 곳)과 일치합니다.

• **allow_tools**는 설정된 경우 목록에 없는 모든 것을 거부합니다.

• **pii_policy**는 기본값이 block이 아닌 warn입니다. 실제 도구는 개인 데이터를 일반 출력으로 반환합니다 — 모든 git log 항목에는 작성자 이메일이 포함되어 있으며, 이를 차단하면 게이트웨이를 사용할 수 없게 됩니다. 도구가 PII를 절대 출력해서는 안 되는 경우 block으로 설정하세요.

• **fail_closed**는 레이어 자체가 오류를 일으킬 때 어떻게 할지 결정합니다. 기본값: 거부.

• **rate_limit_interval**은 0이며, 이는 행동 하한의 자체 상호작용 간 지연을 비활성화합니다. 그 지연은 신중하게 단계를 밟는 하나의 에이전트에게는 적합하지만, 도구 호출의 폭주가 일반적인 트래픽인 프록시에는 부적합합니다.

• **entropy_policy**는 기본값이 warn입니다. 텍스트 필터의 엔트로피 휴리스틱은 산문 속에 숨겨진 인코딩된 페이로드를 찾아내지만, 도구 인수는 일반적으로 구조화되어 있습니다 — 경로, 식별자, 해시 — 높은 엔트로피가 정상인 경우입니다. 임시 디렉터리 경로만으로도 합법적인 호출이 거부될 수 있었습니다. 인수가 정말로 산문인 경우 block으로 설정하세요.

이 도구가 하지 않는 것

고정된 정의에 대해 호출을 검증하고 인수와 결과를 검사합니다. 서버의 소스를 읽지 않으므로, 존재하고 호출되지만 조용히 아무것도 하지 않는 검사를 볼 수 없습니다. 그런 것은 여전히 구현을 읽는 사람이 필요합니다.

또한 손상된 업스트림이 올바르게 보이는 데이터를 반환하는 것을 보호할 수 없습니다 — sovereign-mcp의 Layer C 합의가 이를 해결하며, 직접 구성하는 모델 제공자가 필요합니다.

라이선스

Business Source License 1.1 — LICENSE 참조.

소스는 공개되어 있습니다. 읽고, 수정하고, 파생 저작물을 만들고, 개발, 평가 및 기타 비프로덕션 목적으로 무료로 사용할 수 있습니다.

프로덕션 사용도 무료입니다 — 개인 또는 4인 이하 조직의 경우. 이는 여기에만 명시된 것이 아니라 라이선스에 추가 사용 허가(Additional Use Grant)로 명시되어 있습니다. 더 큰 조직은 상업용 라이선스가 필요합니다.

각 버전은 게시 후 4년이 되는 변경일(Change Date)에 Apache 2.0으로 전환됩니다.

프로덕션용 라이선스를 받거나 사용에 라이선스가 필요한지 문의하려면: contact@sovereign-shield.net