OAuth 客户端凭证

OAuth 客户端凭证扩展（io.modelcontextprotocol/oauth-client-credentials）为 MCP 添加了对 OAuth 2.0 客户端凭证流程的支持。这使得自动化系统能够在无需交互式用户授权的情况下连接到 MCP 服务器。

规范

OAuth 客户端凭证扩展的完整技术规范。

它是什么

标准 MCP 授权流程要求用户交互式地批准访问——浏览器打开，用户登录，并授予权限。这对人类用户效果很好，但当没有用户在场时会失效。 OAuth 客户端凭证扩展通过允许客户端使用应用级凭证（客户端 ID 和密钥，或签名的 JWT 断言）而不是委托的用户凭证进行认证来解决这个问题。客户端直接向授权服务器证明其身份，授权服务器颁发访问令牌，无需浏览器重定向或用户交互。

何时使用

当以下情况时使用 OAuth 客户端凭证：

后台服务需要在没有用户在场的情况下按计划或响应事件调用 MCP 工具
CI/CD 流水线作为自动化构建、测试或部署工作流的一部分调用 MCP 服务器
服务器到服务器的集成连接两个没有最终用户参与的后端系统
守护进程或长期运行的工作者需要持久访问 MCP 资源

如果您的集成涉及应该明确授权访问的人类用户，请改用标准 MCP 授权流程。

工作原理

该扩展支持两种凭证格式：

JWT Bearer 断言（推荐）

定义于 RFC 7523，JWT Bearer 断言允许客户端使用其私钥签名令牌，并将其作为身份证明呈现。授权服务器使用客户端注册的公钥验证签名。 JWT 断言通常包括：

iss: 客户端 ID（颁发者）
sub: 客户端 ID（被认证的主体）
aud: 授权服务器令牌端点 URL
exp: 过期时间
iat: 签发时间

客户端密钥

对于更简单的部署，该扩展还支持使用 client_id 和 client_secret 的标准客户端凭证流程。客户端将其凭证直接发送到授权服务器的令牌端点，并接收访问令牌作为交换。

客户端密钥是长期凭证，授予无需用户交互的访问权限。如果密钥泄露，攻击者可以静默认证为您的应用，直到密钥被轮换。为了降低风险：

将密钥存储在密钥管理器中，切勿存储在签入版本控制的源代码或环境文件中。
定期轮换密钥，并在任何疑似泄露后立即轮换。
将凭证权限范围限制为所需的最小权限。
尽可能首选 JWT 断言——它们是短期的，且不需要传输签名密钥。

实施指南

对于 MCP 客户端

要使用 OAuth 客户端凭证扩展，您的客户端必须：

声明支持

在其每次请求的能力中包含该扩展：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "...",
  "params": {
    // 其他字段...
    "_meta": {
      // 其他字段...
      "io.modelcontextprotocol/clientCapabilities": {
        "extensions": {
          "io.modelcontextprotocol/oauth-client-credentials": {},
        },
      },
    },
  },
}

获取访问令牌

在连接到 MCP 服务器之前，使用客户端凭证授权从授权服务器请求令牌。

包含令牌

在发送给 MCP 服务器的 HTTP 请求的 Authorization 头中传递令牌：

Authorization: Bearer <access_token>

处理令牌刷新

客户端凭证令牌通常比用户委托令牌的寿命更短。实施令牌刷新逻辑以便在过期前获取新令牌。

对于 MCP 服务器

要接受客户端凭证令牌，您的服务器必须：

验证令牌

在每个请求上，针对授权服务器的公钥验证 JWT 签名和声明（通常通过 JWKS 端点）。

检查作用域

确保令牌包含请求操作所需的作用域。

宣告支持

可选地（但为了便于发现，建议这样做），在 server/discover 响应中包含该扩展：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    // 其他字段...
    "capabilities": {
      "extensions": {
        "io.modelcontextprotocol/oauth-client-credentials": {},
      },
    },
  },
}

SDK 示例

官方 MCP SDK 提供对客户端凭证认证的内置支持。两者都自动处理令牌获取和刷新。

安装 SDK

TypeScript
Python

npm install @modelcontextprotocol/client

pip install mcp

创建提供者并连接

选择与您设置匹配的凭证格式：

使用客户端密钥

TypeScript
Python

import {
  Client,
  ClientCredentialsProvider,
  StreamableHTTPClientTransport,
} from "@modelcontextprotocol/client";

const provider = new ClientCredentialsProvider({
  clientId: "my-service",
  clientSecret: "s3cr3t",
});

const client = new Client(
  { name: "my-service", version: "1.0.0" },
  { capabilities: {} },
);

const transport = new StreamableHTTPClientTransport(
  new URL("https://mcp.example.com/mcp"),
  { authProvider: provider },
);

await client.connect(transport);

// 使用客户端
const tools = await client.listTools();
console.log(
  "可用工具：",
  tools.tools.map((t) => t.name),
);

await transport.close();

import asyncio

import httpx2

from mcp import Client
from mcp.client.auth.extensions.client_credentials import (
    ClientCredentialsOAuthProvider,
)
from mcp.client.streamable_http import streamable_http_client
from mcp.shared.auth import OAuthClientInformationFull, OAuthToken


