实例

MCP CAN 实例是指一个运行中的 MCP（Model Context Protocol）服务单元。每个实例都是一个独立的、可访问的 MCP 服务端点，为 AI 应用（如扣子、Cursor、Windsurf、Dify、Kymo 等）提供标准化的上下文和工具能力。

什么是实例？

实例是 MCP CAN 平台的核心概念，它将您的业务逻辑、数据接口或工具封装为符合 MCP 协议的服务。通过创建实例，您可以：

快速部署 - 从模板、代码包或 OpenAPI 规范一键创建 MCP 服务
统一管理 - 在单一平台上管理所有 MCP 服务的生命周期
安全访问 - 通过令牌和访问配置控制服务的使用权限
实时监控 - 查看服务运行状态、请求日志和性能指标
弹性伸缩 - 根据负载自动或手动调整实例规模

无论您是开发者、企业用户还是 AI 应用集成商，实例都是连接您的数据和 AI 能力的桥梁。

核心功能

📈 仪表数据 - 统计查看你的实时数据，以方便你的管理
🚀 实例管理 - 实例生命周期、扩缩容与集群管理
📈 监控日志 - 实时监控、日志聚合与告警通知
🔐 安全认证 - 身份认证、权限控制与操作审计
⚡ 一键使用 - 一键获取外网访问地址以供 AI 使用或调试

实例管理

创建实例

我们为实例创建提供了丰富的类型组合来添加不同应用场景下的 MCP 服务; 支持自定义、模板、OpenAPI 转 MCP等多找模式创建一个 MCP 服务。

菜单栏创建添加

实例管理页创建添加

模板中创建添加

访问配置

访问配置提供了将 MCP 实例接入到各类 AI 客户端所需的标准化配置信息。通过访问配置，您可以快速获取符合 MCP 协议的连接参数。

配置管理

在实例详情页的"访问配置"标签中，您可以：

查看配置列表 - 展示所有已创建的访问令牌及其状态
添加令牌 - 点击"+ 添加令牌"按钮创建新的访问凭证
编辑令牌 - 修改令牌的标签、有效期等属性
删除令牌 - 移除不再使用的访问凭证
查看访问日志 - 追踪令牌的使用记录

配置格式

访问配置以标准的 JSON 格式提供，包含 MCP 服务的完整连接信息：

json

{
  "mcpServers": {
    "mcp-fc57f995": {
      "url": "https://your-visit.com/url",
      "headers": {
        "Authorization": "Basic your Authorization"
      }
    }
  }
}

配置字段说明：

mcpServers - MCP 服务器配置根对象
- mcp-fc57f995 - 服务实例的唯一标识符
  - url - MCP 服务的访问端点地址
  - headers - 请求头配置
    - Authorization - 身份验证信息（Bearer 或 Basic 认证）

如何使用

复制配置 - 点击右上角的复制图标，将完整的 JSON 配置复制到剪贴板
粘贴到客户端 - 将配置粘贴到您使用的 AI 客户端的 MCP 配置文件中
重启客户端 - 重启 AI 客户端使配置生效
验证连接 - 在客户端中确认 MCP 服务已成功连接

提示

每个访问令牌都有独立的有效期，可在令牌列表中查看"永久有效"或具体过期时间
建议为不同的使用场景（开发、测试、生产）创建不同的访问令牌
定期轮换令牌以提高安全性

安全令牌

安全令牌是访问 MCP 服务的身份凭证，用于对客户端请求进行身份验证和授权。MCP CAN 支持多种认证方式，以满足不同的安全需求和使用场景。

令牌类型

MCP CAN 支持以下四种 API 认证方式：

1. Bearer Token

可随机生成令牌或自定义填写令牌。适用于需要灵活管理访问凭证的场景。

自动生成：系统随机生成一个安全的令牌字符串
自定义令牌：可以输入自己的令牌值或自定义填写令牌
使用方式：在 HTTP 请求头中添加 Authorization: Bearer <token>

2. Api-Key

可随机生成令牌或可以自定义填写令牌。这是一种常见的 API 认证方式，令牌直接作为 API 密钥使用。

自动生成：系统随机生成 API Key
自定义填写：可以输入自己的 API Key 值
使用方式：在 HTTP 请求头中添加 Api-Key: <your-api-key>

3. X-API-Key

可随机生成令牌也可自定义填写令牌。适用于需要自定义请求头名称的场景。

自动生成：系统随机生成密钥
自定义填写：可以输入自己的密钥值
使用方式：在 HTTP 请求头中添加 X-API-Key: <your-key>

