← Vytvářejte agenty na Cloudflare / agents / model-context-protocol / protocol

Autorizace

Při sestavování Model Context Protocol (MCP) ↗ server, potřebujete jak způsob, jak uživatelům umožnit přihlášení (ověření), tak způsob, jak jim umožnit udělit klientovi MCP přístup ke zdrojům ve svém účtu (autorizace).

Model Context Protocol používá podmnožina OAuth 2.1 pro autorizaci ↗. OAuth umožňuje vašim uživatelům udělit omezený přístup ke zdrojům, aniž by museli sdílet API klíče nebo jiné přihlašovací údaje.

Cloudflare poskytuje OAuth Provider Library ↗ která implementuje stranu poskytovatele protokolu OAuth 2.1 a umožňuje snadno přidat autorizaci do vašeho MCP serveru.

OAuth Provider Library můžete použít čtyřmi způsoby:

1. Používejte Cloudflare Access jako poskytovatele OAuth.
2. Integrujte se přímo s OAuth poskytovatelem třetí strany, například GitHub nebo Google.
3. Integrujte se s vlastním OAuth poskytovatelem, včetně poskytovatelů authorization-as-a-service, na které již možná spoléháte, například Stytch, Auth0 nebo WorkOS.
4. Váš Worker se sám stará o autorizaci a autentizaci. Váš server MCP, běžící na Cloudflare, zajišťuje celý průběh OAuth.

Následující sekce popisují jednotlivé možnosti a odkazují na spustitelné příklady kódu pro každou z nich.

Cloudflare Access vám umožňuje přidat do serveru MCP funkci jednotného přihlašování (SSO). Uživatelé se k vašemu serveru MCP ověřují pomocí nakonfigurovaný poskytovatel identity nebo jednorázový PIN, a přístup jim je udělen, jen pokud jejich identita odpovídá vašemu Zásady Access.

Chcete-li nasadit příklad serveru MCP ↗ s Cloudflare Access jako poskytovatelem OAuth, viz Zabezpečení serverů MCP pomocí Access for SaaS.

OAuth Provider Library ↗ lze nakonfigurovat tak, aby používal OAuth poskytovatele třetí strany, například GitHub nebo Google. Úplný příklad najdete v Příklad GitHub.

Používáte-li poskytovatele OAuth třetí strany, musíte poskytnout handler pro OAuthProvider která implementuje OAuth tok pro poskytovatele třetí strany.

import MyAuthHandler from "./auth-handler";

export default new OAuthProvider({
	apiRoute: "/mcp",
	// Your MCP server:
	apiHandler: MyMCPServer.serve("/mcp"),
	// Replace this handler with your own handler for authentication and authorization with the third-party provider:
	defaultHandler: MyAuthHandler,
	authorizeEndpoint: "/authorize",
	tokenEndpoint: "/token",
	clientRegistrationEndpoint: "/register",
});

Uvědomte si, že jak definováno ve specifikaci Model Context Protocol ↗ když použijete OAuth poskytovatele třetí strany, server MCP (váš Worker) vygeneruje a vydá vlastní token klientovi MCP:

sequenceDiagram
    participant B as User-Agent (Browser)
    participant C as MCP Client
    participant M as MCP Server (your Worker)
    participant T as Third-Party Auth Server

    C->>M: Initial OAuth Request
    M->>B: Redirect to Third-Party /authorize
    B->>T: Authorization Request
    Note over T: User authorizes
    T->>B: Redirect to MCP Server callback
    B->>M: Authorization code
    M->>T: Exchange code for token
    T->>M: Third-party access token
    Note over M: Generate bound MCP token
    M->>B: Redirect to MCP Client callback
    B->>C: MCP authorization code
    C->>M: Exchange code for token
    M->>C: MCP access token

Přečíst dokumentaci k Knihovna Workers OAuth Provider ↗ pro další podrobnosti.

Pokud vaše aplikace už sama implementuje OAuth Provider, nebo používáte poskytovatele typu authorization-as-a-service, můžete to použít stejně jako u poskytovatele OAuth třetí strany popsaného výše v (2) OAuth poskytovatel třetí strany.

Auth provider můžete použít k:

