Skip to main content

Gerbang MCP

Pengagregat MCP Yabanin ialah proxy di sisi gerbang yang membolehkan organisasi mendedahkan mana-mana pelayan Model Context Protocol (MCP) luaran kepada ejennya — dengan kawalan akses ejen sahaja, senarai benarkan alat bagi setiap ejen, jejak audit, pemajuan identiti, kelayakan huluan (peringkat pelayan + kebenaran malas setiap pengguna), kebolehcerapan, dan pengawal parameter. Ia mati secara lalai: keseluruhan kumpulan laluan dipasang hanya apabila YABANIN_MCP_GATEWAY=1.

Nama itu bukan protokol. Walaupun nama "gerbang MCP", apa yang dihantar hari ini ialah API seruan: endpoint HTTP biasa POST /api/mcp/invoke (permintaan JSON, kunci ejen yag_*) yang sendiri memanggil pelayan MCP luaran melalui JSON-RPC. Klien MCP tidak boleh menyambung kepadanya: tiada tools/list dan tiada pengangkutan MCP yang berhadapan klien di sini. Endpoint MCP natif pada gerbang (katalog tools/list dan pelayan Streamable HTTP) ialah kerja masa hadapan yang dirancang (kad RM-100 dan RM-101); sehingga itu mendarat, satu-satunya antara muka berprogram pengagregat ialah API seruan yang diterangkan dalam §5.

Jambatan rakan keluar yang diterangkan dalam §1 ialah ciri berasingan yang sudah dihantar dan berada di luar skop di sini. Jambatan menjawab "ejen memanggil alat Yabanin"; pengagregat menjawab songsangan — "ejen Yabanin memanggil pelayan MCP luaran sewenang-wenang", dengan selamat.

1. Apa yang wujud hari ini (di luar skop pengagregat)​

Yabanin sudah menghantar jambatan rakan MCP keluar (pkg/mcppartner, services/run/mcp.go, subarahan binari mcp):

  • Pengangkutan: stdio (Claude Code) dan HTTP-SSE pada :8787 (YABANIN_MCP_HTTP=1).
  • Alat yang didedahkan: tr_route, tr_spend_report, tr_set_policy, tr_lineage_verify, serta tr_delegate / tr_delegation_status pilihan.
  • Pengesahan: kunci API rakan (YABANIN_PARTNER_API_KEY), dihantar sebagai Bearer ke gerbang :8082 dan pentadbir :8086.
  • Klien huluan: http.Client yang dihadkan (tamat masa 30 s); klien ini hanya bercakap dengan endpoint milik Yabanin sendiri — ia tidak sekali-kali mendail URL sewenang-wenang yang dibekalkan pengguna.

Pengagregat ialah kerja baharu: registri pelayan + kawalan akses, pemajuan identiti, metrik, dan pengawal parameter — semuanya pada satah data gerbang.

