← Создание агентов на Cloudflare / agents / model-context-protocol / protocol

Авторизация

При создании Model Context Protocol (MCP) ↗ сервера нужны два элемента: способ, позволяющий пользователям входить в систему (аутентификация), и способ, позволяющий им предоставлять MCP-клиенту доступ к ресурсам своей учётной записи (авторизация).

Model Context Protocol использует подмножество OAuth 2.1 для авторизации ↗. OAuth позволяет вашим пользователям предоставлять ограниченный доступ к ресурсам без необходимости делиться API-ключами или другими учётными данными.

Cloudflare предоставляет OAuth Provider Library ↗ который реализует сторону провайдера протокола OAuth 2.1, что позволяет легко добавить авторизацию в ваш MCP-сервер.

Вы можете использовать OAuth Provider Library четырьмя способами:

1. Используйте Cloudflare Access в качестве OAuth-провайдера.
2. Интегрируйтесь напрямую со сторонним поставщиком OAuth, например GitHub или Google.
3. Интегрируйтесь с собственным поставщиком OAuth, включая поставщиков authorization-as-a-service, на которых вы уже можете полагаться, например Stytch, Auth0 или WorkOS.
4. Ваш Worker сам занимается авторизацией и аутентификацией. Ваш MCP-сервер, работающий на Cloudflare, обрабатывает весь процесс OAuth.

В следующих разделах описан каждый из этих параметров и приведены ссылки на рабочие примеры кода для каждого из них.

Cloudflare Access позволяет добавить в ваш MCP-сервер функцию единого входа (SSO). Пользователи проходят аутентификацию на вашем MCP-сервере с помощью настроенный поставщик удостоверений или одноразовый PIN-код, и им предоставляется доступ, только если их идентичность совпадает с вашим Политики доступа.

Чтобы развернуть пример MCP-сервера ↗ с Cloudflare Access в качестве OAuth-провайдера, см. Защитите серверы MCP с помощью Access for SaaS.

OAuth Provider Library ↗ можно настроить на использование стороннего провайдера OAuth, например GitHub или Google. Полный пример есть в Пример GitHub.

Если вы используете стороннего OAuth-провайдера, необходимо передать обработчик в OAuthProvider который реализует поток OAuth для стороннего провайдера.

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",
});

Обратите внимание, что по мере того как определено в спецификации Model Context Protocol ↗ когда вы используете стороннего провайдера OAuth, MCP-сервер (ваш Worker) генерирует и выдаёт собственный токен 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

Прочитайте документацию по Библиотека Workers OAuth Provider ↗ для дополнительных сведений.

Если ваше приложение уже само реализует OAuth Provider или вы используете провайдера authorization-as-a-service, это можно использовать так же, как стороннего провайдера OAuth, описанного выше в (2) сторонний провайдер OAuth.

Вы можете использовать auth provider для того, чтобы:

• Позвольте пользователям аутентифицироваться на вашем MCP-сервере через электронную почту, вход через социальные сети, SSO (единый вход) и MFA (многофакторную аутентификацию).
• Определите scopes и разрешения, которые напрямую сопоставляются с вашими MCP-инструментами.
• Показывайте пользователям страницу согласия, отвечающую запрошенным разрешениям.
• Обеспечивайте соблюдение разрешений, чтобы агенты могли вызывать только разрешённые инструменты.

Начало работы с удалённый MCP-сервер, использующий Stytch ↗ чтобы пользователи могли входить по email, через Google или корпоративный SSO и авторизовывать своего AI-агента на просмотр и управление OKR компании от их имени. Stytch будет ограничивать области доступа, предоставляемые AI-агенту, на основе роли и разрешений пользователя в организации. При авторизации MCP Client каждый пользователь увидит страницу согласия с перечнем разрешений, которые запрашивает агент и которые пользователь может предоставить в соответствии со своей ролью.

Для дополнительных пользовательских сценариев разверните удалённый сервер MCP для приложения To Do, которое использует Stytch для аутентификации и авторизации клиента MCP. Пользователи могут войти по email и сразу получить доступ к своим спискам To Do, привязанным к аккаунту, а также предоставить доступ любому AI-ассистенту, чтобы тот помогал им управлять задачами.

