MCP授权和范围

The Casdoor MCP server authorizes tool calls by OAuth 2.0 scopes. A request that is authenticated with an access token can call only the tools that the scopes of the token allow. This lets you issue tokens with the least privilege that a task needs.

A request that is authenticated with a session cookie isn't checked against scopes and can call all tools.

How scopes control tools

Each tool requires one scope. A scope has the form resource:action: the resource is the kind of object, and the action is read or write. For example:

• application:read allows get_applications and get_application.
• application:write allows add_application, update_application, and delete_application.

tools/list with a token returns only the tools that the token can call. A request without credentials still receives the full list for discovery, but can't call any tool.

Some tools have requirements beyond the scope:

• Creating an application counts against the application quota of the organization.
• Applications with an IP allowlist are subject to that check.
• In demo mode, Casdoor rejects write operations.

Scope reference

Application scopes

作用域	映射的工具	描述
application:read	get_applications、get_application	查看应用程序配置和设置
application:write	add_application、update_application、delete_application	创建、修改和删除应用程序

User scopes

作用域	映射的工具	描述
user:read	get_users、get_user	查看用户个人资料和信息
user:write	add_user、update_user、delete_user	创建、修改和删除用户账户

Organization scopes

作用域	映射的工具	描述
organization:read	get_organizations、get_organization	查看组织详情和设置
organization:write	add_organization、update_organization、delete_organization	创建、修改和删除组织

Role scopes

作用域	映射的工具	映射的工具
role:read	get_roles、get_role	查看角色定义和分配
role:write	add_role, update_role, delete_role	创建、修改和删除角色

Permission scopes

作用域	映射的工具	描述
permission:read	get_permissions、get_permission	查看权限配置
permission:write	add_permission、update_permission、delete_permission	创建、修改和删除权限

Provider scopes

作用域	映射的工具	描述
provider:read	get_providers、get_provider	查看OAuth、短信、电子邮件及其他提供商配置
provider:write	add_provider、update_provider、delete_provider	创建、修改和删除提供商集成

Token scopes

作用域	映射的工具	描述
token:read	get_tokens、get_token	查看访问令牌及其元数据
token:write	delete_token	删除访问令牌

Alias scopes

Three aliases stand for groups of scopes:

Alias	Stands for
read	Every :read scope
write	Every :write scope
admin	Every :read and :write scope

Request a token with scopes

Name the scopes in the token request. For a token that can read applications but can't change them:

curl -X POST https://your-casdoor.com/api/login/oauth/access_token \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=application:read"

For a token that can also create and change applications:

curl -X POST https://your-casdoor.com/api/login/oauth/access_token \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=application:write"

Separate several scopes with spaces: scope=application:read application:write. In a URL, encode the space as %20.

Missing scopes

When a token calls a tool without the required scope, Casdoor returns the error insufficient_scope:

{
  "jsonrpc": "2.0",
  "id": 10,
  "error": {
    "code": -32001,
    "message": "insufficient_scope",
    "data": {
      "tool": "add_application",
      "granted_scopes": ["application:read"],
      "required_scope": "application:write"
    }
  }
}

required_scope is the scope that the tool needs, and granted_scopes are the scopes of your token. Request a new token that includes the required scope.

Define scopes for your own MCP server

When Casdoor is the OAuth 2.0 provider of an MCP server that you build, define scopes that match the capabilities of your server.

1. In the Casdoor admin console, open the edit page of the application and set Category to Agent.
2. Add your scopes to the application, each with a name, a display name, and a description. See Custom scopes.
3. In your MCP server, read the granted scopes from the scope claim of the access token and check them before you run a tool.

The scopes appear in the discovery document of the application and on the consent screen.

For example, a file management server could define:

名称	显示名称	描述
files:read	读取文件	查看并下载存储中的文件
files:write	写文件	创建、修改和删除文件
metadata:read	读取元数据	查看文件元数据和属性

Consent screen

When a user authorizes an MCP client, Casdoor asks for consent if both of the following conditions hold:

• The application defines custom scopes.
• The client requests at least one of them, and the user hasn't granted it to the application before.

The consent screen lists the requested scopes with their display names and descriptions. After the user clicks Allow, Casdoor remembers the grant and doesn't ask again for the same scopes. Users and administrators can see and revoke grants on the Consents page.

Casdoor doesn't show a consent screen for applications without custom scopes.

Add fine-grained rules with Casbin

Scopes answer the question of which tools a client may call. For rules that depend on the user or the object, use the permissions of Casdoor, which are built on Casbin. A Casbin policy can decide by:

• Attributes of the user, such as the organization, the role, or the department
• Properties of the object, such as its owner
• The environment, such as the time or the IP address
• Relationships, such as "the user owns the object"

要在您的MCP服务器中使用Casbin：

1. Define a Casbin model in Casdoor that describes your rules.
2. Create a permission that connects your application to the model.
3. Add policies that map users and roles to actions.
4. In your MCP server, check the permission after you have checked the scope.

A request must pass both checks.

See also

• MCP tools reference
• Custom scopes
• Permissions