2. Tingkah laku​

  • Akses ejen sahaja. Seruan alat diterima hanya untuk kunci prinsipal ejen (yag_*, kunci prinsipal ejen). Kunci API yab_ biasa tidak mempunyai identiti ejen dan ditolak dengan 403 agent_only sebelum apa-apa dicari. Pengepala X-Agent-Id masuk dilucutkan pada kemasukan dan ditetapkan semula hanya daripada prinsipal yag_* yang dileraikan, supaya klien tidak boleh memalsukan ejen.
  • Geran setiap ejen + senarai benarkan alat. Ejen boleh menyeru pelayan hanya jika ia memegang geran yang didayakan bagi (org, agent, server); geran yang tiada atau dilumpuhkan tidak dapat dibezakan daripada "pelayan tidak tersedia" (404 not_found) — ejen tidak boleh menyenaraikan seruan mana yang disekat oleh geran. Set alat berkesan ialah persilangan senarai benarkan pelayan (mcp_servers.allowed_tools, siling) dan senarai benarkan geran (mcp_server_grants.allowed_tools). [] pada mana-mana sisi bermaksud "semua bagi sisi itu".
  • Keluar yang dikawal SSRF. URL huluan melepasi pengawal pkg/ssrf (senarai benarkan DNS + penolakan IP terpelihara) semasa pendaftaran dan sekali lagi pada setiap seruan (tetingkap pengikatan semula). Proxy tidak mengikut sebarang ubah hala dan menggunakan tamat masa sambung/baca yang dihadkan.
  • Jejak audit. Setiap seruan alat direkodkan ke strim peristiwa yang sama yang digunakan gerbang untuk permintaan sembang, jadi loggerd mengekalkan baris request_logs yang ditag dengan task_id, agent_id, dan upstream_url. Baris itu dilabel ModelUsed = "mcp:<server>:<tool>" (boleh dibezakan daripada inferens model). Gerbang tidak menulis request_logs secara langsung.
  • Pemajuan identiti. Prinsipal yang disahkan dibawa ke huluan sebagai pengepala X-Yabanin-Agent-Id, X-Yabanin-Agent-Name, dan X-Yabanin-Team-Id. Ini ialah atribusi, bukan kebenaran: pelayan luaran boleh menggunakannya untuk mengatribusikan seruan, tetapi ia tidak sekali-kali menjadi kelayakan, dan gerbang menetapkannya hanya daripada prinsipal yang disahkan (tidak sekali-kali daripada klien).
  • Kebolehcerapan. gateway_mcp_calls_total{server,tool,outcome} mengira setiap seruan (kejayaan atau kegagalan); satu span OTel bagi setiap seruan (mcp.tools/call) membawa mcp.server / mcp.tool / mcp.org / mcp.agent_id dan mcp.outcome akhir. Kedua-duanya direkodkan walaupun tiada pencatat audit yang diwayar. gateway_toolpolicy_decisions_total{org,server,tool,outcome} mengira setiap keputusan pagar OP-6 (allow / deny / mask / flag / error — error ialah gangguan stor dasar gagal-terbuka, seruan berjalan TANPA PAGAR).
  • Pagar seruan alat (OP-6). Parameter input alat melepasi cangkuk pengawal pra-keluar (guardhooks.Scan) dengan mod yang diwarisi daripada guard_mode (YABANIN_GUARD_MODE: off / log / redact / deny). redact menggantikan rahsia/PII yang dikesan sebelum keluar dan sebelum jejak audit (parameter klien asal tidak sekali-kali sampai ke audit); deny menggugurkan seruan (409 denied). Di atas itu, peraturan pagar setiap pelayan (tool_policies.rules) menambah semakan skema/saiz/regex pada argumen dan semakan pasca pada hasil — lihat §7.

Bukan-matlamat (buat masa ini)

  • pelayan stdio huluan (tiada pelancaran proses pada gerbang — permukaan keselamatan hos yang baharu; kaji semula selepas HTTP-SSE terbukti).
  • Perkongsian pelayan merentas organisasi — pelayan adalah bagi setiap organisasi.
  • Kependaman bagi setiap model pada skrin perbandingan — skrin perbandingan Model papan pemuka menunjukkan kos penilaian bayang bagi setiap model, persentil kependaman seluruh organisasi (berkapsyen sebagai bukan bagi setiap model) dan bahagian kualiti tersampel evalgate (ADL-04: bagi setiap pasangan murah/premium pada pertindihan yang dihakimi + bagi setiap kelas tugasan, dengan pengesyoran penghalaan yang diterapkan manusia). Kependaman bagi setiap model tidak diukur.

3. Seni bina​

