So autorisieren Sie einen MCP Tool Call

11 Minuten Lesezeit

Um einen MCP-Toolaufruf zu autorisieren, den Anrufer und die Anmeldeinformationen zu überprüfen, den genauen Toolnamen und die Argumente zu kanonisieren, sie an eine Mandats- und Richtlinienentscheidung zu binden, Wiederholungen zu verhindern und dann nur die genehmigte Anforderung auszuführen.

Dieses Implementierungshandbuch richtet sich an MCP-Serverentwickler, die Folgewerkzeuge wie issue_refund, change_supplier_bank_account oder release_purchase_orderDas Ergebnis ist eine Middleware-Grenze, die eine geänderte Anforderung ablehnen kann, bevor die Geschäftslogik ausgeführt wird, und Beweise liefert, die benennen, was genehmigt wurde und was tatsächlich passiert ist.

Verfügbarkeit, Zugang und Autorität sind unterschiedlich

Die MCP-Spezifikation besagt, dass Server Tools aussetzen können, die Clients entdecken und aufrufen können; sie erfordert auch Eingabevalidierung, Zugriffskontrollen, Ratenbegrenzung und Ausgabe-Entsorgung auf der Serverseite.MCP Tools Spezifikation).

Die MCP-Autorisierung für HTTP-Transporte verwendet OAuth-orientierte Mechanismen, um den Zugriff auf geschützte Server zu steuern. Das beantwortet, ob ein Client dem Ressourcenserver einen akzeptablen Nachweis vorlegen kann. Es beantwortet nicht automatisch, ob der vertretene Auftraggeber die Bestellung 9182 für 450 € zurückerstatten kann.

Verwenden Sie drei separate Entscheidungen:

OAuth Scopes können den Zugriff einschränken, aber ein Scope wie refunds:write Ist in der Regel zu breit, um Betragsgrenzen, Händlergrenze, Auftragsbesitz, Genehmigungszustand und Ablauf zu kodieren.

Für das breitere Modell lesen Autorisierung von AI AgentsWarum MCP diese zusätzliche Autoritätsschicht benötigt, siehe MCP gibt Agenten Werkzeuge, aber wer gibt Autorität?.

Modellieren Sie die genaue Anfrage

Die Autorisierung sollte an einen kanonischen Transaktionsumschlag binden.

type ToolEnvelope<TArgs> = {
  protocol: 'mcp';
  serverAudience: string;
  toolName: string;
  arguments: TArgs;
  principalId: string;
  agentId: string;
  mandateId: string;
  transactionId: string;
  nonce: string;
  issuedAt: string;
  expiresAt: string;
};

type AuthorizationDecision = {
  decisionId: string;
  effect: 'allow' | 'deny';
  requestDigest: string;
  policyVersion: string;
  mandateVersion: string;
  obligations: Array<
    | { type: 'human_approval'; approvalId: string }
    | { type: 'revalidate_order_state' }
    | { type: 'record_receipt' }
  >;
  decidedAt: string;
  expiresAt: string;
};

Der Digest muss mindestens das Serverpublikum, den Werkzeugnamen, die kanonischen Argumente, den vertretenen Auftraggeber, den Agenten, das Mandat, die Transaktions-ID, die Nonce und den Ablauf abdecken. amountMinor: 4500Ändern Sie es auf 45000 muss einen anderen verdau und eine verweigerung erzeugen.

Ganzzahlige kleinere Einheiten für die Währung und einen expliziten ISO-Währungscode verwenden; unbekannte Felder ablehnen, es sei denn, das Werkzeugschema erlaubt absichtlich Erweiterungen; mehrdeutige Eingabe ist keine Flexibilität an einer Folgegrenze.

Legen Sie die Autorisierung vor der Werkzeugausführung

Die Middleware Sequenz ist:

