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

# TokenLab MCP Server

> 将 MCP 客户端连接到 TokenLab 模型发现、定价、OpenAI 兼容聊天和原生推理端点。

[TokenLab MCP server](https://github.com/hedging8563/tokenlab-mcp-server) 为兼容 MCP 的智能体提供实时模型发现、定价、OpenAI 兼容 Chat Completions 和原生推理工具。

当智能体需要比较模型、检查支持的请求格式、查看定价，或通过 OpenAI Chat Completions、Responses、Anthropic Messages、Gemini generateContent 调用 TokenLab 时，请使用此服务器。

<Note>
  公共目录工具不需要 TokenLab API key。设置 `TOKENLAB_API_KEY` 后可使用四个付费推理工具。
</Note>

## 它提供了什么

* 从 `https://api.tokenlab.sh/v1/models` 进行实时模型发现。
* 从 `/v1/models/{model}` 获取模型详情。
* 从 `/v1/models/{model}/pricing` 获取定价信息。
* 从 `https://api.tokenlab.sh/llms.txt` 获取智能体可读的 API 概览。
* 针对 OpenAI 兼容聊天、Responses、Anthropic Messages、Gemini、媒体、音频、嵌入 (embeddings)、重排序 (rerank) 和翻译的端点系列指南。
* 通过 OpenAI 兼容 Chat Completions、Responses、Anthropic Messages 和 Gemini generateContent 进行可选推理。

## 从 GitHub 安装

克隆公共仓库并安装依赖项：

```bash theme={null}
git clone https://github.com/hedging8563/tokenlab-mcp-server.git
cd tokenlab-mcp-server
npm install
npm test
```

通过 stdio 启动服务器：

```bash theme={null}
npm start
```

可选的 `TOKENLAB_API_BASE` 环境变量默认为 `https://api.tokenlab.sh`。

## 在 Codex 中安装

将公共目录服务器添加到 Codex 配置：

```bash theme={null}
codex mcp add tokenlab-model-catalog -- npx -y @tokenlabai/mcp-server
```

添加后新开一个 Codex 会话。公共目录工具不需要 `TOKENLAB_API_KEY`。

如需启用推理工具，请在添加服务器时传入 TokenLab API key：

```bash theme={null}
codex mcp add --env TOKENLAB_API_KEY=your-tokenlab-api-key tokenlab-model-catalog -- npx -y @tokenlabai/mcp-server
```

## 在 Cline 中安装

使用 Cline CLI 安装已发布的 stdio 服务器：

```bash theme={null}
cline mcp add tokenlab --yes -- npx -y @tokenlabai/mcp-server
```

该命令已通过 Cline CLI 验证，可在没有安装警告的情况下完成。公共目录工具可直接使用；需要推理工具时，请在 Cline 环境中设置 `TOKENLAB_API_KEY`。

## Claude Desktop 配置

将已发布的 npm package 添加到 MCP 客户端配置：

```json theme={null}
{
  "mcpServers": {
    "tokenlab-model-catalog": {
      "command": "npx",
      "args": ["-y", "@tokenlabai/mcp-server"]
    }
  }
}
```

保存配置后重启 MCP 客户端。

## Cursor、Windsurf 及其他 MCP 客户端

在任何支持 stdio MCP 服务器的客户端中使用相同的命令和参数：

```json theme={null}
{
  "command": "npx",
  "args": ["-y", "@tokenlabai/mcp-server"],
  "env": {
    "TOKENLAB_API_BASE": "https://api.tokenlab.sh"
  }
}
```

如果您的客户端存储了命名服务器，请使用 `tokenlab-model-catalog` 作为服务器名称。

## 工具

| 工具                         | 用途                                                                                                     |
| -------------------------- | ------------------------------------------------------------------------------------------------------ |
| `list_models`              | 列出公共 TokenLab 模型。可选择使用 `recommended_for` 进行过滤，例如 `image`、`video`、`embedding`、`rerank` 或 `translation`。 |
| `get_model`                | 获取单个模型的公共详情和支持的请求格式。                                                                                   |
| `get_model_pricing`        | 获取单个模型的公共定价详情。                                                                                         |
| `compare_models`           | 比较多个模型 ID 的详情和定价。                                                                                      |
| `create_chat_completion`   | 调用 OpenAI 兼容的 `/v1/chat/completions` 端点，支持多模态消息和工具调用。需要 `TOKENLAB_API_KEY`。                            |
| `create_response`          | 使用字符串或结构化 input、tools、tool choice、metadata 和 text 配置调用 `/v1/responses`。需要 `TOKENLAB_API_KEY`。          |
| `create_anthropic_message` | 使用原生多消息 content blocks 和 tools 调用 `/v1/messages`。需要 `TOKENLAB_API_KEY`。                                |
| `create_gemini_content`    | 使用 contents、多模态 parts、tools 和 generation config 调用原生 `generateContent`。需要 `TOKENLAB_API_KEY`。          |
| `get_api_overview`         | 获取 TokenLab 的 `llms.txt` 概览，用于智能体可读的端点指南。                                                              |

推理工具返回普通 JSON 结果。MCP 工具调用会有意禁用流式输出。

## 推荐的智能体工作流程

1. 当用户未指定模型时，调用 `list_models`。
2. 对于非聊天任务（如图像、视频、音乐、3D、TTS、STT、嵌入、重排序或翻译），使用 `recommended_for`。
3. 在构建非聊天请求、重试失败请求或切换端点系列之前，调用 `get_model`。
4. 当模型成本影响用户选择时，调用 `get_model_pricing`。
5. 当选择取决于多个候选模型时，使用 `compare_models`。
6. 调用与所需 API 契约匹配的推理工具，或使用 `get_api_overview` 获取 TokenLab API 系列的简明映射。

## 原生端点指南

TokenLab 支持 OpenAI 兼容路由和原生端点系列。MCP 服务器可帮助智能体在编写代码前选择正确的路由：

| 系列                 | 常用路由                                                                     |
| ------------------ | ------------------------------------------------------------------------ |
| OpenAI 兼容聊天        | `/v1/chat/completions`                                                   |
| Responses          | `/v1/responses`                                                          |
| Anthropic Messages | `/v1/messages`                                                           |
| Gemini 原生          | `/v1beta/models/{model}:generateContent`                                 |
| 图像                 | `/v1/images/generations`, `/v1/images/edits`                             |
| 视频                 | `/v1/videos/generations`                                                 |
| 音乐                 | `/v1/music/generations`                                                  |
| 3D                 | `/v1/3d/generations`                                                     |
| 音频                 | `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/audio/translations` |
| 嵌入和重排序             | `/v1/embeddings`, `/v1/rerank`                                           |
| 文本翻译               | `/v1/translations`                                                       |

## 托管模型浏览器

支持 Streamable HTTP 的客户端可以连接：

```text theme={null}
https://tokenlab-model-explorer.vercel.app/mcp
```

该托管浏览器公开提供 `open_tokenlab_model_explorer`、`compare_tokenlab_models` 和 `generate_tokenlab_endpoint_example`。需要全部九个工具或带凭证的推理时，请使用上面的本地 npm 服务器。

## 与 TokenLab Skills 配合使用

MCP 服务器在运行时非常有用，而 [TokenLab skills repository](https://github.com/hedging8563/tokenlab-skills) 则教导编码智能体如何生成和修复集成代码。

在可用时同时使用它们：

* MCP server：发现当前模型、定价和端点详情。
* `tokenlab-api-integration` skill：生成可运行的 API 示例并处理结构化的 TokenLab 错误。
* `tokenlab-model-picker` skill：为用户的任务选择强大的模型。
* `tokenlab-native-endpoints` skill：决定何时使用 Responses、Anthropic Messages、Gemini、媒体、音频、嵌入、重排序或翻译路由。

## 故障排除

<AccordionGroup>
  <Accordion title="客户端无法启动服务器">
    确认 Node.js 至少为 18.17，然后在终端运行一次 `npx -y @tokenlabai/mcp-server`，以查看 npm 或网络错误。
  </Accordion>

  <Accordion title="模型列表为空">
    验证机器是否可以访问 `https://api.tokenlab.sh/v1/models`。如果您覆盖了 `TOKENLAB_API_BASE`，请确保其末尾不包含斜杠。
  </Accordion>

  <Accordion title="智能体仍然选择过时的模型 ID">
    要求智能体在硬编码模型名称之前调用 `list_models` 或 `get_model`。将 MCP 服务器与 `tokenlab-model-picker` 配合使用效果更佳。
  </Accordion>

  <Accordion title="此服务器可以调用付费的 TokenLab 推理 API 吗？">
    可以。设置 `TOKENLAB_API_KEY` 后，可使用 `create_chat_completion`、`create_response`、`create_anthropic_message` 或 `create_gemini_content`。目录和定价工具无需 key 仍可使用。
  </Accordion>
</AccordionGroup>

## 资源

<CardGroup cols={2}>
  <Card title="GitHub 仓库" icon="github" href="https://github.com/hedging8563/tokenlab-mcp-server">
    源代码和本地设置说明
  </Card>

  <Card title="TokenLab Skills" icon="sparkles" href="https://github.com/hedging8563/tokenlab-skills">
    维护用于 TokenLab 集成的智能体技能
  </Card>

  <Card title="模型目录 API" icon="list" href="https://api.tokenlab.sh/v1/models">
    公共模型发现端点
  </Card>

  <Card title="llms.txt" icon="file-lines" href="https://api.tokenlab.sh/llms.txt">
    智能体可读的 TokenLab API 概览
  </Card>

  <Card title="Glama MCP Server" icon="globe" href="https://glama.ai/mcp/servers/hedging8563/tokenlab-mcp-server">
    查看已验证的 TokenLab MCP Server 条目
  </Card>

  <Card title="Glama 模型浏览器" icon="search" href="https://glama.ai/mcp/servers/hedging8563/tokenlab-openai-apps-model-explorer">
    浏览模型、定价和原生端点示例
  </Card>

  <Card title="MCP.so 条目" icon="compass" href="https://mcp.so/servers/tokenlab-mcp-server">
    在 AI & Agents 目录中发现 TokenLab
  </Card>

  <Card title="托管模型浏览器" icon="rocket" href="https://tokenlab-model-explorer.vercel.app">
    打开公共模型浏览器和远程 MCP 端点
  </Card>
</CardGroup>