4. Basic Authentication

使用 username:password 需要填写用户名和密码。这是标准的 HTTP 基本认证方式。

用户名：输入认证用户名
密码：输入认证密码
编码方式：系统自动将 username:password 进行 Base64 编码
自定义：可根据自定义的编码规则输入
使用方式：在 HTTP 请求头中添加 Authorization: Basic <base64-encoded-credentials>

创建令牌

在"访问配置"页面点击"+ 添加令牌"按钮，按照以下步骤创建新令牌：

设置有效期（可选）：
- 选择令牌的过期时间
- 或选择"永久有效"（不推荐用于生产环境）
选择认证类型：从下拉菜单中选择适合您场景的认证方式（Bearer、Api-Key、X-API-Key 或 Basic）
配置认证信息：
- Bearer/Api-Key/X-API-Key：可选择"随机生成"或手动输入 token 值
- Basic：填写用户名（username）和密码（password）
添加 HTTP 请求头（可选）：
- 启用"透传"开关：即将 header 内容透传至下游服务
- 添加自定义请求头键值对
- 支持添加多个请求头
添加标签（可选）：
- 输入标签名称便于识别和管理
- 例如：dev-token、production、test-env 等
实时配置查看"：修改数据令牌配置将在右侧生成访问配置 JSON

令牌管理

创建令牌后，您可以在令牌列表中进行以下操作：

查看令牌信息：显示令牌类型、有效期、创建时间等
编辑令牌：修改令牌的标签、有效期或其他配置
查看访问日志：查看该令牌的使用记录和访问统计
删除令牌：撤销令牌的访问权限（已删除的令牌立即失效）

安全最佳实践

安全建议

避免硬编码：不要将令牌直接写入代码，使用环境变量或配置文件
最小权限原则：为不同的使用场景创建独立令牌，限制访问范围
定期轮换：定期更新令牌，尤其是生产环境的长期令牌
设置有效期：尽量为令牌设置合理的过期时间，避免使用永久令牌
监控使用：定期查看访问日志，发现异常访问及时撤销令牌
安全存储：使用密钥管理服务（如 AWS Secrets Manager、Azure Key Vault）存储敏感令牌

使用示例

Bearer Token 示例：

bash

curl -X POST https://mcp-dev.itqm.com/mcp-gateway/your-instance-id/mcp \
  -H "Authorization: Bearer your-token-here" \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/list"}'

Basic Authentication 示例：

bash

curl -X POST https://mcp-dev.itqm.com/mcp-gateway/your-instance-id/mcp \
  -H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/list"}'

Api-Key 示例：

bash

curl -X POST https://mcp-dev.itqm.com/mcp-gateway/your-instance-id/mcp \
  -H "Api-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/list"}'

状态探测

状态探测是对 MCP 实例进行健康检查的重要功能，用于实时监控服务的可用性和连接状态。通过状态探测，您可以快速识别服务故障，确保 MCP 服务始终处于可用状态。

探测内容

MCP CAN 会对每个实例执行多维度的状态检测，确保服务的各个组件正常运行：

1. 容器状态

检测实例容器的运行状态，确保服务进程正常启动。

状态指示：
- 🟢 已就绪 - 容器正常运行，服务已启动
- 🔴 未就绪 - 容器启动失败或服务异常
检测内容：容器健康检查、进程存活状态

2. 容器 svc 状态

检测 Kubernetes Service（svc）的连通性，确保网络层面的可达性。

状态指示：
- 🟢 已就绪 - Service 正常，网络可达
- 🔴 未就绪 - Service 异常，无法建立连接
检测内容：Service 端点可用性、负载均衡状态

3. 服务状态

检测 MCP 服务本身的运行状态和响应能力。

状态指示：
- 🟢 已就绪 - MCP 服务正常响应
- 🔴 未就绪 - 服务无响应或返回错误
检测内容：服务端口监听、协议握手、基础响应能力

4. 错误信息

当探测失败时，显示详细的错误诊断信息，帮助快速定位问题。

常见错误：
- 连接超时 - 网络不可达或服务响应慢
- 端口未监听 - 服务进程未启动或端口配置错误
- 认证失败 - 令牌无效或权限不足
- 协议错误 - MCP 协议握手失败

自动探测

除了手动触发探测，MCP CAN 还提供自动健康检查机制：

定期探测：系统每隔一定时间（如 30 秒）自动执行健康检查
状态更新：实例列表中的状态指示器会实时反映最新的健康状态
告警通知：当检测到服务异常时，系统会触发告警（需配置告警规则）