1. Authentifizierung der Verbindung und Validierung des Token-Emittenten, der Signatur, der Zielgruppe, des Ablaufs und des erforderlichen Zugriffsbereichs.
2. Parse die MCP-Anforderung und validiere das toolspezifische Argumentschema.
3. Lösen Sie den Auftraggeber, den Agenten und das Mandat, ohne den vom Kunden bereitgestellten Anzeigefeldern zu vertrauen.
4. Canonicalize den Umschlag und berechnen seine Digest.
5. Fordern Sie die Nonce- oder Transaktions-ID atomar an, um die doppelte Ausführung zu stoppen.
6. Bewerten Sie die Richtlinie anhand des Mandats, der genauen Anfrage und des aktuellen Geschäftszustands.
7. Erfüllung von Verpflichtungen wie frische Genehmigung oder staatliche Verlängerung.
8. Berechnen oder vergleichen Sie den Digest sofort, bevor Sie die Geschäftslogik aufrufen.
9. Ausführen über eine idempotente Domain-API.
10. Notieren Sie eine Aktion Quittung mit Entscheidung und Ergebnis Beweise.

async function authorizeAndCall<TArgs, TResult>(
  ctx: AuthenticatedContext,
  input: ToolEnvelope<TArgs>,
  handler: (args: TArgs, key: string) => Promise<TResult>,
): Promise<TResult> {
  assertAudience(ctx.token, input.serverAudience);
  assertPrincipalBinding(ctx, input.principalId, input.agentId);
  assertFreshWindow(input.issuedAt, input.expiresAt, clock.now());

  const args = schemas.forTool(input.toolName).parse(input.arguments);
  const canonical = canonicalize({ ...input, arguments: args });
  const digest = sha256(canonical);

  const replay = await nonceStore.claim({
    namespace: input.serverAudience,
    nonce: input.nonce,
    transactionId: input.transactionId,
    expiresAt: input.expiresAt,
  });
  if (!replay.claimed) return recoverExistingResult(replay);

  const mandate = await mandateStore.getCurrent(input.mandateId);
  const decision = await policy.evaluate({ ctx, input, args, digest, mandate });
  if (decision.effect !== 'allow') throw new Forbidden(decision.decisionId);

  await satisfyObligations(decision.obligations, { input, digest, mandate });
  if (
    sha256(canonicalize({ ...input, arguments: args })) !==
    decision.requestDigest
  ) {
    throw new RequestChanged();
  }

  try {
    const result = await handler(args, input.transactionId);
    await receipts.recordSuccess({ input, digest, decision, result });
    return result;
  } catch (error) {
    await receipts.recordFailure({ input, digest, decision, error });
    throw error;
  }
}

Die Probe nimmt an, policy.evaluate In der Produktion fehlgeschlagen, wenn die Entscheidung einen Digest fehlt, abgelaufen ist oder auf eine andere Mandats- oder Richtlinienversion verweist.

Schreibe Richtlinien über Domain-Fakten

Eine nützliche Regel nennt konkrete Domänengrenzen.

policy_id: refund-agent-v3
tool: issue_refund
allow_when:
  principal_role: customer_support_agent
  merchant_id_from_token: equals(arguments.merchantId)
  order_customer: equals(principal.customerId)
  currency: EUR
  amount_minor: { max: 5000 }
  order_state: [paid, partially_refunded]
  mandate_purpose: customer_remediation
  mandate_expires_after_request: true
obligations:
  - revalidate_order_state
  - require_human_approval_if: amount_minor > 2500
  - record_receipt

Auflösung order_state Aus dem Bestellsystem während der Bewertung oder als Vorausführungsverpflichtung. Akzeptieren Sie es nicht aus den Argumenten des Modells. In ähnlicher Weise leiten Sie die Händlermiete aus dem vertrauenswürdigen Identitätskontext ab, nicht nur aus einem veränderlichen Feld.

