MCP-proxy

Hvert værktøjskald kontrolleres, før det når dine værktøjer.

Proxyen kontrollerer kun de kald, der sendes gennem den. Et værktøj, som din agent kan nå ad en anden vej, er ikke beskyttet.

Hvad proxyen gør

noa-mcp-proxy sidder mellem en AI-app (MCP-værten) og en værktøjsserver, som den allerede bruger; værktøjsserverens kode ændres ikke. MCP står for Model Context Protocol, en åben protokol, som AI-software bruger til at kalde værktøjer.

Din politikfil afgør hvert værktøjskald: tilladte kald går igennem, og blokerede kald når aldrig værktøjet. Kald, der passer på en regel i approval-rules.json, tilbageholdes: proxyen afviser dem med en fejl, der indeholder et kvitterings-id, en person godkender, og agenten gentager det identiske kald. Hver beslutning bliver til en signeret kvittering, som alle med de offentlige nøgler kan kontrollere offline.

Den lukker ved fejl, det vil sige, at den afviser i stedet for at gætte: en ubrugelig politikfil forhindrer den i at starte, og en uventet fejl før videresendelse lukker aldrig et kald igennem; hvis forbindelsen afbrydes, efter at et kald er sendt videre, returnerer proxyen en fejl, og kaldet kan stadig være blevet udført.

Installér og kør den i fem trin

Du skal bruge Node.js 20 eller nyere.

Installér proxyen og godkendelseskommandoen, noa-approve:
```
npm install -g noa-mcp-proxy noa-mcp-adapter-core
```
Navngiv tre af din servers værktøjer: ét, der skal tillades, ét, der kun kører, når en person har godkendt det, og ét, der skal blokeres. Alle andre værktøjer afvises. Det skriver politikken, godkendelsesreglen og godkendernøglerne i mappen noa og udskriver startkommandoen og en MCP-konfiguration, du kan indsætte, begge med absolutte stier:
```
noa-mcp-proxy init --dir noa --allow-tool search_docs --approval-tool refund --block-tool delete_all
```

Start proxyen foran din server med den startkommando, som init udskrev, og som har fulde stier. Alt efter -- er din servers egen kommando. Med forkortede stier ser den sådan ud:

noa-mcp-proxy --policy noa/policy.json --approval-rules noa/approval-rules.json --pending-store noa/pending-store.jsonl --approver-keyring noa/approver-keyring.json --key-file noa/proxy-key.json --keyring-file noa/keyring.json --receipt-log noa/decisions.jsonl --outcome-log noa/outcomes.jsonl -- node your-server.js

Et tilbageholdt refund-kald returnerer en fejl med et kvitterings-id. En person godkender det fra en separat terminal, og derefter gentager agenten det identiske kald; en godkendelse kører ikke noget i sig selv:
```
noa-approve approve --id <receiptId> --by you@example.com --pending-store noa/pending-store.jsonl --key-file noa/approver-key.json
```
Kontrollér resultatkvitteringerne offline. Afslutningskode 0 betyder VALID, 2 TAMPERED, 3 MALFORMED og 4 en brugsfejl:
```
noa-mcp-proxy verify-outcome noa/outcomes.jsonl --keyring noa/keyring.json
```

init skriver kun startfiler; den slår ikke beskyttelsen til. Intet er beskyttet, før din MCP-vært starter proxyen med disse filer, værktøjsnavnene er dine egne, en person kører noa-approve for hvert tilbageholdt kald, og agenten gentager det identiske kald.

Påkrævede regler for din opsætning

Angiv altid din egen --policy-fil. Uden den kører proxyen en indbygget demopolitik, skrevet til dens demoserver, og udskriver en advarsel ved hver start.
Navngiv hvert værktøj, der kræver godkendelse, i både policy.json og approval-rules.json. Proxyen nægter at starte, når en godkendelsesregel navngiver et værktøj, som politikken ikke navngiver (POLICY_APPROVAL_MISMATCH).
Godkendelser kræver tre flag sammen: --approval-rules, --pending-store og --approver-keyring. Proxyen nægter at starte, når en af de to første er angivet uden betroede godkendernøgler.
Læg politik-, regel- og nøglefilerne i en mappe, som kun operatøren kan skrive i, hele vejen op ad stien, og angiv fulde stier som i den kommando, init udskriver. Proxyen afviser en politik- eller godkendelsesfil, der er et symbolsk link, eller som andre kan skrive i, men den kan ikke se en ombyttet overordnet mappe.
Peg din MCP-vært på proxyen, aldrig direkte på værktøjsserveren.

Politikfilen

--policy tager en noa.policy/0.2-fil. Den første regel, der passer, afgør sagen, og et kald, som ingen regel passer på, afvises.

{
  "spec": "noa.policy/0.2",
  "id": "my-tools-v1",
  "requiredPaths": ["action"],
  "rules": [
    { "id": "allow-search_docs", "when": { "op": "eq", "path": "action", "value": "search_docs" }, "then": "ALLOW" },
    { "id": "small-refunds-only", "when": { "op": "and", "clauses": [
        { "op": "eq", "path": "action", "value": "refund" },
        { "op": "lt", "path": "args.amountMinor", "value": 10000 } ] }, "then": "ALLOW" }
  ]
}