故障排查

当状态探测显示异常时，可以按以下步骤排查：

检查容器状态：
- 查看实例日志，确认服务是否正常启动
- 检查资源配置（CPU、内存）是否充足
检查网络连接：
- 确认 Service 配置正确，端口映射无误
- 检查网络策略（Network Policy）是否阻止了访问
验证认证配置：
- 确认令牌有效且未过期
- 检查认证方式是否与实例配置匹配
查看监控日志：
- 切换到"监控日志"标签，查看详细的运行日志
- 搜索错误关键字，定位具体问题

提示

状态探测结果会缓存一段时间，如需获取最新状态请点击"刷新"按钮
建议在实例变更（如重启、更新配置）后主动执行状态探测，确保服务正常
可以结合监控日志功能，深入分析探测失败的根本原因

监控日志

监控日志是实例运行状态和请求追踪的核心功能，提供实时日志查看、错误追踪和问题诊断能力。通过监控日志，您可以快速定位服务异常、分析性能瓶颈、追溯用户请求。

MCP CAN 提供两类日志视图：容器日志和访问日志，分别用于查看应用运行日志和 API 请求记录。

容器日志

容器日志记录了 MCP 实例运行时的所有标准输出（stdout）和标准错误（stderr）信息，包括应用启动、配置加载、错误堆栈等底层运行日志。

日志内容

容器日志包含以下关键信息：

时间戳：日志产生的精确时间（格式：[I 2025-11-20 12:00:03.686.686]）
日志级别：INFO、WARN、ERROR 等级别标识
模块路径：产生日志的代码模块（如 mcp_server.streamable_http_manager）
日志内容：详细的运行信息、错误消息或状态更新

常见日志类型：

[INFO] StreamableHTTP session manager started
[INFO] MCP SSE Protocol [everything] added successfully, SSE access URL: http://0.0.0.0:8080/sse
[INFO] MCP STEAMABLE_HTTP Protocol [everything] added successfully, HTTP access URL: http://0.0.0.0:8080/mcp
[INFO] Serving incoming MCP requests on 0.0.0.0:8080
[INFO] Started server process [22]
[INFO] Waiting for application startup.
[INFO] Application startup complete.
[INFO] Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)
[INFO] 10.42.0.6:34656 - "POST /mcp HTTP/1.1" 307 Temporary Redirect

使用场景

启动诊断：查看服务启动日志，确认配置加载和模块初始化是否正常
错误排查：定位异常堆栈信息，分析服务崩溃或响应错误的根本原因
性能分析：观察请求处理日志，识别慢查询或资源瓶颈
运行监控：实时查看服务健康状态和运行事件

操作功能

在容器日志视图中，您可以：

实时查看：日志内容自动滚动显示最新记录
刷新日志：点击"🔄 刷新"按钮手动刷新日志内容
下载日志：点击"⬇ 下载"按钮将日志导出为文本文件，便于离线分析
关闭日志：点击"✖ 关闭"按钮退出日志查看界面
日志滚动：支持鼠标滚轮或滚动条浏览历史日志

访问日志

访问日志（Trace 日志）记录了所有进入 MCP 实例的 API 请求和响应详情，包括请求参数、响应结果、执行耗时等关键信息，是追踪用户行为和诊断业务问题的重要工具。

日志内容

访问日志以结构化 JSON 格式展示，每条记录包含：

时间戳：请求发生的时间（如 2025/11/21 16:05:29）
日志级别：Info、Trace、Debug、Warn、Error
事件类型：request（请求）、response（响应）、sse_start（SSE 会话启动）
详细信息：JSON 格式的请求和响应数据

请求日志示例：

json

{
  "event": "request",
  "level": "info",
  "message": {
    "contentType": "application/json",
    "cookies": [],
    "form": [],
    "headers": {
      "Accept": "application/json, text/event-stream",
      "Accept-Encoding": "br, gzip, deflate"
    },
    "responseHeaders": {
      "Cache-Control": "no-store, no-cache, must-revalidate"
    }
  }
}

响应日志示例：

json

{
  "event": "response",
  "level": "info",
  "message": {
    "latency": 5012853814,
    "method": "GET",
    "path": "/mcp-gateway/0630c7e5-1661-4066-8cc0-a11b596e09c2d/mcp",
    "responseHeaders": {
      "Content-Length": "2696702"
    }
  }
}

过滤与搜索

访问日志提供强大的过滤和搜索功能，帮助快速定位目标日志：