Richtlinieversionen müssen unveränderlich und adressierbar sein, und ein späterer Prüfer muss die Regel reproduzieren, die die Entscheidung getroffen hat, und nicht die Regel, die heute angewendet wird.

Umgang mit Wiederholungen und unsicheren Ergebnissen

Nonce-Checks allein bieten keine exakte Ausführung. Ein Server kann die Rückerstattung ausführen, die Antwort verlieren und eine Wiederholung erhalten. Verwenden Sie einen Domänen-Idempotenzschlüssel, der an die Transaktions-ID gebunden ist, und versuchen Sie, das aufgezeichnete Ergebnis wiederherzustellen.

Verwenden Sie diese Zustände:

received -> authorized -> executing -> succeeded | failed | outcome_unknown

An outcome_unknown Der Status ist notwendig, wenn der nachgelagerte Dienst nach dem Akzeptieren einer Anforderung ausfällt, nicht blind wiederholen, das Domänensystem nach dem idempotency-Schlüssel abfragen, das Ergebnis abgleichen und dann den Empfang abschließen.

Das sichere Verhalten für häufige Fehler ist explizit:

Gleiche Nonce, gleicher Digest. Geben Sie das vorherige Ergebnis oder den aktuellen Transaktionsstatus zurück.

Gleiche Nonce, unterschiedlicher Digest. Verweigern und markieren Sie einen Wiederholungs- oder Substitutionsversuch.

Die Zulassung bezieht sich auf einen anderen Digest. Ein anderer Antrag erfordert eine neue Entscheidung.

Mandat nach der Entscheidung, aber vor der Ausführung widerrufen. Überprüfen Sie den aktuellen Mandatsstatus an der Ausführungsgrenze.

Policy Service nicht verfügbar. Fail closed for consequential writes. Read-only low-risk tools können eine separat überprüfte Degradationsrichtlinie haben.

Der Geschäftszustand hat sich geändert. Wenn die Bestellung vollständig zurückerstattet wurde, verweigern oder geben Sie das bestehende Ergebnis zurück.

Receipt Write scheitert nach erfolgreicher Aktion. Wiederholen Sie die Aktion nicht, markieren Sie die anhängige Beweislieferung und reparieren Sie asynchron aus dem idempotenten Domäneneintrag.

Der detaillierte Transaktionspfad wird in vom MCP-Toolaufruf zur auditierbaren UnternehmenstransaktionQuittungen sind Beweise, kein Ersatz für die Genehmigung; siehe AI-Auditpfade und Aktionsquittungen.

Überprüfen Sie die Grenze mit Angriffsarmaturen

Unit-Tests für den glücklichen Pfad sind unzureichend. Führen Sie eine Konformitäts-Fixer gegen Middleware und einen gefälschten idempotenten Domain-Dienst aus.

const cases = [
  { name: 'exact approved request', mutate: none, expect: 'allow', calls: 1 },
  {
    name: 'amount substitution',
    mutate: set('amountMinor', 45000),
    expect: 'deny',
    calls: 0,
  },
  {
    name: 'tool substitution',
    mutate: set('toolName', 'change_bank_account'),
    expect: 'deny',
    calls: 0,
  },
  {
    name: 'audience swap',
    mutate: set('serverAudience', 'mcp://other'),
    expect: 'deny',
    calls: 0,
  },
  { name: 'expired mandate', mutate: expireMandate, expect: 'deny', calls: 0 },
  {
    name: 'same retry',
    mutate: replayIdentically,
    expect: 'recover',
    calls: 1,
  },
  {
    name: 'nonce with new args',
    mutate: replayWithNewArgs,
    expect: 'deny',
    calls: 0,
  },
  {
    name: 'downstream timeout after commit',
    mutate: timeoutAfterCommit,
    expect: 'reconcile',
    calls: 1,
  },
];