action er værktøjets navn; args.<name> er et værktøjsargument (indlejret: args.a.b). Tal skal være heltal.
Operatorer: eq ne lt le gt ge (med value), in (values), exists absent, and or (clauses) og not (clause). En afgørelse er ALLOW eller DENY.
Formatet er lukket: en ukendt eller dobbelt nøgle er en fejl, så kommentarer er ikke mulige.
Filen læses én gang, ved start: en ændring får først virkning efter en genstart.
Hvis filen ikke kan bruges, starter proxyen ikke. Den afslutter med kode 1 og én fejllinje, der navngiver filen, feltet og rettelsen. Linjen begynder med en af fire faste koder: POLICY_UNREADABLE, POLICY_UNPARSABLE, POLICY_INVALID eller POLICY_APPROVAL_MISMATCH.

Kontrollér kvitteringerne

Der findes to slags kvitteringer, og hver har sit eget kontrolværktøj.

Resultatkvitteringer (noa.mcp.outcome/0.1, skrevet med --outcome-log) kontrolleres med noa-mcp-proxy verify-outcome som i trin 5.

Beslutningskvitteringer (noa.receipt/0.1, skrevet med --receipt-log) kontrolleres med kommandoen noa fra pakken noa-receipt:

noa verify <receipts.json> --keyring <keyring.json>

noa-receipt 0.9.0 på npm (på engelsk)

Den kommando læser ét JSON-array, ikke én kvittering pr. linje, så læg først loggens linjer ind i ét [ ... ]-array. Dens nøglering skal indeholde hver nøgle, der har signeret kæden: proxyens nøgle fra noa/keyring.json og, når et kald blev godkendt, godkenderens nøgle fra noa/approver-keyring.json, samlet i ét JSON-objekt.

VALID betyder, at hver linje er en ægte, signeret resultatkvittering, hver for en forskellig beslutning. Det beviser ikke, at loggen er komplet: en slettet linje efterlader intet spor. Hvis den samme beslutnings resultat optræder to gange, er det TAMPERED.

Valgfrit: hold signeringsnøglen i sin egen proces

Som standard holder proxyen sin private signeringsnøgle i sin egen proces: en ny nøgle ved hver start eller en gemt nøgle med --key-file.

noa-signer-sidecar flytter nøglen over i en separat proces. Proxyen beder den om signaturer over en lokal Unix-socket, der kun er beregnet til denne maskine; at gøre socketen tilgængelig uden for den, for eksempel gennem en container-montering eller en SSH-videresendelse, ligger uden for sidecarens trusselsmodel: gør det ikke. Start den sådan:

npm install -g noa-signer-sidecar
mkdir -p -m 700 /path/to/private-dir
noa-signer-sidecar --key-file /path/to/private-dir/key.json --socket /path/to/private-dir/signer.sock

Start derefter proxyen med dette flag i stedet for --key-file:

--signer-socket /path/to/private-dir/signer.sock

Socketens mappe skal allerede findes med tilstand 0700, så kun du har adgang; ellers nægter sidecaren at starte. Det kontrolleres ved start, ikke løbende: hvis mappen senere gøres mere åben, opdages det ikke.
--signer-socket og --key-file kan ikke bruges sammen.
Hvis sidecaren ikke kan nås ved start, starter proxyen ikke; hvis sidecaren stopper under en session, afvises hvert kald.
Det er procesisolering, ikke et hardwaresikkerhedsmodul: root eller den samme styresystembruger kan stadig læse nøglefilen eller sidecarens hukommelse.
Sidecaren signerer alt, hvad den bliver bedt om at signere: alle, der kan forbinde sig til socketen, kan få en gyldig signatur.
Nøglerotation er ikke indbygget i sidecaren.

Hvad proxyen ikke gør

Den kontrollerer ikke et kalds argumenter mod værktøjets eget inputskema; din værktøjsserver skal stadig afvise forkert formede input.
Den beviser ikke, at en kvitteringslog er komplet: en slettet linje efterlader intet spor.
En kvittering beviser ikke, at den handling, den beskriver, faktisk skete; det bevis kommer fra det system, der udfører handlingen.
En godkendelse viser, at en betroet nøgle godkendte; den beviser ikke, at personen forstod, hvad vedkommende godkendte.
Den stopper ikke en person, der kan omskrive dens regelfiler på stedet som den samme bruger: en tom regelliste er gyldig og tilbageholder intet.
Den beskytter ikke mod en angriber, der kontrollerer selve proxyprocessen.

Den er ikke NOA Mandate-garantien i sig selv. Den garanti kræver alle fire regler mod bagveje, herunder en boks, der kontrollerer Noas godkendelse ved sin egen lås.

Læs NON-CLAIMS.md, før du stoler på proxyen til noget, der betyder noget.

Status, kontrolleret 2026-10-06: noa-mcp-proxy 0.5.0 og noa-mcp-adapter-core 0.5.0 er udgivet på npm som åben kildekode (Apache-2.0), og noa-signer-sidecar 0.1.0 er en valgfri tilføjelse.

Pakker og kildekode

Kildelinkene peger på det præcise offentlige commit, som denne vejledning er skrevet ud fra.

Indlæser…