class InMemoryTokenStorage:
    def __init__(self) -> None:
        self.tokens: OAuthToken | None = None
        self.client_info: OAuthClientInformationFull | None = None

    async def get_tokens(self) -> OAuthToken | None:
        return self.tokens

    async def set_tokens(self, tokens: OAuthToken) -> None:
        self.tokens = tokens

    async def get_client_info(self) -> OAuthClientInformationFull | None:
        return self.client_info

    async def set_client_info(self, client_info: OAuthClientInformationFull) -> None:
        self.client_info = client_info


provider = ClientCredentialsOAuthProvider(
    server_url="https://mcp.example.com/mcp",
    storage=InMemoryTokenStorage(),
    client_id="my-service",
    client_secret="s3cr3t",
    scopes="read write",
)


async def main() -> None:
    async with httpx2.AsyncClient(auth=provider) as http_client:
        transport = streamable_http_client(
            "https://mcp.example.com/mcp",
            http_client=http_client,
        )
        async with Client(transport) as client:
            # 使用客户端
            tools = await client.list_tools()
            print("可用工具：", [t.name for t in tools.tools])


if __name__ == "__main__":
    asyncio.run(main())

使用 JWT 私钥

TypeScript
Python

import {
  Client,
  PrivateKeyJwtProvider,
  StreamableHTTPClientTransport,
} from "@modelcontextprotocol/client";

const provider = new PrivateKeyJwtProvider({
  clientId: "my-service",
  privateKey: process.env.CLIENT_PRIVATE_KEY_PEM,
  algorithm: "RS256",
});

const client = new Client(
  { name: "my-service", version: "1.0.0" },
  { capabilities: {} },
);

const transport = new StreamableHTTPClientTransport(
  new URL("https://mcp.example.com/mcp"),
  { authProvider: provider },
);

await client.connect(transport);

// 使用客户端
const tools = await client.listTools();
console.log(
  "可用工具：",
  tools.tools.map((t) => t.name),
);

await transport.close();

import asyncio
from pathlib import Path

import httpx2

from mcp import Client
from mcp.client.auth.extensions.client_credentials import (
    PrivateKeyJWTOAuthProvider,
    SignedJWTParameters,
)
from mcp.client.streamable_http import streamable_http_client
from mcp.shared.auth import OAuthClientInformationFull, OAuthToken


class InMemoryTokenStorage:
    def __init__(self) -> None:
        self.tokens: OAuthToken | None = None
        self.client_info: OAuthClientInformationFull | None = None

    async def get_tokens(self) -> OAuthToken | None:
        return self.tokens

    async def set_tokens(self, tokens: OAuthToken) -> None:
        self.tokens = tokens

    async def get_client_info(self) -> OAuthClientInformationFull | None:
        return self.client_info

    async def set_client_info(self, client_info: OAuthClientInformationFull) -> None:
        self.client_info = client_info


# 从密钥参数创建签名的 JWT 断言提供者
jwt_params = SignedJWTParameters(
    issuer="my-service",
    subject="my-service",
    signing_key=Path("private_key.pem").read_text(),
    signing_algorithm="RS256",
    lifetime_seconds=300,
)

provider = PrivateKeyJWTOAuthProvider(
    server_url="https://mcp.example.com/mcp",
    storage=InMemoryTokenStorage(),
    client_id="my-service",
    assertion_provider=jwt_params.create_assertion_provider(),
    scopes="read write",
)


async def main() -> None:
    async with httpx2.AsyncClient(auth=provider) as http_client:
        transport = streamable_http_client(
            "https://mcp.example.com/mcp",
            http_client=http_client,
        )
        async with Client(transport) as client:
            # 使用客户端
            tools = await client.list_tools()
            print("可用工具：", [t.name for t in tools.tools])


if __name__ == "__main__":
    asyncio.run(main())

客户端支持

对此扩展的支持因客户端而异。扩展是可选加入的，默认从不激活。

查看客户端矩阵以了解跨 MCP 客户端的当前实现状态。

ext-auth 仓库

源代码和参考实现

完整规范

带有规范性要求的技术规范

RFC 6749 — 客户端凭证授权

底层 OAuth 2.0 规范

RFC 7523 — JWT Bearer 断言

JWT 断言格式规范

MCP Apps

Authorization Extensions

Tasks

规范

它是什么

何时使用

工作原理

JWT Bearer 断言（推荐）

客户端密钥

实施指南

对于 MCP 客户端

对于 MCP 服务器

SDK 示例

使用客户端密钥

使用 JWT 私钥

客户端支持

相关资源

ext-auth 仓库

完整规范

RFC 6749 — 客户端凭证授权

RFC 7523 — JWT Bearer 断言

规范

​它是什么

​何时使用

​工作原理

​JWT Bearer 断言（推荐）

​客户端密钥

​实施指南

​对于 MCP 客户端

​对于 MCP 服务器

​SDK 示例

​使用客户端密钥

​使用 JWT 私钥

​客户端支持

​相关资源

ext-auth 仓库

完整规范

RFC 6749 — 客户端凭证授权

RFC 7523 — JWT Bearer 断言

它是什么

何时使用

工作原理

JWT Bearer 断言（推荐）

客户端密钥

实施指南

对于 MCP 客户端

对于 MCP 服务器

SDK 示例

使用客户端密钥

使用 JWT 私钥

客户端支持

相关资源