Für jeden Fall geben Sie die Anzahl der Domänenaufrufe, den Entscheidungseffekt, den Anforderungsverdau, die Richtlinien- und Mandatsversionen, den Transaktionszustand und das Empfangsergebnis an. Stellen Sie die Uhr und das Schlüsselmaterial in der Vorrichtung ein, damit die Ergebnisse reproduzierbar sind. Unbekannte Felder, numerische Grenzen, Unicode-Normalisierung und neu geordnete JSON-Eigenschaften. Eine Canonicalisierungsimplementierung sollte sie entweder vorhersagbar normalisieren oder ablehnen.

Testen Sie auch verwirrt-deputed-Bedingungen: ein gültiges Token für einen MCP-Server, das einem anderen präsentiert wird, ein Auftraggeber von einem Mandanten gepaart mit einem Auftrag von einem anderen und ein Client, der eine Umleitung oder Ressource anfordert, die die beabsichtigte Zielgruppe verändert.RFC 9728Validieren Sie das Ressourcenpublikum auf dem Server sowieso.

Checkliste der Durchführung

• Validieren Sie Token-Signatur, Emittent, Zielgruppe, Ablauf und erforderlichen Zugriffsbereich.
• Lösen Sie die Haupt- und Agentenidentität aus dem vertrauenswürdigen Kontext.
• Validieren Sie Argumente mit einem strengen, werkzeugspezifischen Schema.
• Canonicalize und hash den Toolnamen, Argumente und Transaktionskontext.
• Binden Sie jede Entscheidung und Genehmigung an genau diesen Digest.
• Bewerten Sie Mandatsgrenzen, Richtlinienversion und aktuellen Domain-Status.
• Claim Nonce und Transaktion ID atomar.
• Verwenden Sie einen Domain-Idempotenzschlüssel und vereinbaren Sie unsichere Ergebnisse.
• Überprüfen Sie den Widerruf und den veränderlichen Geschäftszustand vor der Ausführung erneut.
• Zeichne Erfolg, Leugnung, Misserfolg und unbekannte Ergebnisse ohne Geheimnisse auf.
• Test Substitution, Replay, Cross-Tenant und Timeout-after-Commit Fälle.
• Erhalten Sie eine fachkundige Sicherheitsüberprüfung und Bedrohungsmodellierung vor der Produktion.

Aktueller Intelliger und OATI Grenze

OATI ist ein offener Standard in der Entwicklervorschau, kein Produktionsautorisierungsdienst, der über Kundenflotten hinweg betrieben wird. Aktuell implementierte Assets umfassen Schemata, ein TypeScript SDK, einen tragbaren Python- und Go-Core, einen CLI, 73 Konformitätstests, lokale Commerce- und RWA-Sandboxen, eine Envoy-Referenz und einen eingesetzten Public Trust / Lookup-Vertical-Slice.

Der vollständige Richtlinien-Compiler, die unabhängige Sicherheitsüberprüfung, die Evidenz- und Streitbeilegungs-Workflows, die Kunden-Gateway-Flotte, die Hub-Erfahrung und die Akzeptanz der Produktion für zwei Unternehmen sind nicht vollständig. Der Transaktionsumschlag, der Mandats- und Aktionsempfangsansatz informieren das obige Muster, aber die Teams müssen den genauen Repository-Status überprüfen, bevor sie ihn annehmen. OATI-Übersicht, Entwicklerdokumentation und OATI-Repository.

Hinweis zur Sicherheitsüberprüfung: Der Code und die Richtlinie hier sind illustrativ, keine einsetzbare Sicherheitskontrolle. Kryptografische Canonicalization, OAuth-Konfiguration, Mietsteuerelemente, Zahlungsvorgänge und Replay-Recovery erfordern eine Überprüfung durch qualifizierte Sicherheits- und Domänenexperten für Ihre Bereitstellung.

Um diese Grenze zu testen, anstatt sie nur zu diskutieren, Führen Sie das OATI-Konformitätsmaterial für Entwickler-Vorschau aus dem öffentlichen Repository aus.