• Umožněte uživatelům ověřit se u vašeho serveru MCP pomocí e-mailu, přihlášení přes sociální sítě, SSO (Single Sign-On) a MFA (vícefaktorové ověřování).
• Definujte scopes a oprávnění, které se přímo mapují na vaše nástroje MCP.
• Zobrazte uživatelům stránku se souhlasem odpovídající požadovaným oprávněním.
• Vynucujte oprávnění tak, aby agenti mohli volat pouze povolené nástroje.

Začínáme s vzdálený server MCP, který používá Stytch ↗ aby se uživatelé mohli přihlásit pomocí e-mailu, přihlášení přes Google nebo firemního SSO a autorizovat svého AI agenta ke zobrazování a správě OKR své společnosti jejich jménem. Stytch se postará o omezení rozsahů udělených AI agentovi podle role a oprávnění uživatele v rámci organizace. Při autorizaci MCP klienta uvidí každý uživatel stránku se souhlasem, která popisuje oprávnění, jež agent požaduje a která je uživatel na základě své role schopen udělit.

Pro další případy použití zaměřené na spotřebitele nasaďte vzdálený server MCP pro aplikaci To Do, která pro autentizaci a autorizaci MCP klienta využívá Stytch. Uživatelé se mohou přihlásit e-mailem a hned získat přístup ke svým seznamům To Do přiřazeným k jejich účtu a udělit přístup libovolnému AI asistentovi, aby jim pomohl se správou úkolů.

Začínáme se vzdáleným MCP serverem, který k ověřování uživatelů používá Auth0, a to prostřednictvím e-mailu, přihlášení přes sociální sítě nebo podnikového SSO, aby mohli prostřednictvím AI agentů pracovat se svými úkoly a osobními údaji. MCP server se bezpečně připojuje ke koncovým bodům API jménem uživatelů a přesně ukazuje, ke kterým zdrojům bude agent moci přistupovat, jakmile od uživatele získá souhlas. V této implementaci se přístupové tokeny automaticky obnovují během dlouhotrvajících interakcí.

Pro nastavení nejprve nasaďte chráněný API endpoint:

Poté nasaďte server MCP, který zajišťuje ověřování přes Auth0 a bezpečně propojuje AI agenty s vaším API endpointem.

Začínáme se vzdáleným MCP serverem, který k ověřování uživatelů a správě oprávnění udělených AI agentům používá AuthKit od WorkOS. V tomto příkladu MCP server dynamicky zpřístupňuje nástroje na základě role uživatele a jeho přístupových práv. Všichni ověření uživatelé získají přístup k add nástroj, ale pouze uživatelé, kterým byla přiřazena role image_generation oprávnění ve WorkOS může agentovi AI udělit přístup k nástroji pro generování obrázků. To ukazuje, jak servery MCP mohou podmíněně zpřístupňovat své možnosti agentům AI na základě role a oprávnění ověřeného uživatele.

Začínáme se vzdáleným MCP serverem, který používá Descope ↗ Inbound Apps k ověřování a autorizaci uživatelů (například e-mail, přihlášení přes sociální sítě, SSO) pro interakci s jejich daty prostřednictvím AI agentů. Pro jemnější řízení oprávnění využijte vlastní rozsahy (scopes) Descope k jejich definování a správě.

Váš server MCP, který využívá OAuth Provider Library ↗, dokáže zpracovat celý autorizační postup OAuth bez účasti třetí strany.

Knihovna Workers OAuth Provider ↗ je Cloudflare Worker, který implementuje fetch() handler, a zpracovává příchozí požadavky na váš MCP server.

Poskytnete vlastní handlery pro rozhraní API vašeho serveru MCP, vlastní logiku autentizace a autorizace a cesty URI pro koncové body OAuth, jak je znázorněno níže:

export default new OAuthProvider({
	apiRoute: "/mcp",
	// Your MCP server:
	apiHandler: MyMCPServer.serve("/mcp"),
	// Your handler for authentication and authorization:
	defaultHandler: MyAuthHandler,
	authorizeEndpoint: "/authorize",
	tokenEndpoint: "/token",
	clientRegistrationEndpoint: "/register",
});

Viz úvodní příklad pro kompletní příklad OAuthProvider v provozu, se simulovaným ověřovacím postupem.

Autorizační tok v tomto případě funguje takto:

