MCP 接入

下面的响应取自用真实 Claude Code 与 Codex 客户端做的验收。只有学校所在的 OneAI 开放了 API，服务才会应答。

端点与请求头

MCP 客户端向 $ONEAI_ORIGIN/mcp 发送 JSON-RPC。服务端不保存会话：每个请求自带 Bearer 令牌，回复是一条 text/event-stream 消息。令牌须是 mcp 受众：audience 为 mcp 的 PAT，或浏览器授权时 resource=$ONEAI_ORIGIN/mcp 换得的 OAuth 令牌。

curl -X POST "$ONEAI_ORIGIN/mcp" -H "Authorization: Bearer $ONEAI_TOKEN" \
  -H "Accept: application/json, text/event-stream" -H "Content-Type: application/json" -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

initialize 回复 "protocolVersion": "2025-11-25" 与 "serverInfo": { "name": "oneai", "version": "1.0.0" }。不带令牌时返回 401，并指向元数据：

WWW-Authenticate: Bearer resource_metadata="$ONEAI_ORIGIN/.well-known/oauth-protected-resource/mcp"

public-api 令牌打 /mcp 返回 403 external.audience.denied。

连接 Claude Code 或 Codex

CLI 按 profile 输出配置，其中不含凭据。以下是 oneai mcp config 的输出：

claude mcp add --transport http --scope user oneai $ONEAI_ORIGIN/mcp
# Then run /mcp inside Claude Code to sign in

# Managed by oneai CLI; remove with: oneai mcp uninstall --client codex
[mcp_servers.oneai]
url = "$ONEAI_ORIGIN/mcp"
tool_timeout_sec = 60
# Then run: codex mcp login oneai --scopes profile:read,problems:read,classes:read,grades:read,ingestions:read,papers:read

oneai mcp install --client claude|codex 先显示改动，加 --yes 才写入；Codex 配置会先备份，不会覆盖其他服务器。每个客户端各自走浏览器授权，CLI 不复制自己的凭据。

• Claude Code 用它公开的客户端元数据表明身份，在 /mcp 里登录。验收时批准后即显示已连接。
• Codex 0.163 用 codex mcp login oneai --scopes profile:read,problems:read,classes:read,grades:read,ingestions:read,papers:read 登录。不带 --scopes 时它会申请 OneAI 列出的全部 scope，授权页以 invalid_scope 拒绝。Codex 0.144 登录不了：它只支持动态客户端注册，OneAI 不提供。

浏览器登录只给客户端只读 scope，不含班级名单。读名单，以及收卷、开始解析这类写操作，走 CLI；CLI 的设备授权会把申请的每个 scope 都列给教师看。

工具随 scope 列出

tools/list 只列出授权能触达的工具。授权为 profile:read classes:read grades:read 时，返回list_classes、list_grade_sessions、get_grade_session、list_grade_answers、get_job 和 get_profile。

工具	需要
search_problems	problems:read
get_ingestion、list_ingestion_candidates	ingestions:read
list_class_members	roster:read；看姓名还要 students:pii
preview_grade_submission、submit_grade_sheets、cancel_job	grades:submit
prepare_student_accounts	students:manage

结果同时给 structuredContent 和同内容的 JSON 文本。以下摘自 tools/call 调 list_classes 的结果（班级名已打码）：

{ "structuredContent": { "items": [ { "id": "591d7b2e-fc7f-40d2-b7e1-f4b50d54dde4", "name": "…", "subject": "math",
  "stage": "senior", "studentCount": 2, "createdAt": "2026-10-22T09:16:22.505Z", "updatedAt": "2026-10-22T09:16:22.505Z" } ],
  "nextCursor": null } }

列出工具不代表能访问对象：每次调用都复核令牌、工作区、scope、身份与学校政策。业务失败返回 isError，文本是稳定的 reason，例如 public.not_found。写工具带 idempotencyKey 参数，生成一次，重试时原样带上。submit_grade_sheets 数秒内返回 jobId，用 get_job 查询进度。prepare_student_accounts 不改任何数据：它返回一条预选这些学生的班级页链接，由教师打开后开号、补发初始密码或重置密码，登录名和密码都不经过 MCP。

提示词

prompts/list 返回 review_grading_result（参数 sessionId），它逐题查看一场改卷的 AI 评分，列出教师应核对的地方。只有授权含 grades:read 时才会列出。check_ingestion_draft（参数 ingestionId）对一份解析出的试卷做同样的事，需要 ingestions:read。

改卷与解析 Skill

oneai skills install --client claude|codex 安装 oneai-grading，加 --skill ingest 安装 oneai-ingest。Skill 要求 agent 用 oneai 命令上传和写入、用 MCP 工具读取，任何计费操作前先等教师同意，也不改分、不发布题目。2026-10-28 验收时，教师的要求写在一条提示里。客户端经浏览器登录，只有只读 scope；上传、写入和班级名单用 CLI 的默认登录：

客户端	改卷	解析
Claude Code	用 oneai classes members list 读名单，预览后提交一份答卷，任务成功，一道题标为待复核	2025 年一份试卷，19 道草稿题，2 道 flagged
Codex 0.163	用 oneai classes members list 读名单，预览后提交一份答卷，任务成功	2025 年一份试卷，19 道草稿题：17 道 ready、2 道 flagged（2026-10-27，MCP 用个人访问令牌）

Codex 在 workspace-write 沙箱里执行命令，CLI 的配置目录会变成只读。用 sandbox_workspace_write.writable_roots 放行，否则命令会以 config.unwritable 停下（见「本地 CLI」）。

失败处理

被撤销的令牌返回 401 external.token.invalid。学校关闭外部客户端后，调用返回 403 external.school.disabled。请教师处理访问问题；重复调用没有用。