跳到主要内容

MCP 身份验证

Almirant MCP 服务器要求所有操作均使用有效的 API Key。身份验证通过带有 Bearer 令牌的 Authorization 请求头完成。

获取 API Key​

  1. 在 Almirant 中，从侧边栏菜单进入 Settings
  2. 导航至 API Keys 部分
  3. 点击 创建 API Key
  4. 为其指定描述性名称（例如，“Claude Code - 我的项目”）
  5. 复制生成的 API Key
保存你的 API Key

API Key 创建时只会显示一次。请复制并安全保存它。如果丢失，则需要生成新的 API Key。

有关 API Key 管理的更多信息，请参阅功能部分中的 API Keys 文档。

MCP 服务器 URL​

https://api.almirant.ai/mcp

用于本地开发：

http://localhost:3001/mcp

身份验证请求头​

所有请求都必须包含以下请求头：

Authorization: Bearer <your-api-key>

在 Claude Code 中配置​

在项目根目录中创建或编辑 .mcp.json 文件：

{
  "mcpServers": {
    "almirant": {
      "type": "http",
      "url": "https://api.almirant.ai/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}
项目范围限定

若要将操作限制在特定项目中，请将 projectId 参数添加到 URL。详情请参阅项目范围限定。

在 Cursor 中配置​

Cursor 原生支持 MCP。请将配置添加到 Cursor 的 MCP 设置文件（.cursor/mcp.json）中：

{
  "mcpServers": {
    "almirant": {
      "type": "http",
      "url": "https://api.almirant.ai/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

全局配置（所有项目）​

如果希望 Almirant 在所有项目中可用，而无需在每个项目中创建 .mcp.json，请将配置添加到 ~/.claude/settings.json：

{
  "mcpServers": {
    "almirant": {
      "type": "http",
      "url": "https://api.almirant.ai/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

常见身份验证错误​

代码消息原因解决方案
401UnauthorizedAPI Key 缺失或无效验证 Authorization 请求头是否包含 Bearer <api-key>
401API key expiredAPI Key 已被撤销在 Settings 中生成新的 API Key
403ForbiddenAPI Key 没有请求资源的权限验证 API Key 权限
500Error: could not resolve organizationId from API keyAPI Key 未关联组织从正确的组织生成新的 API Key

验证连接​

配置完成后，你可以使用 get_current_user 工具验证连接是否正常工作：

{
  "tool": "get_current_user"
}

该工具会返回已验证用户的个人资料，包括 id、name、email 和 organizationId。如果身份验证失败，你会收到描述性错误。