Начало работы с удалённым MCP-сервером, который использует Auth0 для аутентификации пользователей через email, вход через социальные сети или корпоративный SSO, чтобы они могли работать со своими задачами и личными данными через ИИ-агентов. MCP-сервер безопасно подключается к эндпойнтам API от имени пользователей, точно показывая, к каким ресурсам агент сможет получить доступ после получения согласия от пользователя. В этой реализации токены доступа автоматически обновляются во время длительных взаимодействий.

Чтобы настроить это, сначала разверните защищённую конечную точку API:

Затем разверните MCP-сервер, который обрабатывает аутентификацию через Auth0 и безопасно подключает AI-агентов к вашей конечной точке API.

Начало работы с удалённым MCP-сервером, который использует AuthKit от WorkOS для аутентификации пользователей и управления разрешениями, предоставленными ИИ-агентам. В этом примере MCP-сервер динамически предоставляет инструменты на основе роли и прав доступа пользователя. Все аутентифицированные пользователи получают доступ к add инструмент, но только пользователи, которым назначена роль image_generation разрешение в WorkOS может предоставить ИИ-агенту доступ к инструменту генерации изображений. Это показывает, как MCP-серверы могут условно предоставлять свои возможности ИИ-агентам на основе роли и разрешений аутентифицированного пользователя.

Начало работы с удалённым MCP-сервером, который использует Descope ↗ Inbound Apps для аутентификации и авторизации пользователей (например, через email, вход через соцсети, SSO), чтобы они могли взаимодействовать со своими данными через ИИ-агентов. Используйте пользовательские scopes Descope, чтобы определять и управлять разрешениями с более высокой точностью.

Ваш MCP-сервер, использующий OAuth Provider Library ↗, может обработать весь поток авторизации OAuth самостоятельно, без участия третьей стороны.

Библиотека Workers OAuth Provider ↗ это Cloudflare Worker, который реализует fetch() обработчик, и обрабатывает входящие запросы к вашему MCP серверу.

Вы самостоятельно реализуете обработчики API вашего MCP-сервера, логику аутентификации и авторизации, а также пути URI для конечных точек OAuth, как показано ниже:

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",
});

См. вводный пример для полного примера OAuthProvider в использовании, с имитационным процессом аутентификации.

В этом случае поток авторизации работает так:

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

Помните: аутентификация отличается от авторизации ↗. Ваш MCP-сервер может обрабатывать авторизацию самостоятельно, полагаясь при этом на внешнюю службу аутентификации для первичной аутентификации пользователей. пример в разделе Начало работы предоставляет имитационный процесс аутентификации. Вам потребуется реализовать собственный обработчик аутентификации: либо обрабатывать аутентификацию самостоятельно, либо использовать внешний сервис аутентификации.

Когда пользователь проходит аутентификацию через OAuth Provider, информация о его личности становится доступна внутри ваших инструментов. Способ доступа к ней зависит от того, используете ли вы McpAgent или createMcpHandler.

Этот паттерн применяется только к существующим устаревшим McpAgent routes. Третий параметр типа определяет форму контекста аутентификации. Обращайтесь к нему через this.props внутри init() и обработчики инструментов.

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}!` }],
		}));
	}
}

Совместимый Workers OAuth Provider предоставляет стандартные метаданные токена по адресу context.http.authInfo. Используйте getMcpAuthContext() для существующих props приложения.

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;

Не записывайте в лог и не возвращайте исходный токен доступа.

Вы можете управлять доступностью инструментов в зависимости от прав пользователя. Есть два подхода: проверять права внутри обработчика инструмента или регистрировать инструменты условно.

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" }],
			}));
		}
	}
}

Проверка внутри обработчика возвращает LLM сообщение об ошибке, которое можно показать пользователю как объяснение отказа. Условная регистрация инструментов означает, что LLM никогда не увидит инструменты, к которым у пользователя нет доступа: он не сможет даже попытаться их вызвать.