Uedu Agent API v1

Quick start

1. Create a token under “My Agent Token” below, and select the required scope.
2. Give the token to your Agent (via MCP configuration or HTTP header).
3. Give instructions in natural language, for example: “Copy my course 1234 to 115-1, and dry run it for me first.”

Every Agent call is recorded; configuration changes on the teacher side are also written to the channel settings audit, so you can see which token made the change.

My Agent Token

Token format uedu_agent_…; the database stores only a SHA-256 hash, and the full token is shown only once after creation. Each person can have up to 5 active tokens.

Authorized applications (OAuth)

When an OAuth-capable tool (Claude Code, Cursor, VS Code, etc.) connects for the first time, it will open a browser to the Uedu authorization page, so you do not need to copy a token. This lists the applications you have authorized, and you can revoke them at any time.

Set up MCP in your Agent

One MCP server provides both teacher-side and student-side tools; any scope not granted will return SCOPE_DENIED.

Method 1: HTTP + browser authorization (no installation, no token copying, recommended)

Claude Code

claude mcp add --transport http uedu-agent https://uedu.tw/mcp/agent
# Then enter /mcp in the conversation, choose uedu-agent to authenticate, and the browser will open the Uedu authorization page

Cursor / VS Code / Claude Desktop

{ "mcpServers": { "uedu-agent": { "url": "https://uedu.tw/mcp/agent" } } }

What happens on the first connection

1. The tool reads Uedu's discovery data and automatically registers itself at /oauth/register; you do not need to apply for any keys.
2. The browser opens the Uedu authorization page, lists the scope it requests, and prompts: “Is this a tool you started yourself?” If you are not signed in, it will first redirect to the login page.
3. After clicking “Allow authorization,” you are returned to the tool and shown as connected.
4. If you say “use whoami to check my identity” in the chat, it should return your account, auth_kind as oauth, and the authorized scope.

The access token lasts one hour and the refresh token lasts thirty days, and the tool will renew it automatically. This authorization will appear under “Authorized apps” above and can be revoked at any time; after revocation, the tool must be authorized again the next time it is used.

Troubleshooting

• If the authorization page shows an error, check error and error_description in the address bar. A common cause is that the callback URL sent by the tool is outside the allowed range (only https, local localhost, or a tool-defined scheme is accepted).
• If the tool returns SCOPE_DENIED: that scope was not selected during authorization; revoke and authorize again. Or that feature is available only to course owners and instructors, while TAs have read-only access.
• If the tool returns UNAUTHENTICATED: the token has been revoked or expired and the tool did not renew it; simply authenticate again.
• Claude Code can use /mcp to check connection status, re-authenticate, or remove it; removing the tool-side setting does not revoke the authorization on Uedu, so please revoke it under “Authorized apps.”

Method 2: HTTP + personal token (for tools or scheduled scripts that do not support OAuth)

Claude Code

claude mcp add --transport http uedu-agent https://uedu.tw/mcp/agent \
  --header "Authorization: Bearer uedu_agent_xxxxxxxx"

Cursor（~/.cursor/mcp.json）／ Claude Desktop

{
  "mcpServers": {
    "uedu-agent": {
      "url": "https://uedu.tw/mcp/agent",
      "headers": { "Authorization": "Bearer uedu_agent_xxxxxxxx" }
    }
  }
}

VS Code（.vscode/mcp.json）

{
  "servers": {
    "uedu-agent": {
      "type": "http",
      "url": "https://uedu.tw/mcp/agent",
      "headers": { "Authorization": "Bearer uedu_agent_xxxxxxxx" }
    }
  }
}

Codex CLI（~/.codex/config.toml）

[mcp_servers.uedu_agent]
url = "https://uedu.tw/mcp/agent"
http_headers = { Authorization = "Bearer uedu_agent_xxxxxxxx" }

Method 3: stdio (run on your own computer; local files can be uploaded)

pip install "mcp[cli]" httpx
curl -O https://uedu.tw/static/mcp/uedu_mcp_agent.py

# Claude Code
claude mcp add uedu-agent --env UEDU_AGENT_TOKEN=uedu_agent_xxxxxxxx \
  -- python /absolute/path/to/uedu_mcp_agent.py

The stdio mode includes an additional upload_knowledge_file tool, which can upload local PDF/DOCX/PPTX/TXT files directly to the knowledge base; in HTTP mode, use add_knowledge_text to send text.

Method 4: call the HTTP API directly (OpenClaw, custom scripts, scheduling)

curl -H "Authorization: Bearer uedu_agent_xxxxxxxx" \
  "https://uedu.tw/api/agent/v1/student/tasks?days=7"

What teachers can do

Base URL：https://uedu.tw/api/agent/v1。You can add ?dry_run=1 to write endpoints or set dry_run: true in the body.

What students can do

Typical usage: schedule the Agent to call the daily_study_reminder prompt every morning, convert UTC time to local time, and prioritize overdue items.

Design Principles

Response format and error codes

{ "success": true, "data": {...}, "message": "..." }
{ "success": true, "items": [...], "total": 12 }
{ "success": false, "error": "...", "error_code": "SCOPE_DENIED" }

• UNAUTHENTICATED (401) — Token missing, invalid, revoked, or expired
• SCOPE_DENIED (403) — Token does not have this scope; the response includes required_scope
• PERMISSION_DENIED (403) — Not an instructor for this course, or a teaching assistant attempted to write
• VALIDATION (400) — Invalid field content; the response explains the reason
• RATE_LIMITED (429) — 120 requests per minute and 5,000 requests per day per token