MCP 配置与 OAuth

配置本地与远程服务器，插值环境变量，并注册各客户端的 OAuth 回调。

This page has not been translated into English yet. The original Chinese version is shown below.

项目配置位于 .cursor/mcp.json，用户配置位于 ~/.cursor/mcp.json。选择传输方式后，使用对应字段，避免把本地进程配置套到远程服务器。

本地 stdio

下面连接已经存在的 Python server，并从环境读取所需密钥：

{
  "mcpServers": {
    "local-tools": {
      "type": "stdio",
      "command": "python",
      "args": ["${workspaceFolder}/tools/mcp_server.py"],
      "env": { "API_KEY": "${env:API_KEY}" }
    }
  }
}

command 必须在 PATH 中或为完整路径。args 与 env 可选，envFile 可从指定文件加载变量，但仅适用于 stdio。官方部分简例省略 type，而字段表把它列为必填；此处显式设置 stdio。

配置插值

command、args、env、url、headers 支持变量：

语法	内容
${env:NAME}	环境变量
${userHome}	用户主目录
${workspaceFolder}	包含项目 .cursor/mcp.json 的根目录
${workspaceFolderBasename}	项目根名称
${pathSeparator}、${/}	系统路径分隔符

远程 HTTP/SSE 不支持 envFile，应通过进程环境与插值传入 headers 或 auth 值。

静态 OAuth

提供者不支持动态注册，或给定固定 Client ID 时，可在 url 服务器中添加 auth：

{
  "mcpServers": {
    "remote-tools": {
      "url": "https://api.example.com/mcp",
      "auth": {
        "CLIENT_ID": "${env:MCP_CLIENT_ID}",
        "CLIENT_SECRET": "${env:MCP_CLIENT_SECRET}",
        "scopes": ["read"]
      }
    }
  }
}

CLIENT_ID 必填，CLIENT_SECRET 仅在提供者要求时设置；scopes 可选，省略时从 /.well-known/oauth-authorization-server 发现 scopes_supported。示例地址与 scope 必须替换为真实提供者配置。

回调地址

Web/Cursor Agents 使用 https://www.cursor.com/agents/mcp/oauth/callback，桌面使用 http://localhost:8787/callback。两端都会认证时，两者都要注册为允许的 redirect URI；服务器通过 OAuth state 区分。

认证后仍受工具批准与团队策略控制。连接失败时查看 Output 中的 MCP Logs。