sequenceDiagram
    participant B as User-Agent (Browser)
    participant C as MCP Client
    participant M as MCP Server (your Worker)

    C->>M: MCP Request
    M->>C: HTTP 401 Unauthorized
    Note over C: Generate code_verifier and code_challenge
    C->>B: Open browser with authorization URL + code_challenge
    B->>M: GET /authorize
    Note over M: User logs in and authorizes
    M->>B: Redirect to callback URL with auth code
    B->>C: Callback with authorization code
    C->>M: Token Request with code + code_verifier
    M->>C: Access Token (+ Refresh Token)
    C->>M: MCP Request with Access Token
    Note over C,M: Begin standard MCP message exchange

Nezapomeňte: autentizace se liší od autorizace ↗. Váš server MCP může autorizaci zajišťovat sám, přičemž se pro počáteční ověření uživatelů stále spoléhá na externí ověřovací službu. příklad v části Začínáme poskytuje simulovaný ověřovací postup. Budete si muset implementovat vlastní handler ověřování: buď ověřování zpracujete sami, nebo použijete externí ověřovací službu.

Když se uživatel ověří přes OAuth Provider, informace o jeho identitě jsou dostupné uvnitř vašich nástrojů. Způsob přístupu k nim závisí na tom, zda používáte McpAgent nebo createMcpHandler.

Tento vzor se týká pouze existujících zastaralých McpAgent routy. Třetí typový parametr definuje tvar kontextu autentizace. Přistupte k němu přes this.props uvnitř init() a handlery nástrojů.

import { McpAgent } from "agents/mcp";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

type AuthContext = {
	claims: { sub: string; name: string; email: string };
	permissions: string[];
};

export class MyMCP extends McpAgent<Env, unknown, AuthContext> {
	server = new McpServer({ name: "Auth Demo", version: "1.0.0" });

	async init() {
		this.server.tool("whoami", "Get the current user", {}, async () => ({
			content: [{ type: "text", text: `Hello, ${this.props.claims.name}!` }],
		}));
	}
}

Kompatibilní Workers OAuth Provider poskytuje standardní metadata tokenu na context.http.authInfo. Použijte getMcpAuthContext() pro existující props aplikace.

import { createMcpHandler, getMcpAuthContext } from "agents/mcp/server";
import { McpServer } from "@modelcontextprotocol/server";

function createServer() {
	const server = new McpServer({ name: "Auth Demo", version: "1.0.0" });

	server.registerTool(
		"whoami",
		{ description: "Get the current user", inputSchema: {} },
		async (_args, context) => {
			const auth = getMcpAuthContext();
			const name = (auth?.props.name as string) ?? "anonymous";
			return {
				content: [
					{
						type: "text",
						text: `${name}: ${context.http?.authInfo?.clientId}`,
					},
				],
			};
		},
	);

	return server;
}

export default {
	fetch(request, env, ctx) {
		return createMcpHandler(createServer)(request, env, ctx);
	},
} satisfies ExportedHandler;

Nezaznamenávejte do logu ani nevracejte surový přístupový token.

Můžete řídit, které nástroje jsou dostupné podle oprávnění uživatele. Existují dva přístupy: kontrola oprávnění uvnitř handleru nástroje, nebo podmíněná registrace nástrojů.

export class MyMCP extends McpAgent<Env, unknown, AuthContext> {
	server = new McpServer({ name: "Permissions Demo", version: "1.0.0" });

	async init() {
		this.server.tool("publicTool", "Available to all users", {}, async () => ({
			content: [{ type: "text", text: "Public result" }],
		}));

		this.server.tool(
			"adminAction",
			"Requires admin permission",
			{},
			async () => {
				if (!this.props.permissions?.includes("admin")) {
					return {
						content: [
							{ type: "text", text: "Permission denied: requires admin" },
						],
					};
				}
				return {
					content: [{ type: "text", text: "Admin action completed" }],
				};
			},
		);

		if (this.props.permissions?.includes("special_feature")) {
			this.server.tool("specialTool", "Special feature", {}, async () => ({
				content: [{ type: "text", text: "Special feature result" }],
			}));
		}
	}
}

Kontrola uvnitř handleru vrátí LLM chybovou zprávu, kterou může vysvětlit uživateli jako důvod zamítnutí. Podmíněná registrace nástrojů znamená, že LLM nikdy neuvidí nástroje, ke kterým uživatel nemá přístup: nemůže se je tedy ani pokusit zavolat.