日志级别过滤：
- 点击顶部标签按钮选择日志级别：全部 | Trace | Debug | Info | Warn | Error
- 快速筛选特定级别的日志记录
实例连接过滤：
- 在"实例连接"下拉菜单中选择特定实例
- 查看该实例的独立访问日志
时间范围过滤：
- 设置开始时间和结束时间
- 查询指定时间段内的日志记录
Token 过滤：
- 选择特定的访问令牌
- 追踪该令牌对应的所有请求
Trace ID 搜索：
- 输入 Trace ID 精确查找特定请求链路
- 用于分布式链路追踪和问题定位
刷新日志：
- 点击"🔄 刷新"按钮更新日志列表

使用场景

请求追踪：通过 Trace ID 追踪完整的请求链路，定位跨服务调用问题
性能分析：查看请求延迟（latency），识别慢接口和性能瓶颈
错误诊断：过滤 Error 级别日志，快速定位失败请求和异常原因
用户行为分析：根据 Token 过滤查看特定用户或客户端的访问记录
安全审计：追溯 API 访问历史，排查异常访问或越权行为

日志字段说明

字段	说明	示例
时间戳	请求发生的时间	`2025/11/21 16:05:29`
日志级别	Info、Trace、Debug、Warn、Error	`Info`
事件类型	request、response、sse_start 等	`request`
latency	请求处理耗时（纳秒）	`5012853814`（约 5 秒）
method	HTTP 方法	`GET`、`POST`
path	请求路径	`/mcp-gateway/.../mcp`
contentType	请求内容类型	`application/json`
headers	请求头信息	`{"Accept": "..."}`
responseHeaders	响应头信息	`{"Content-Length": "..."}`

日志管理最佳实践

提示

定期查看：建议每天查看一次 Error 级别日志，及时发现潜在问题
保留时长：访问日志默认保留 7 天，容器日志保留 3 天（可根据订阅计划调整）
下载归档：对于重要事件，建议下载日志并归档保存
结合监控：将日志分析与状态探测、告警监控结合使用，构建完整的可观测性体系
Trace ID 规范：在客户端请求中携带自定义 Trace ID，便于跨系统链路追踪

常见问题排查

问题 1：容器日志显示"暂无数据"

可能原因：服务刚启动，尚未产生日志
解决方法：稍等片刻或点击刷新按钮，或检查容器是否正常启动

问题 2：访问日志中看不到最新请求

可能原因：日志收集有延迟（通常 10-30 秒）
解决方法：点击刷新按钮，或调整时间范围为"最近 5 分钟"

问题 3：日志中出现大量 307 Temporary Redirect

可能原因：HTTP 请求被重定向到 HTTPS 或路径规范化
解决方法：检查客户端配置，确保使用正确的协议和路径

问题 4：日志显示"Application startup complete"但服务不可用

可能原因：服务启动成功但网络或认证配置有问题
解决方法：执行状态探测，检查容器 svc 状态和服务状态

实例 ​

什么是实例？ ​

核心功能 ​

实例管理 ​

创建实例 ​

访问配置 ​

配置管理 ​

配置格式 ​

如何使用 ​

安全令牌 ​

令牌类型 ​

1. Bearer Token ​

2. Api-Key ​

3. X-API-Key ​

4. Basic Authentication ​

创建令牌 ​

令牌管理 ​

安全最佳实践 ​

使用示例 ​

状态探测 ​

探测内容 ​

1. 容器状态 ​

2. 容器 svc 状态 ​

3. 服务状态 ​

4. 错误信息 ​

自动探测 ​

故障排查 ​

监控日志 ​

容器日志 ​

日志内容 ​

使用场景 ​

操作功能 ​

访问日志 ​

日志内容 ​

过滤与搜索 ​

使用场景 ​

日志字段说明 ​

日志管理最佳实践 ​

常见问题排查 ​

实例

什么是实例？

核心功能

实例管理

创建实例

访问配置

配置管理

配置格式

如何使用

安全令牌

令牌类型

1. Bearer Token

2. Api-Key

3. X-API-Key

4. Basic Authentication

创建令牌

令牌管理

安全最佳实践

使用示例

状态探测

探测内容

1. 容器状态

2. 容器 svc 状态

3. 服务状态

4. 错误信息

自动探测

故障排查

监控日志

容器日志

日志内容

使用场景

操作功能

访问日志

日志内容

过滤与搜索

使用场景

日志字段说明

日志管理最佳实践

常见问题排查