> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alforse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 连接 AI 助手（MCP）

> 通过在浏览器中授权或使用 API 密钥，将 Claude、ChatGPT、Cursor、VS Code 或任何其他 MCP 客户端连接到您的 Alforse 公司。

Alforse 运行着一个 Model Context Protocol（MCP）服务器，因此 AI 助手可以查询并处理您的 ERP 数据：物料、销售、采购、生产、库存、质量、会计等。公司里的任何人都可以连接自己的助手，开发者还可以连接编码客户端和脚本。助手只能做它所代表的人员或密钥被允许做的事。

## 您需要什么

| | 值 |
| - | - |
| 服务器 URL | `https://app.alforse.com/api/mcp` |
| 传输方式 | Streamable HTTP（仅 `POST`） |
| 套餐 | **商业版**（Business）。在其他套餐上，服务器会拒绝每一次调用（参见[限制](#limits)）。 |
| 服务器清单 | `https://app.alforse.com/.well-known/mcp.json`（公开，不含公司数据） |

让助手登录有两种方式。请选择您的客户端支持的那一种。

| 客户端 | 连接方式 |
| - | - |
| Claude.ai、Claude Desktop、ChatGPT | **浏览器授权（OAuth）。** 无需创建或粘贴密钥。 |
| Claude Code | 两种皆可。不带密钥时，它会在首次使用时启动浏览器授权；也可以传入 API 密钥。 |
| Cursor、VS Code、Codex、脚本和 CI | 在 `Authorization` 请求头中使用 **API 密钥** |
| 只能运行本地（stdio）服务器的客户端 | API 密钥，通过 `mcp-remote` |

## 通过浏览器授权连接

无需先在 Alforse 中做任何设置。您在助手中添加服务器 URL，Alforse 会请您批准这次连接。

**在助手中添加服务器。**

* \*\*Claude Desktop / Claude.ai：\*\***Settings → Connectors → Add custom connector**，然后粘贴 `https://app.alforse.com/api/mcp`。
* \*\*ChatGPT：\*\***Settings → Connectors → Add**，然后粘贴同一个 URL。ChatGPT 只在部分套餐中提供自定义连接器。
* **Claude Code：**`claude mcp add --transport http alforse https://app.alforse.com/api/mcp`（不带 `--header`）。

**登录 Alforse。** 助手会在浏览器中打开一个 Alforse 页面。如有提示，请登录。

**查看请求。** **授权应用程序**页面显示助手的名称和它将返回的网站，后面是“is requesting access to your Alforse account.”（正在请求访问您的 Alforse 账户。）下方是所请求的**范围**（`mcp:tools`）。

**选择公司。** 在**公司**下，选择助手应在其中工作的公司。如果您只属于一家公司，则直接显示，无需选择。一个连接只在一家公司内工作；要在另一家公司工作，请重新连接并选择那家公司。

**选择“授权”。** 浏览器会返回您的助手，它现在已连接。问它一个简单的问题来检查，例如“列出我最近的五张销售订单”。

NOTE

**谁可以授权**

**授权应用程序**页面需要您在当前公司中拥有**设置**的**更新**权限。没有该权限，您会被送回应用并看到“Access Denied”（访问被拒绝）。请管理员授予该权限，或使用管理员为您创建的 [API 密钥](https://docs.alforse.com/zh/docs/building/api-keys.md)。

### 连接能做什么

* 它**以您的身份、在您选择的公司中**操作，权限恰好是您当前的[权限](https://docs.alforse.com/zh/docs/reference/permissions.md)。如果您的权限发生变化，助手的权限随之变化。
* 一旦您不再是该公司的启用成员，它就会停止工作。
* 公司和用户始终来自连接本身。助手无法通过传入不同的参数来切换公司或冒充他人。

### 登录在幕后如何运作

客户端会自动处理这些；此处的细节供自行开发客户端的开发者参考。

| 步骤 | 端点 |
| - | - |
| 不带令牌的调用会得到 `401` 响应以及 `WWW-Authenticate: Bearer resource_metadata="https://app.alforse.com/.well-known/oauth-protected-resource"` | `/api/mcp` |
| 受保护资源元数据 | `https://app.alforse.com/.well-known/oauth-protected-resource` |
| 授权服务器元数据 | `https://app.alforse.com/.well-known/oauth-authorization-server` |
| 客户端注册（开放的动态注册，JSON 请求体含 `client_name` 和 `redirect_uris`） | `https://app.alforse.com/register` |
| 批准页面 | `https://app.alforse.com/authorize` |
| 令牌交换与刷新 | `https://app.alforse.com/token` |

* 授权类型：`authorization_code` 和 `refresh_token`。响应类型：`code`。
* 使用 `S256` 的 PKCE。公共客户端（令牌端点认证方式为 `none`）必须发送 code challenge。
* 令牌端点的客户端认证：`client_secret_post` 或 `none`。
* 范围：`mcp:tools`。
* 授权码有效期为 10 分钟，且只能使用一次。访问令牌有效期为一小时（`expires_in: 3600`）；客户端用其刷新令牌续期。

## 使用 API 密钥连接

对于无法打开浏览器登录的客户端以及脚本，请使用密钥。管理员在**设置 → API密钥**下创建它；密钥有自己的权限范围，并且属于一家公司。创建和限定密钥的方法请参阅 [API 密钥](https://docs.alforse.com/zh/docs/building/api-keys.md)。

把密钥放在 `Authorization` 请求头中发送：

```http theme={null}
Authorization: Bearer alf_your_key_here
```

也接受 `alforse-key: alf_your_key_here` 请求头。

TIP

**命令已为您备好**

创建密钥时，其对话框会在密钥旁显示一条 **MCP 命令**。复制它，即可一步将服务器添加到 Claude Code。

### 客户端配置

**Claude Code**

```bash theme={null}
claude mcp add --transport http alforse \
  https://app.alforse.com/api/mcp \
  --header "Authorization: Bearer alf_your_key_here"
```

**Cursor**（项目中的 `.cursor/mcp.json`，或合并到您现有的 `mcpServers`）

```json theme={null}
{
  "mcpServers": {
    "alforse": {
      "url": "https://app.alforse.com/api/mcp",
      "headers": { "Authorization": "Bearer alf_your_key_here" }
    }
  }
}
```

**VS Code**（`.vscode/mcp.json`；VS Code 会向您索要密钥，因此不会保存在文件中）

```json theme={null}
{
  "inputs": [
    { "id": "alforse-key", "type": "promptString", "description": "Alforse API key", "password": true }
  ],
  "servers": {
    "alforse": {
      "type": "http",
      "url": "https://app.alforse.com/api/mcp",
      "headers": { "Authorization": "Bearer ${input:alforse-key}" }
    }
  }
}
```

**任何其他客户端：**向它提供 URL `https://app.alforse.com/api/mcp` 和 `Authorization: Bearer …` 请求头。URL 字段的名称因客户端而异（例如 `url` 或 `serverUrl`）；请查阅您的客户端文档。

HEADS UP

**每个客户端一个密钥**

为每个助手或脚本使用单独的密钥，且只授予它所需的范围（只读助手仅授予查看范围）。这样您就可以撤销或收窄其中一个，而不影响其他的。

## 助手看到的工具

服务器没有为每个操作提供一个工具，而是提供三个可以触达所有操作的工具：

| 工具 | 作用 |
| - | - |
| `search_tools` | 按关键词、模块或风险等级（`READ`、`WRITE`、`DESTRUCTIVE`）搜索可用的 Alforse 操作。默认返回 20 条结果，最多 100 条。 |
| `describe_tool` | 返回一个或多个操作的完整契约：说明、所需权限、输入与响应模式。 |
| `call_tool` | 使用 JSON 对象形式的参数运行某个操作。 |

这些操作来自以下领域：账户、会计、文档、库存、开票、物料、人员、生产、采购、质量、资源、销售、设置、共享和用户。只有 Alforse 明确发布的操作才可用；有些被有意排除在服务器之外。

* 每次调用都经过与应用相同的权限检查，写入由同一服务层校验。
* 每个操作都带有风险等级，因此您的助手可以在运行 `WRITE` 或 `DESTRUCTIVE` 操作之前先询问您。
* 列表读取默认返回 **25 行**。助手通过 `limit`（1–100）和 `offset` 翻页。
* 助手会获知贵公司时区下的今天日期，因此“上周”这类相对日期能被正确解析。

## 限制

| 限制 | 值 |
| - | - |
| 套餐 | 商业版。否则每次调用都返回 `402`。 |
| 浏览器授权的连接 | **每位用户每分钟 60 次请求**，由您的所有连接共享 |
| API 密钥 | 密钥自身的限制，默认为每分钟 60 次请求（[详情](https://docs.alforse.com/zh/docs/building/api-keys.md#rate-limit)） |
| 访问令牌有效期 | 1 小时，用刷新令牌自动续期 |
| 每次列表读取的行数 | 默认 25，每页最多 100 |

达到限制时，服务器会以 `429` 响应，并附带 `Retry-After` 以及 `X-RateLimit-Limit`、`X-RateLimit-Remaining` 和 `X-RateLimit-Reset` 请求头。请等待 `Retry-After` 指定的秒数，然后重试。

## 故障排除

| 现象 | 原因 | 解决办法 |
| - | - | - |
| `402`，附带“The MCP server is available on the Business plan. Upgrade to connect an agent to Alforse.”（MCP 服务器在 Business 套餐中提供。升级后即可将智能体连接到 Alforse。） | 公司不在商业版套餐上。 | 升级套餐（参见[账单与订阅](https://docs.alforse.com/zh/docs/reference/billing.md)）。连接本身无需更改。 |
| 助手打开 Alforse 后立即出现“Access Denied”（访问被拒绝） | 您缺少**设置**的**更新**权限，而批准页面需要它。 | 请管理员授予该权限，或改用 API 密钥连接。 |
| 选择**授权**时出现“Invalid company”（公司无效）（`403`） | 您不是所选公司的成员。 | 选择您所属的公司。 |
| “Invalid redirect URI”（重定向 URI 无效）或“Invalid client”（客户端无效） | 客户端发送了未注册的返回地址，或其注册信息未知。 | 从助手中移除该服务器并重新添加，使其重新注册。 |
| “PKCE required for public clients”（公共客户端需要 PKCE） | 没有密钥的客户端未发送 code challenge。 | 使用支持 PKCE（`S256`）的客户端。 |
| 之前能用，现在每次调用都返回 `401` | 访问令牌已过期且无法续期，您不再是该公司的启用成员，或 API 密钥已过期或被删除。 | 重新连接（再次授权），或使用有效的密钥。 |
| `429`“Rate limit exceeded”（超出速率限制） | 每分钟请求数超过允许值。 | 等待 `Retry-After`；让助手获取更少、更大的页面。 |
| `405`“Method not allowed. Use POST.”（不允许该方法，请使用 POST。） | 该 URL 是在浏览器中打开的，或用 `GET` 调用。 | 属正常现象：MCP 客户端使用 `POST`。请改为在助手中添加该 URL。 |
| 工具调用因权限错误而失败 | 所连接的用户或密钥的范围不允许该操作。 | 在 Alforse 中授予相应权限或范围；下一次调用起生效。 |
| 助手找不到某个操作 | 它没有发布到 MCP 服务器，或搜索词不匹配。 | 让助手按模块（例如“sales”）或字段名搜索。 |

## 相关内容

**API 密钥**

为编码客户端、脚本和 CI 创建并限定密钥。

[Open](https://docs.alforse.com/zh/docs/building/api-keys.md)

**权限**

已连接的助手被允许读取和更改的内容。

[Open](https://docs.alforse.com/zh/docs/reference/permissions.md)

**Slack 中的助手**

在 Slack 中使用 Alforse。

[Open](https://docs.alforse.com/zh/docs/integrations/assistant.md)

**账单与订阅**

您的套餐以及如何升级。

[Open](https://docs.alforse.com/zh/docs/reference/billing.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.