入门

选择兼容的 OAuth 2.1 或 OpenID Connect 提供商

MCP 规范对授权 (Authorization) 有一些特定要求：

• OAuth 2.1 IETF DRAFT
• OAuth 2.0 授权服务器元数据 (RFC 8414)
• OAuth 2.0 动态客户端注册协议 (RFC 7591)

虽然后两者不是强制性的，但第一个是确保安全和合规实现所必需的。

注释

在新的 MCP 草案中，RFC 8414 将对授权服务器（提供商）强制要求。我们会在新草案最终确定后更新文档。

你可以查看 MCP 兼容提供商列表 来确认你的提供商是否受支持。

安装 MCP Auth SDK

MCP Auth 同时支持 Python 和 TypeScript。如果你需要其他语言或框架的支持，请告诉我们！

Python

pip install mcpauth

或者你喜欢的其他包管理器，如 pipenv 或 poetry。

Node.js

npm install mcp-auth

或者你喜欢的其他包管理器，如 pnpm 或 yarn。

初始化 MCP Auth

第一步是使用你的提供商的授权服务器元数据初始化 MCP Auth 实例。如果你的提供商符合以下之一：

• OAuth 2.0 授权服务器元数据
• OpenID Connect 发现

你可以使用内置函数获取元数据并初始化 MCP Auth 实例：

Python

from mcpauth import MCPAuth
from mcpauth.config import AuthServerType
from mcpauth.utils import fetch_server_config

mcp_auth = MCPAuth(
    server=fetch_server_config(
      '<auth-server-url>',
      type=AuthServerType.OIDC # 或 AuthServerType.OAUTH
    )
)

Node.js

import { MCPAuth, fetchServerConfig } from 'mcp-auth';

const mcpAuth = new MCPAuth({
  server: await fetchServerConfig('<auth-server-issuer>', { type: 'oidc' }), // 或 'oauth'
});

如果你需要手动指定元数据 URL 或端点，请查看 其他初始化 MCP Auth 的方式。

挂载元数据端点

为了符合当前 MCP 规范，MCP Auth 会将 OAuth 2.0 授权服务器元数据端点 (/.well-known/oauth-authorization-server) 挂载到你的 MCP 服务器：

Python

from starlette.applications import Starlette

app = Starlette(routes=[
    mcp_auth.metadata_route(),
])

Node.js

import express from 'express';

const app = express();
app.use(mcpAuth.delegatedRouter());

元数据中的 URL 会保持不变，因此授权服务器的角色完全委托给提供商。你可以通过访问 MCP 服务器的 /.well-known/oauth-authorization-server 来测试元数据端点。

为什么只挂载元数据端点？

你可能会看到官方 SDK 提供了一个 auth 路由器，挂载了 /authorize、/token 等授权端点。我们不这样做的原因如下：

1. 只挂载元数据端点可以让你充分利用提供商的全部能力，而无需“重复造轮子”并给 MCP 服务器引入不必要的复杂性。
2. 目前也在推动将 MCP 服务器角色转变为资源服务器，并要求 OAuth 2.0 受保护资源元数据 (RFC 9728)。这意味着 MCP 服务器将不再处理任何授权 (Authorization) 逻辑（包括元数据端点），而只作为依赖提供商进行认证 (Authentication) 和授权 (Authorization) 的资源服务器。

注释

我们会在新 MCP 规范最终确定后，更新 MCP Auth 以支持新规范。在此期间，你可以使用当前版本，它与现有规范兼容。

使用 Bearer 认证 (Authentication) 中间件

一旦初始化 MCP Auth 实例，你就可以应用 Bearer 认证 (Authentication) 中间件来保护你的 MCP 路由：

Python

from starlette.applications import Starlette
from starlette.middleware import Middleware
from starlette.routing import Mount
from mcpauth import MCPAuth
from mcp.server.fastmcp import FastMCP

mcp = FastMCP()
mcp_auth = MCPAuth(
  # 用你的授权服务器配置初始化
)
bearer_auth = mcp_auth.bearer_auth_middleware(
    "jwt", required_scopes=["read", "write"]
)

app = Starlette(routes=[
    mcp_auth.metadata_route(),
    Mount(
        "/",
        app=mcp.sse_app(),
        middleware=[Middleware(bearer_auth)],
    ),
])

Node.js

import express from 'express';
import { MCPAuth } from 'mcp-auth';

const app = express();
const server = new McpServer(/* ... */);
const mcpAuth = new MCPAuth({
  /* ... */
});

app.use(mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] }));

在上面的例子中，我们指定了 jwt 令牌类型，并要求 read 和 write 权限 (Scopes)。它会自动校验 JWT (JSON Web Token)，并填充一个包含已认证 (Authentication) 用户信息的对象。

信息

之前没听说过 JWT (JSON Web Token)？别担心，你可以继续阅读文档，我们会在需要时进行解释。你也可以查看 Auth Wiki 进行快速了解。

关于 Bearer 认证 (Authentication) 配置的更多信息，请查看 配置 Bearer 认证 (Authentication)。

在 MCP 实现中获取认证 (Authentication) 信息

应用 Bearer 认证 (Authentication) 中间件后，你可以在 MCP 实现中访问已认证 (Authentication) 用户（或身份）的信息：

Python

MCP Auth 会在 Bearer 认证 (Authentication) 中间件成功认证 (Authentication) 后，将已认证 (Authentication) 用户信息存储在上下文变量中。你可以在 MCP 工具处理器中这样访问：

from mcp.server.fastmcp import FastMCP

mcp = FastMCP()
mcp_auth = MCPAuth(
  # 用你的授权服务器配置初始化
)

@mcp.tool()
def add(a: int, b: int):
    """
    一个将两个数字相加的工具。
    已认证 (Authentication) 用户的信息会在上下文中可用。
    """
    auth_info = mcp_auth.auth_info # 在当前上下文中访问认证 (Authentication) 信息
    if auth_info:
        print(f"Authenticated user: {auth_info.claims}")
    return a + b

Node.js

工具处理器的第二个参数会包含 authInfo 对象，其中包括已认证 (Authentication) 用户的信息：

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';

const server = new McpServer(/* ... */);
server.tool('add', { a: z.number(), b: z.number() }, async ({ a, b }, { authInfo }) => {
  // 现在你可以使用 `authInfo` 对象访问认证 (Authentication) 信息
});

下一步

继续阅读，了解如何将 MCP Auth 与 MCP 服务器集成的端到端示例，以及如何在 MCP 客户端中处理认证 (Authentication) 流程。