MCP Docs - Authorization
Overview
- Learn how to implement secure authorization for MCP servers using OAuth 2.1 to protect sensitive resources and operations.
- Authorization in the Model Context Protocol (MCP) secures access to sensitive resources and operations exposed by MCP servers.
- If your MCP server handles user data or administrative actions, authorization ensures only permitted users can access its endpoints.
- MCP uses standardized authorization flows to build trust between MCP clients and MCP servers.
- Its design doesn’t focus on one specific authorization or identity system, but rather follows the conventions outlined for OAuth 2.1.
- For detailed information - https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization
OAuth 2.1
Authorization Code Flow with PKCE
Higress
When Should You Use Authorization?
While authorization for MCP servers is optional, it is strongly recommended when:
- Your server accesses user-specific data (emails, documents, databases)
- You need to audit who performed which actions
- Your server grants access to its APIs that require user consent
- You’re building for enterprise environments with strict access controls
- You want to implement rate limiting or usage tracking per user
Authorization for Local MCP Servers
- For MCP servers using the STDIO transport
- you can use environment-based credentials or credentials provided by third-party libraries embedded directly in the MCP server instead.
- Because a STDIO-built MCP server runs locally
- it has access to a range of flexible options when it comes to acquiring user credentials
- that may or may not rely on in-browser authentication and authorization flows.
- OAuth flows, in turn, are designed for HTTP-based transports where the MCP server is remotely-hosted
- and the client uses OAuth to establish that a user is authorized to access said remote server.
OAuth 2.1 + PKCE
| Key | Value |
|---|---|
| 安全性 | 远程访问需要标准化、可审计的授权机制 |
| 灵活性 | 本地工具可以使用任何适合的认证方式 |
| 用户体验 | 本地工具无缝集成，远程工具安全可控 |
| 业界标准 | OAuth 是互联网授权的事实标准 |
OAuth 2.1 + PKCE vs OIDC
Dex
Higress → Keycloak → Dex → 公司 SSO
Keycloak
The Authorization Flow: Step by Step
Let’s walk through what happens when a client wants to connect to your protected MCP server:
Initial Handshake
MCP（Model Context Protocol）服务器的 OAuth 2.0 授权流程的初始握手阶段
- When your MCP client first tries to connect
- your server responds with a
401 Unauthorizedand tells the client where to find authorization information - captured in a Protected Resource Metadata (PRM) document.
- your server responds with a
- The document is hosted by the MCP server, follows a predictable path pattern
- and is provided to the client in the
resource_metadataparameter within theWWW-Authenticateheader.
- and is provided to the client in the
1 | HTTP/1.1 401 Unauthorized |
- This tells the client that authorization is required for the MCP server
- and where to get the necessary information to kickstart the authorization flow.
Protected Resource Metadata Discovery
发现并获取受保护资源元数据
- With the URI pointer to the PRM document
- the client will fetch the metadata to learn about
- the authorization server, supported scopes, and other resource information.
- The data is typically encapsulated in a JSON blob, similar to the one below.
1 | { |
Authorization Server Discovery
发现授权服务器的详细能力
- Next, the client discovers what the authorization server can do by fetching its metadata.
- If the PRM document lists more than one authorization server, the client can decide which one to use.
- With an authorization server selected
- the client will then construct a standard metadata URI and issue a request to
- the OpenID Connect (OIDC) Discovery or OAuth 2.0 Auth Server Metadata endpoints
- depending on authorization server support
- and retrieve another set of metadata properties
- that will allow it to know the endpoints it needs to complete the authorization flow.
1 | { |
/.well-known/openid-configuration vs /.well-known/oauth-authorization-server
1 | { |
Client Registration
客户端注册 - MCP 客户端开发者
- With all the metadata out of the way, the client now needs to make sure that it’s registered with the authorization server.
- This can be done in two ways - pre-registered or Dynamic Client Registration
pre-registered
- First, the client can be pre-registered with a given authorization server
- in which case it can have embedded client registration information that it uses to complete the authorization flow.
授权服务器可以完全控制客户端列表
Dynamic Client Registration
- Alternatively, the client can use Dynamic Client Registration (DCR) to dynamically register itself with the authorization server.
- The latter scenario requires the authorization server to support DCR.
- If the authorization server does support DCR, the client will send a request to the registration_endpoint with its information
- If the registration succeeds, the authorization server will return a JSON blob with client registration information.
1 | { |
No DCR or Pre-Registration
- In case an MCP client connects to an MCP server
- that doesn’t use an authorization server that supports DCR
- and the client is not pre-registered with said authorization server
- it’s the responsibility of the client developer to provide an affordance for the end-user to enter client information manually.
User Authorization
用户授权与令牌获取
- The client will now need to open a browser to the
/authorizeendpoint- where the user can log in and grant the required permissions.
- The authorization server will then redirect back to the client with an authorization code
- that the client exchanges for tokens
1 | { |
- The access token is what the client will use to authenticate requests to the MCP server.
- This step follows standard OAuth 2.1 authorization code with PKCE conventions.
本质上是利用了单向散列的安全性，用于替代 OAuth 2.0 中存储 client_secret 的安全问题
OAuth 2.1 Authorization Code with PKCE 的安全性
Making Authenticated Requests
Finally, the client can make requests to your MCP server using the access token embedded in the Authorization header:
1 | GET /mcp HTTP/1.1 |
The MCP server will need to validate the token and process the request if the token is valid and has the required permissions.
MCP Server Token 验证机制
MCP 场景：JWT + 本地验证
Implementation Example
- To get started with a practical implementation, we will use a Keycloak authorization server hosted in a Docker container.
- Keycloak is an open-source authorization server that can be easily deployed locally for testing and experimentation.
Keycloak Setup
From your terminal application, run the following command to start the Keycloak container:
1 | docker run -p 127.0.0.1:8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak start-dev |
- This command will pull the Keycloak container image locally and bootstrap the basic configuration.
- It will run on port
8080and have anadminuser withadminpassword.
Not for Production
- The configuration above may be suitable for testing and experimentation; however, you should never use it in production.
- Refer to the Configuring Keycloak for production guide for additional details on
- how to deploy the authorization server for scenarios that require reliability, security, and high availability.
You will be able to access the Keycloak authorization server from your browser at
http://localhost:8080.
- When running with the default configuration
- Keycloak will already support many of the capabilities that we need for MCP servers
- including Dynamic Client Registration.
- You can check this by looking at the OIDC configuration, available at
http://localhost:8080/realms/master/.well-known/openid-configuration
1 | { |
Client scopes
- We will also need to set up Keycloak to support our scopes and allow our host (local machine) to dynamically register clients
- as the default policies restrict anonymous dynamic client registration.
- Go to Client scopes in the Keycloak dashboard and create a new
mcp:toolsscope.- We will use this to access all of the tools on our MCP server.
- After creating the scope, make sure that you assign its type to Default and have flipped the Include in token scope switch
- as this will be needed for token validation.
Audience
Audience (aud) 是 JWT（JSON Web Token）中的一个标准声明，用于标识该令牌是为谁发行的
- Let’s now also set up an audience for our Keycloak-issued tokens.
- An audience is important to configure because it embeds the intended destination directly into the issued access token.
- This helps your MCP server to verify that the token it got was actually meant for it rather than some other API.
- This is key to help avoid token passthrough scenarios.
To do this, open your mcp:tools client scope and click on Mappers, followed by Configure a new mapper. Select Audience.
- For Name, use
audience-config. Add a value for Included Custom Audience, set tohttp://localhost:3000. - This will be the URI of our test MCP server.
Not for Production
- The audience configuration above is meant for testing.
- For production scenarios
- additional set-up and configuration will be required to ensure that audiences
- are properly constrained for issued tokens.
- Specifically, the audience needs to be based on the resource parameter passed from the client, not a fixed value.
Trusted Hosts
- Now, navigate to Clients, then Client registration, and then Trusted Hosts.
- Disable the Client URIs Must Match setting and add the hosts from which you’re testing.
- You can get your current host IP by running the
ifconfigcommand on Linux or macOS, oripconfigon Windows. - You can see the IP address you need to add by looking at the keycloak logs for a line that looks like
Failed to verify remote host : 192.168.215.1.
- Check that the IP address is associated with your host.
- This may be for a bridge network depending on your docker setup.
Getting the Host
If you are running Keycloak from a container, you will also be able to see the host IP from the Terminal in the container logs.
Client
- Lastly, we need to register a new client that we can use with the MCP server itself to talk to Keycloak for things like token introspection.
- To do that:
- Go to Clients.
- Click Create client.
- Give your client a unique Client ID and click Next.
- Enable Client authentication and click Next.
- Click Save.
- Worth noting that token introspection is just one of the available approaches to validate tokens.
- This can also be done with the help of standalone libraries, specific to each language and platform.
- When you open the client details, go to Credentials and take note of the Client Secret.
Handling Secrets
- Never embed client credentials directly in your code.
- We recommend using environment variables or specialized solutions for secret storage.
With Keycloak configured, every time the authorization flow is triggered, your MCP server will receive a token like this:
1 | eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI1TjcxMGw1WW5MWk13WGZ1VlJKWGtCS3ZZMzZzb3JnRG5scmlyZ2tlTHlzIn0.eyJleHAiOjE3NTU1NDA4MTcsImlhdCI6MTc1NTU0MDc1NywiYXV0aF90aW1lIjoxNzU1NTM4ODg4LCJqdGkiOiJvbnJ0YWM6YjM0MDgwZmYtODQwNC02ODY3LTgxYmUtMTIzMWI1MDU5M2E4IiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwL3JlYWxtcy9tYXN0ZXIiLCJhdWQiOiJodHRwOi8vbG9jYWxob3N0OjMwMDAiLCJzdWIiOiIzM2VkNmM2Yi1jNmUwLTQ5MjgtYTE2MS1mMmY2OWM3YTAzYjkiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiI3OTc1YTViNi04YjU5LTRhODUtOWNiYS04ZmFlYmRhYjg5NzQiLCJzaWQiOiI4ZjdlYzI3Ni0zNThmLTRjY2MtYjMxMy1kYjA4MjkwZjM3NmYiLCJzY29wZSI6Im1jcDp0b29scyJ9.P5xCRtXORly0R0EXjyqRCUx-z3J4uAOWNAvYtLPXroykZuVCCJ-K1haiQSwbURqfsVOMbL7jiV-sD6miuPzI1tmKOkN_Yct0Vp-azvj7U5rEj7U6tvPfMkg2Uj_jrIX0KOskyU2pVvGZ-5BgqaSvwTEdsGu_V3_E0xDuSBq2uj_wmhqiyTFm5lJ1WkM3Hnxxx1_AAnTj7iOKMFZ4VCwMmk8hhSC7clnDauORc0sutxiJuYUZzxNiNPkmNeQtMCGqWdP1igcbWbrfnNXhJ6NswBOuRbh97_QraET3hl-CNmyS6C72Xc0aOwR_uJ7xVSBTD02OaQ1JA6kjCATz30kGYg |
Decoded, it will look like this:
1 | { |
Embedded Audience
- Notice the
audclaim embedded in the token - it’s currently set to be the URI of the test MCP server and it’s inferred from the scope that we’ve previously configured.
- This will be important in our implementation to validate.
MCP Server Setup
- We will now set up our MCP server to use the locally-running Keycloak authorization server.
- Depending on your programming language preference, you can use one of the supported MCP SDKs.
- For our testing purposes, we will create an extremely simple MCP server that exposes two tools
- one for addition and another for multiplication. The server will require authorization to access these.
Python
- To simplify our authorization interaction, in Python scenarios we rely on FastMCP.
- Many of the conventions around authorization, like the endpoints and token validation logic
- are consistent across languages, but some offer simpler ways of integrating them in production scenarios.
- Prior to writing the actual server, we need to set up our configuration in
config.py- the contents are entirely based on your local server setup:
1 | """Configuration settings for the MCP auth server.""" |
The server implementation is as follows:
1 | import datetime |
- Lastly, the token verification logic is delegated entirely to
token_verifier.py - ensuring that we can use the Keycloak introspection endpoint to verify the validity of any credential artifacts
1 | """Token verifier implementation using OAuth 2.0 Token Introspection (RFC 7662).""" |
启动并测试 MCP Server
Testing the MCP Server
Visual Studio Code
- For testing purposes, we will be using Visual Studio Code
- but any client that supports MCP and the new authorization specification will fit.
- Press Cmd + Shift + P and select MCP: Add server…. Select HTTP and enter
http://localhost:3000. - Give the server a unique name to be used inside Visual Studio Code.
- In
mcp.jsonyou should now see an entry like this:
1 | "my-mcp-server-18676652": { |
On connection, you will be taken to the browser, where you will be prompted to consent to Visual Studio Code having access to the mcp:tools scope.
After consenting, you will see the tools listed right above the server entry in mcp.json.
You will be able to invoke individual tools with the help of the # sign in the chat view.
Claude Code
~/.claude.json
1 | "mcpServers": { |
Common Pitfalls and How to Avoid Them
- For comprehensive security guidance, including attack vectors, mitigation strategies, and implementation best practices,
- make sure to read through Security Best Practices. A few key issues are called out below.
Do not implement token validation or authorization logic by yourself.
- Use off-the-shelf, well-tested, and secure libraries for things like token validation or authorization decisions.
- Doing everything from scratch means that you’re more likely to implement things incorrectly unless you are a security expert.
Use short-lived access tokens
- Depending on the authorization server used, this setting might be customizable.
- We recommend to not use long-lived tokens
- if a malicious actor steals them, they will be able to maintain their access for longer periods.
Always validate tokens
- Just because your server received a token does not mean that the token is valid or that it’s meant for your server.
- Always verify that what your MCP server is getting from the client matches the required constraints.
Store tokens in secure, encrypted storage
- In certain scenarios, you might need to cache tokens server-side.
- If that is the case, ensure that the storage has the right access controls and cannot be easily exfiltrated
- by malicious parties with access to your server.
- You should also implement robust cache eviction policies
- to ensure that your MCP server is not re-using expired or otherwise invalid tokens.
Enforce HTTPS in production
- Do not accept tokens or redirect callbacks over plain HTTP except for
localhostduring development.
Least-privilege scopes
- Don’t use catch‑all scopes.
- Split access per tool or capability where possible and verify required scopes per route/tool on the resource server.
Don’t log credentials
- Never log
Authorizationheaders, tokens, codes, or secrets. - Scrub query strings and headers.
- Redact sensitive fields in structured logs.
Separate app vs. resource server credentials
- Don’t reuse your MCP server’s client secret for end‑user flows.
- Store all secrets in a proper secret manager, not in source control.
Return proper challenges
- On 401, include
WWW-AuthenticatewithBearer,realm, andresource_metadata - so clients can discover how to authenticate.
DCR (Dynamic Client Registration) controls
- If enabled, be aware of constraints specific to your organization
- such as trusted hosts, required vetting, and audited registrations.
- Unauthenticated DCR means that anyone can register any client with your authorization server.
Multi‑tenant/realm mix-ups
- Pin to a single issuer/tenant unless explicitly multi‑tenant.
- Reject tokens from other realms even if signed by the same authorization server.
Audience/resource indicator misuse
- Don’t configure or accept generic audiences (like
api) or unrelated resources. - Require the audience/resource to match your configured server.
Error detail leakage
- Return generic messages to clients, but log detailed reasons with correlation IDs internally
- to aid troubleshooting without exposing internals.
Session identifier hardening
- Treat
Mcp-Session-Idas untrusted input; never tie authorization to it. - Regenerate on auth changes and validate lifecycle server‑side.
Related Standards and Documentation
MCP authorization builds on these well-established standards
| Standards | Desc |
|---|---|
| OAuth 2.1 | The core authorization framework |
| RFC 8414 | Authorization Server Metadata discovery |
| RFC 7591 | Dynamic Client Registration |
| RFC 9728 | Protected Resource Metadata |
| RFC 8707 | Resource Indicators |
For additional details, refer to
All articles on this blog are licensed under CC BY-NC-SA 4.0 unless otherwise stated.
Related Articles
2026-03-02
MCP - Introduction
Background Generative AI applications are a great step forward as they often let the user interact with the app using natural language prompts. However, as more time and resources are invested in such apps, you want to make sure you can easily integrate functionalities and resources in such a way that it’s easy to extend, that your app can cater to more than one model being used, and handle various model intricacies. In short, building Gen AI apps is easy to begin with, but as they grow and become more c...
2026-03-03
MCP Docs - Overview
Introduction MCP (Model Context Protocol) is an open-source standard for connecting AI applications to external systems. Using MCP, AI applications like Claude or ChatGPT can connect to data sources (e.g. local files, databases) tools (e.g. search engines, calculators) workflows (e.g. specialized prompts)—enabling them to access key information and perform tasks. Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect electronic devices MCP provides a s...
2026-03-03
MCP Docs - Architecture
Overview This overview of the Model Context Protocol (MCP) discusses its scope and core concepts, and provides an example demonstrating each core concept. Because MCP SDKs abstract away many concerns, most developers will likely find the data layer protocol section to be the most useful. It discusses how MCP servers can provide context to an AI application. Scope MCP focuses on context exchange MCP Specification A specification of MCP that outlines the implementation requirements for clients and s...
2024-08-08
RAG - Frameworks
Overview Retrieval-Augmented Generation (RAG) is an AI framework that enhances the capabilities of large language models (LLMs) by incorporating external knowledge sources. It helps overcome limitations such as knowledge cutoff dates and reduces the risk of hallucinations in LLM outputs. RAG works by retrieving relevant information from a knowledge base and using it to augment the LLM’s input, allowing the model to generate more accurate, up-to-date, and contextually relevant responses. Haystack Hays...
2024-07-02
LLM Core - Machine Learning Concept
机器学习 机器学习是让计算机利用数据来学习如何完成任务 机器学习允许计算机通过分析和学习数据来自我改进以及作出决策 房价预测 利用 scikit-learn 进行预测 数据集 housing_data.csv 面积 卧室数量 地理位置 售价 100 2 1 300 150 3 2 450 120 2 2 350 80 1 1 220 线性回归12345678910111213141516171819202122232425from sklearn.model_selection import train_test_splitfrom sklearn.linear_model import LinearRegressionimport pandas as pd# 加载数据集data = pd.read_csv("housing_data.csv") # 假设这是我们的房屋数据# 准备数据X = data[['面积', '卧室数量', '地理位置']] # 特征y = data[...
2025-01-18
AI Agent - Overview
技术更迭 LLM 应用工程化难题 模型与外部世界割裂 LLM 是基于概率计算的新范式，虽然很强大，但仍需要与传统的结构化计算范式相结合，即通过工具调用来完成精确任务 目前传统结构化工具与 LLM 之间是割裂的，LLM 难以直接动态地接入实时数据、数据库或企业工具 传统的 API 调用方式零散且不标准，导致开发效率低下 Agent 协作的孤岛效应 不同 Agent 框架（LangGraph、AutoGen、CrewAI）各自为政，缺乏统一的通信标准，跨平台协作很难实现 复杂场景的工程化瓶颈 从搜索助手到企业知识中台、RAG 与多 Agent 系统需要处理多源数据、多模态交互和长时任务，现有工具链难以提供统一的解决方案 MCP + A2A 标准化 + 可扩展 MCP 模型主控 + 客户端驱动 MCP 是一个为 LLM 更方便地利用外部资源（主要是工具）而设计的标准化接口，旨在打破 LLM 与外部数据、工具之间的壁垒 传统上，将 AI 系统连接到外部工具需要集成多个 API - 代码冗余 + 难以维护 + 扩展性差 MCP 将繁琐细节都隐藏到服务器端 - 开发者只需关心 LLM...
