MCP——将外部AI智能体连接到Omniscol

智能体能做什么

MCP智能体非常适合处理数据就在Omniscol中的查询类问题：

• “请给出本周各教室相对于开放时间的占用率。”
• “帮我找一间教室，10月的三个周一在同一个2小时时段都有空。”
• “张伟老师本学年已经上了多少小时的课？”
• “今天所有的数学课有哪些？”
• “列出本学期完成服务时间不足70%的教师。”

这类请求通常需要组合多个工具：课表、统计仪表盘、计算得出的可用时间、教师详情。智能体负责编排这些调用，并用自然语言给出答复。

开放的工具

MCP服务器根据允许用于MCP的Omniscol API路由生成工具。被明确忽略的路由，以及某些技术性模块（例如与用户身份验证相关的模块），不会成为工具。因此工具列表反映的是向MCP开放的API，而不是应用程序的全部内部接口，不过它已经覆盖了很大一部分。此外，还有一些路由专为MCP设计，Omniscol本身并不使用。例如高级搜索工具：让Omniscol能根据自由文本所指的实体（“张伟老师”“6年级1班”）找到其技术标识，再用这个标识精确查询数据。又如一些在Omniscol中没有图形界面的复杂工具，因为它们更适合用提示词来完成，比如查询实体的占用和可用情况（“帮我找一间教室，下午连续三个周一都有2小时空闲”“10月14日那一周有数学教师可以上3小时课吗？”）。

这些工具主要涵盖：

• **管理**模块（用户、科目、学年、设置），
• **课表管理**模块（配置、校区、教室、班级、课程），
• **课表**模块（日程表、仪表盘、搜索），
• **缺勤管理**模块（登记、统计），
• 全局搜索。

读取类路由最适合智能体使用。目录中也可能存在一些写入操作，取决于令牌的权限和可用的API，但必须严加管控：凡是会修改多个业务对象的请求，都应由用户核实后再视为可靠。

启用MCP服务器

MCP服务器适用于**Premium账户。一切从 MCP界面开始：在管理模块中点击配置即可打开。界面会显示服务器URL**，并提供可直接复制的客户端配置内容。

**MCP的标准认证方式是OAuth2。**兼容的客户端（如Claude）只需连接到服务器URL，即可发现该账户的OAuth2配置，用户在授权页面批准访问即可：除了URL之外无需提供任何其他内容。授予的权限范围遵循账户的权限及其可见性限制。Omniscol的OAuth2服务器、客户端管理界面和授权的详细说明，请参见OAuth2 / OIDC（提供方）。

对于不支持OAuth2的客户端，同一界面可以生成令牌（API密钥，可选全局范围或限定某个模块，设置有效期，可选关联用户，可勾选写入权限），并根据需要提供可直接粘贴的格式：Authorization: Bearer 请求头、Claude Desktop（免费版）的配置块，以及本地代理命令。该令牌基于Omniscol API中介绍的密钥体系。

安全最佳实践

• OAuth2认证——更方便，智能体支持时应优先使用（Claude付费版）。
• AI专用令牌——创建令牌时使用一目了然的名称（AI智能体——Claude桌面版），需要时可随时撤销。
• 最小权限范围——使用API令牌时，只选择必要的API接口；使用OAuth令牌时，按实际需要限制权限范围（scope）。
• 活动日志——当相关路由会记录日志时，调用会出现在与该令牌关联的日志中。日志只记录调用本身，不保存返回数据的详情，也不保存可重放的请求内容。
• 可见性限制——智能体只能看到Omniscol返回给它的内容。如果您为令牌所属角色配置了严格的可见性限制，这些限制同样适用。