agent (yag_* key, X-Yabanin-Task)
│ POST /api/mcp/invoke {"server":"knowledge","tool":"search","params":{...}}
▼
┌─────────────────────────── gateway proxy (:8082) ───────────────────────────┐
│ 0. agent-only: resolved yag_* principal, else 403 agent_only │
│ 1. server row: enabled? (404 not_found) │
│ 1b. grant: enabled grant for (org, agent, server)? (404 not_found) │
│ 2. tool allowed? server allow-list ∩ grant allow-list (404 not_found) │
│ 2c. toolpolicy guardrails: server-aware deny + args rules │
│ (schema/max_bytes/deny_regex) → 400 mcp_tool_blocked (OP-6) │
│ 3. ssrf: AllowList re-check (400 ssrf_blocked) │
│ 4. guard: guardhooks.Scan(params) → off/log/redact/deny (409 denied) │
│ 5. creds: resolve outbound auth — per-user active → server-level enabled │
│ → none; 401/403 upstream → one force-refresh retry, else lazy │
│ mcp_auth_required with the human flow URL (§6) │
│ 5b. proxy: JSON-RPC tools/call POST → upstream (bounded timeout) │
│ headers: X-Yabanin-Agent-Id / X-Yabanin-Agent-Name / X-Yabanin-Team-Id │
│ 6. record: gateway_mcp_calls_total{server,tool,outcome} + OTel span │
│ + audit event → loggerd → request_logs (task_id, agent_id, upstream_url) │
│ 6b. toolpolicy result post-check (secrets/deny_regex: flag|mask|deny) │
│ → 400 mcp_tool_blocked / redacted result (OP-6) │
└──────────────────────────────────────────────────────────────────────────────┘
▼
external MCP server (HTTP-SSE, e.g. an org's internal knowledge server)

Proxy berada dalam satah data gerbang (:8082, kumpulan laluan /api/mcp/...), bukan pentadbir — trafik ejen ialah satah data. Pentadbir memiliki CRUD mcp_servers dan CRUD geran setiap ejen; gerbang membaca kedua-duanya melalui stor yang sama yang digunakan tetapan organisasi/penghalaan.

Postur lalai: mati. Kumpulan laluan dikompil masuk tetapi dipasang hanya apabila YABANIN_MCP_GATEWAY=1 dan kolam pangkalan data wujud. Pelaksanaan yang tidak menetapkan pemboleh ubah persekitaran baharu berkelakuan tepat seperti sebelumnya.

4. Model data​

Dua jadual, kedua-duanya bagi setiap organisasi:

-- Baseline 0001_init: the server registry.
CREATE TABLE mcp_servers (
id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
org_id uuid NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
name text NOT NULL, -- [a-z0-9][a-z0-9_-]*
display_name text,
url text NOT NULL, -- https://… (the SSRF-guarded host)
transport text NOT NULL DEFAULT 'http', -- only 'http' is proxied
allowed_tools jsonb NOT NULL DEFAULT '[]', -- [] = all tools the server offers
enabled boolean NOT NULL DEFAULT false,
created_at timestamptz NOT NULL DEFAULT now(),
updated_at timestamptz NOT NULL DEFAULT now(),
UNIQUE (org_id, name)
);
CREATE INDEX idx_mcp_servers_org ON mcp_servers (org_id) WHERE enabled;

-- Baseline 0001_init: per-agent grants (one row per agent per server).
CREATE TABLE mcp_server_grants (
id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
org_id uuid NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
agent_id uuid NOT NULL REFERENCES agent_keys(id) ON DELETE CASCADE,
server_name text NOT NULL, -- same name rules as mcp_servers
allowed_tools jsonb NOT NULL DEFAULT '[]', -- [] = every tool the SERVER allows
enabled boolean NOT NULL DEFAULT true,
created_at timestamptz NOT NULL DEFAULT now(),
updated_at timestamptz NOT NULL DEFAULT now(),
UNIQUE (org_id, agent_id, server_name)
);
CREATE INDEX idx_mcp_server_grants_org_agent ON mcp_server_grants (org_id, agent_id) WHERE enabled;
CREATE INDEX idx_mcp_server_grants_org_server ON mcp_server_grants (org_id, server_name) WHERE enabled;

Geran merujuk agent_keys.id (prinsipal ejen). Geran ialah fakta kebenaran (siapa boleh memanggil apa), bukan kelayakan — tiada bahan rahsia. Geran yang dilumpuhkan lengai sehingga pengendali mendayakannya (postur kejujuran ketersediaan yang sama seperti mcp_servers.enabled).

Migrasi 0007 menambah jadual kelayakan — mcp_server_credentials (peringkat pelayan) dan mcp_user_credentials (bagi setiap (server, agent)) — diterangkan dalam §6.

5. Endpoint​

Pentadbir (satah kawalan, pengesahan root sahaja, berskop organisasi):

POST /api/organizations/{id}/mcp/servers create server
GET /api/organizations/{id}/mcp/servers list servers
GET /api/organizations/{id}/mcp/servers/{name} get one server
PATCH /api/organizations/{id}/mcp/servers/{name} update (incl. enabled)
DELETE /api/organizations/{id}/mcp/servers/{name} delete server

GET /api/organizations/{id}/mcp/servers/{name}/grants list grants
POST /api/organizations/{id}/mcp/servers/{name}/grants create grant
PATCH /api/organizations/{id}/mcp/servers/{name}/grants/{agent_id} update grant
DELETE /api/organizations/{id}/mcp/servers/{name}/grants/{agent_id} revoke grant

PUT /api/organizations/{id}/mcp/servers/{name}/credential upsert server-level credential
GET /api/organizations/{id}/mcp/servers/{name}/credential read the masked row
DELETE /api/organizations/{id}/mcp/servers/{name}/credential delete

Senarai benarkan domain SSRF bagi URL pelayan ialah milik pelaksanaan YABANIN_MCP_ALLOWED_UPSTREAMS (domain tepat dipisahkan koma atau *.suffix; kosong = gagal-tertutup, setiap hos ditolak). Penciptaan geran memerlukan pelayan yang dirujuk wujud bagi organisasi (404 jika tidak) dan memulangkan 409 pada pendua pelanggaran unik.

Gerbang (satah data, pengesahan ejen yag_*):

POST /api/mcp/invoke {"server":"knowledge","tool":"search","params":{...}}
→ 200 {tool result} | 401 mcp_auth_required | 403 agent_only | 404 not_found
| 400 ssrf_blocked | 400 mcp_tool_blocked | 409 denied
| 504 timeout | 502 upstream

POST /api/mcp/credentials/{server} headers submit/rotate (per-user, grant ceiling)
POST /api/mcp/auth/{server}/begin oauth: consent URL + pending row
GET /api/mcp/auth/{server}/callback oauth: code exchange (public — the IdP
redirects the human's browser here)

Satu endpoint seruan (bukan laluan bagi setiap pelayan) mengekalkan jadual laluan stabil apabila pelayan ditambah atau dibuang; pelayan ialah nilai, bukan segmen laluan. params ialah objek input alat; proxy mensirinya ke dalam permintaan JSON-RPC tools/call huluan. Respons ialah sama ada application/json (hasil tunggal) atau text/event-stream (hasil sebagai bingkai data terakhir); kedua-duanya dikendalikan dan diruntuhkan kepada result akhir. Seruan alat ialah permintaan/respons dari perspektif ejen (tiada penstriman separa).

KodHTTPMaksud
agent_only403pemanggil bukan kunci prinsipal ejen (yag_*)
mcp_auth_required401tiada kelayakan boleh guna bagi huluan (atau yang disimpan sudah mati); badan membawa {"error":{"code":"mcp_auth_required","kind":"headers|oauth","url":"/api/mcp/…"}} — aliran manusia yang menyelesaikannya (§6)
not_found404pelayan tiada/dilumpuhkan, atau tiada geran ejen, atau alat tiada pada senarai benarkan berkesan
ssrf_blocked400URL gagal pengawal SSRF bagi setiap seruan
mcp_tool_blocked400pagar toolpolicy OP-6 menyekat seruan atau hasilnya (dasar nafi, peraturan skema/saiz maksimum/regex argumen, atau semakan pasca hasil mod nafi); mesej menamakan semakan yang gagal, tidak sekali-kali nilai yang sepadan
denied409pengawal parameter (mod deny) menolak parameter
timeout504huluan melebihi tamat masa baca/sambung
upstream502huluan memulangkan bukan-2xx atau badan cacat bentuk

6. Kelayakan huluan (MC-1..3)​

Pelayan MCP huluan mungkin memerlukan pengesahan. Pengagregat meleraikan kelayakan keluar pada setiap seruan melalui rantai tetap — setiap pengguna (aktif) → peringkat pelayan (didayakan) → tiada — dan tidak sekali-kali membenarkan kelayakan meluaskan permukaan keluar: semakan senarai benarkan SSRF pada URL pelayan berjalan sebelum sebarang peleraian kelayakan, jadi hos yang didaftarkan tetapi tidak dibenarkan kekal disekat dengan atau tanpa kelayakan.

Jenis pengesahan​

Jenis pengesahanSiapa yang menetapkannyaPeleraian pada seruan
none (-)—seruan diteruskan tanpa pengesahan (postur legasi); keputusan huluan yang menentukan
headers (peringkat pelayan)pentadbir melalui API pentadbir (PUT …/credential)digunakan pada seruan setiap ejen apabila didayakan
headers (setiap pengguna)manusia ejen melalui aliran malas (POST /api/mcp/credentials/{server})digunakan hanya bagi pasangan (server, agent) itu, apabila active
oauth (peringkat pelayan atau setiap pengguna)pentadbir, atau aliran malas begin/callbacktoken akses digunakan; 401/403 huluan mencetuskan tepat satu cubaan semula muat semula paksa; token yang mati menjadi needs_reauth (kekal)

Kebenaran malas (mcp_auth_required)​

Apabila tiada kelayakan boleh guna wujud (atau yang disimpan sudah mati), seruan menjawab 401 dengan badan berstruktur:

{"error": {"code": "mcp_auth_required", "kind": "headers",
"url": "/api/mcp/credentials/knowledge"}}

kind menamakan jenis kelayakan yang akan memenuhi pelayan (headers → endpoint hantar, oauth → endpoint mula) dan url ialah laluan relatif manusia untuk memulakan aliran itu. Aliran hantar/mula memerlukan kunci prinsipal ejen (yag_) dan menghormati X-Audit-Reason.

Status kitar hayat (kelayakan setiap pengguna)​

StatusMaksud
pendingaliran malas bermula (persetujuan oauth belum selesai)
activedileraikan dan digunakan pada seruan
orphanedgeran pada pelayan dibatalkan — kelayakan itu lengai; pemberian semula geran memulihkannya (RestoreMCPUserCredentials)
needs_reauthhuluan menolak token secara muktamad (kekal sehingga pengesahan semula)
needs_updaterahsia yang disimpan gagal pengesahan selepas perubahan huluan

version bertambah pada setiap putaran atau peralihan status supaya cache penyelesai gerbang dinyahsah serta-merta.

Invarian keselamatan​

  • Bahan rahsia teks biasa wujud hanya sebagai argumen panggilan ke dalam kaedah store/resolve; setiap bacaan memulangkan baris bertopeng sahaja (secret_last4, has_secret) — tiada respons API boleh membawa teks biasa atau teks sifer, dan tiada medan struct boleh menyimpannya.
  • Rahsia disulitkan semasa rehat dengan sampul berawalan enc: (pkg/encryption, pariti BYOK, jadual migrasi 0007). Penulisan ialah gagal-tertutup: tanpa penyulit yang dikonfigurasi penulisan ditolak — konfigurasi penyulitan yang tiada tidak sekali-kali boleh merosot secara senyap kepada teks biasa.
  • Setiap operasi berjalan dalam satu transaksi yang GUC app.current_org-nya disemat — kontrak RLS org_isolation (ENABLE + FORCE, peranan keistimewaan paling rendah). Baris organisasi asing tidak kelihatan dan tidak boleh ditulis.
  • Setiap langkah CRUD/status mendarat dalam jurnal audit berantai cincang.
  • Teks biasa dihadkan (8 KiB bagi setiap muatan rahsia) dan tidak sekali-kali dilog atau disiri oleh proxy.
  • Upsert setiap pengguna memerlukan geran yang didayakan pada pelayan — geran kekal sebagai siling bagi setiap langkah aliran (lihat Tadbir urus ejen).

7. Pagar seruan alat (OP-6)​

Di atas registri benarkan/nafi yang biasa (Dasar alat), baris tool_policies boleh membawa dokumen rules yang dinilai pada granulariti (organisasi, pelayan, alat, subjek):

  • Pengawal argumen berjalan pra-keluar: JSON-Schema (draf 2020-12) pada argumen yang disiri, had saiz max_bytes dan corak RE2 deny_regex. Sesuatu pelanggaran menyekat seruan dengan 400 mcp_tool_blocked sebelum sebarang trafik huluan.
  • Semakan pasca hasil berjalan pada hasil huluan yang disiri: pengesan rahsia/PII/suntikan guardhooks dan deny_regex tersuai dengan mod setiap peraturan flag | mask | deny — topeng memulangkan hasil yang dihitamkan, nafi menggugurkannya dengan 400 mcp_tool_blocked.

Peraturan yang sepadan digabung kesatuan + paling ketat (peraturan hanya boleh menambah sekatan); setiap dapatan membawa hanya sumber semakan dan penunjuk span/JSON — nilai yang sepadan tidak sekali-kali muncul dalam ralat, dapatan atau metrik. Mod gagal adalah bagi setiap peraturan (fail: closed|open, lalai tertutup): sebaik sahaja organisasi mengisytiharkan peraturan gagal-tertutup, gangguan stor dasar menyekat seruan yang dikawal sehingga stor pulih. Tiada rules pada mana-mana baris = tingkah laku pra-pagar, bit demi bit.

Keputusan dikira dalam gateway_toolpolicy_decisions_total{org,server,tool,outcome} (error ialah gangguan stor dasar gagal-terbuka — seruan berjalan TANPA PAGAR).

8. Matriks risiko​

#RisikoKeterukanMitigasi
R1SSRF: organisasi mendaftarkan http://169.254.169.254/… atau hos pengikatan semula DNS yang menunjuk kepada metadata awan / perkhidmatan dalamanTinggipkg/ssrf AllowList.ValidateUpstream (senarai benarkan DNS + penolakan IP terpelihara) semasa pendaftaran dan sekali lagi pada setiap seruan (tetingkap pengikatan semula); tiada ubah hala diikuti; senarai benarkan domain statik pelaksanaan (YABANIN_MCP_ALLOWED_UPSTREAMS)
R2Suntikan prompt / persenjataan alat: seruan alat yang didorong model mengeksfiltrasi data organisasi melalui skema alat atau parameter pelayan luaran yang berniat jahatTinggiakses ejen sahaja, geran setiap ejen, senarai benarkan alat setiap pelayan (persilangan), cangkuk pengawal pada parameter, dasar nafi toolpolicy organisasi + peraturan argumen (skema/saiz maksimum/regex) pra-keluar, lalai MATI, jejak audit dengan parameter yang dihitamkan; bajet setiap ejen mengikat jejari letupan seruan berulang
R3Keluar rahsia: parameter membawa kunci API organisasi / PII ke pelayan luaranSederhanaguardhooks.Scan (termasuk pengesan PII kebangsaan) dalam mod redact/deny mengikut guard_mode sebelum keluar; deny menggugurkan seruan dengan 409 + peristiwa audit; semakan pasca hasil OP-6 (pengesan rahsia, flag/mask/deny setiap peraturan) menghentikan HASIL alat yang sarat rahsia daripada sampai kepada ejen
R4Kebocoran kelayakan: menyimpan token huluan setiap pelayan dalam PostgresSederhanarahsia hanya sebagai sampul disulitkan enc: semasa rehat (penulisan gagal-tertutup tanpa penyulit); RLS pengasingan organisasi (GUC app.current_org); bacaan memulangkan baris bertopeng sahaja (secret_last4/has_secret — teks biasa tidak sekali-kali merentas API); setiap langkah CRUD/status dalam jurnal audit berantai cincang; kelayakan tidak sekali-kali meluaskan keluar (semakan SSRF mendahului peleraian) (§6)
R5Penafian perkhidmatan / kos: ejen menggelung seruan alat; huluan mengecaj setiap seruanSederhanabajet token/perbelanjaan setiap ejen yang diwarisi; tamat masa sambung + baca proxy yang dihadkan; gateway_mcp_calls_total menjadikan kadar gelung kelihatan
R6Pemalsuan identiti: huluan mempercayai pengepala X-Yabanin-Agent-* yang dipalsukan oleh ejen milik organisasi sendiriRendahpengepala ialah atribusi, bukan kebenaran; gerbang tidak sekali-kali memajukan nilai pengepala ini yang dibekalkan pemanggil (dilucutkan pada kemasukan, ditetapkan daripada prinsipal ejen yang disahkan)
R7Jurang audit: seruan alat berlaku tetapi tidak dilogSederhanaseruan dijawab tanpa mengira audit (ketersediaan mengatasi audit); metrik gateway_mcp_calls_total dan span OTel direkodkan walaupun penerbitan audit digugurkan, jadi jurang kelihatan
R8Rampasan strim SSE / huluan slow-lorisRendahtamat masa baca yang dihadkan pada badan SSE, saiz respons maksimum, tiada guna semula keep-alive terbiar kepada hos yang dibekalkan pengguna di luar kolam standard
R9Kebergantungan: permukaan klien MCP untuk HTTP-SSERendahpembungkus klien nipis (JSON-RPC atas HTTP/SSE) supaya lapisan pengangkutan boleh ditukar; pintu keselamatan pada setiap perubahan
R10Rayapan skop ke huluan stdio (pelancaran proses pada gerbang)Sederhanabukan-matlamat yang eksplisit (§2); stdio kekal hanya untuk jambatan keluar

9. Invarian keselamatan (disemak oleh pintu keselamatan repositori pada setiap perubahan pengagregat)​

  1. Tiada URL yang dikawal pengguna sampai ke http.Client tanpa melepasi pengawal SSRF dua kali (pendaftaran + seruan) — dan sentiasa sebelum peleraian kelayakan, supaya kelayakan tidak boleh memanjangkan keluar.
  2. Rahsia kelayakan disimpan hanya sebagai sampul enc:, dibaca semula hanya sebagai baris bertopeng (secret_last4/has_secret) di bawah RLS pengasingan organisasi, dan setiap mutasi diaudit; tiada bahan rahsia disimpan dalam mcp_servers / mcp_server_grants atau dilog tanpa penghitaman; peristiwa audit membawa params-redacted.
  3. Identiti ejen datang hanya daripada prinsipal yag_* yang disahkan; pengepala X-Yabanin-Agent-* ditetapkan oleh proxy dan dilucutkan daripada permintaan masuk.
  4. Ciri ini MATI secara lalai (YABANIN_MCP_GATEWAY tidak ditetapkan ⇒ kumpulan laluan tidak dipasang ⇒ sifar perubahan tingkah laku).

10. Rujukan konfigurasi​

Pemboleh ubah persekitaranLalaiMaksud
YABANIN_MCP_GATEWAYtidak ditetapkan (mati)1 memasang kumpulan laluan /api/mcp/invoke (memerlukan kolam pangkalan data).
YABANIN_MCP_ALLOWED_UPSTREAMSkosongDomain tepat dipisahkan koma atau *.suffix yang mesti dipadankan hos URL huluan. Kosong = gagal-tertutup (setiap hos ditolak).
YABANIN_GUARD_MODEoffoff / log / redact / deny — mod pengawal parameter yang digunakan pada input alat (diwarisi daripada cangkuk pengawal laluan sembang).

Pendawaian pelaksanaan (OP-25 F-5): perkhidmatan pentadbir menghurai YABANIN_MCP_ALLOWED_UPSTREAMS daripada persekitaran (config.Load("") ialah env sahaja — config.yaml yang dilekapkan tidak dibaca) dan menghantar senarai itu kepada CRUD registri; gerbang menghurai pemboleh ubah yang sama untuk semakan semula semasa seruan, pengawal URL token kelayakan dan pelaksana alat sisi pelayan — SATU senarai mentadbir pendaftaran dan setiap dail keluar. Dalam pelaksanaan compose, pemboleh ubah itu oleh itu mesti dihantar kepada KEDUA-DUA perkhidmatan admin dan gateway (deploy/docker-compose.prod.yml + deploy/.env.example melakukan ini); kosong/tidak ditetapkan bermaksud pendaftaran menjawab 400 (host not in the allowed domains list) — gagal-tertutup mengikut reka bentuk, bukan kerosakan.

11. Ringkasan penerimaan​

KomponenPenerimaan
Registri + proxyCRUD mcp_servers dalam pentadbir; proxy seruan untuk HTTP-SSE; lalai MATI; pengawal SSRF pada pendaftaran + seruan; tamat masa yang dihadkan; ujian meliputi nafi ubah hala, IP terpelihara, tamat masa
Akses + auditseruan menolak kunci bukan-yag_ (403 agent_only) dan ejen/pelayan/alat tanpa geran (404); setiap seruan → baris request_logs dengan task_id/agent_id/upstream_url + peristiwa audit (parameter dihitamkan), dilabel mcp:<server>:<tool>; CRUD geran dalam pentadbir
Identitihuluan menerima X-Yabanin-Agent-Id / -Name / X-Yabanin-Team-Id; salinan masuk dilucutkan; nilai datang daripada prinsipal yang disahkan
Kebolehcerapangateway_mcp_calls_total{server,tool,outcome} hadir di bawah /metrics; satu span OTel (mcp.tools/call) bagi setiap seruan dengan atribut pelayan/alat/hasil
Pengawal parameterparameter melepasi guardhooks.Scan; mod redact menggantikan rahsia; mod deny menggugurkan seruan (409) + audit; mod diwarisi daripada guard_mode
Pagar seruan alat (OP-6)tool_policies.rules (skema argumen/max_bytes/deny_regex pra-keluar; rahsia hasil/regex flag/mask/deny pasca-keluar); pelanggaran skema → 400 mcp_tool_blocked sebelum sebarang trafik huluan; rahsia dalam hasil → bertopeng atau dinafikan mengikut peraturan; dapatan membawa span/kategori sahaja (bebas nilai, disemat oleh ujian); -race hijau pada keserentakan Decide/Guard; peraturan organisasi terasing bagi setiap organisasi
Kelayakan huluan (MC-1..3)kelayakan peringkat pelayan + setiap pengguna sebagai sampul enc: di bawah RLS pengasingan organisasi; bacaan bertopeng sahaja; seruan meleraikan setiap pengguna → peringkat pelayan → none dengan satu cubaan semula muat semula; mcp_auth_required malas dengan URL aliran manusia; siling geran + penyatiman/pemulihan; jurnal audit pada setiap langkah CRUD/status
Skrin perbandingan modelskrin perbandingan papan pemuka (#compare): kos penilaian bayang bagi setiap model + kependaman seluruh organisasi (berkapsyen bukan bagi setiap model) + kualiti tersampel evalgate bagi setiap pasangan/kelas tugasan (ADL-04) dengan pengesyoran penghalaan yang diterapkan manusia; kapsyen skop yang digunakan; terpapar pada semua ruang pandang