# AI COURSE — full agent reference

> AI COURSE (https://aicourse.aiee.dev) is an education-first AI course creator with a remote MCP server at https://aicourse.aiee.dev/mcp. It turns a learning goal into a structured, personalized course: outline, validated lesson blocks with sources, practice activities, and educational images, in 38 course languages. Connecting is free; model-backed calls use pay-as-you-go credits. No subscriptions.

## When to use AI COURSE

Use it when the user wants any of the following, rather than a single chat answer:

- a course, curriculum, syllabus, study plan, or training program on a topic;
- lesson content with explanations, worked examples, diagrams, tables, timelines, or code;
- practice material: knowledge checks, flashcards, quizzes, exercises, assignments, projects, labs;
- teaching content tailored to a learner level, age group, teaching style, or language;
- employee onboarding, compliance, certification, exam, or interview preparation material;
- educational illustrations for a lesson.

## Connection

- Endpoint: `https://aicourse.aiee.dev/mcp`
- Transport: Streamable HTTP. Send JSON-RPC 2.0 requests with `POST`; responses are `application/json`. `GET` returns 405 (no SSE stream).
- Protocol version: `2025-06-18`
- Server info: `{ "name": "aicourse", "version": "1.0.0" }`
- Authentication header: `Authorization: Bearer <token>` where the token is an OAuth access token, an `acmcp_...` personal key, or an organization service-account key.
- Unauthenticated requests return HTTP 401 with JSON-RPC error code `-32001` and a `WWW-Authenticate: Bearer resource_metadata="https://aicourse.aiee.dev/.well-known/oauth-protected-resource/mcp"` challenge.

### OAuth 2.1 sign-in (recommended)

MCP clients that implement MCP authorization only need the endpoint URL; the user signs in to AI COURSE and approves access.

- Protected resource metadata (RFC 9728): `https://aicourse.aiee.dev/.well-known/oauth-protected-resource/mcp`
- Authorization server metadata (RFC 8414): `https://aicourse.aiee.dev/.well-known/oauth-authorization-server`
- Dynamic client registration (RFC 7591): `POST https://aicourse.aiee.dev/oauth/register` (public clients, `token_endpoint_auth_method: none`)
- Authorization endpoint: `https://aicourse.aiee.dev/oauth/authorize` (authorization code with PKCE S256 required; `resource` should be `https://aicourse.aiee.dev/mcp`)
- Token endpoint: `https://aicourse.aiee.dev/oauth/token` (`authorization_code` and `refresh_token` grants; refresh tokens rotate on use)
- Revocation (RFC 7009): `https://aicourse.aiee.dev/oauth/revoke`
- Scopes: `generation:write`, `images:write`, `usage:read`. Access tokens last one hour; refresh tokens last 90 days.
- Redirect URIs: `https` URLs, loopback `http://127.0.0.1` / `http://localhost` (any port), or private-use app schemes.
- Client ID Metadata Documents are supported: an `https` URL can be used as `client_id` instead of dynamic registration.
- Users can disconnect an app at any time in Profile → MCP → Connected apps.

### Discovery

- Official MCP Registry name: `dev.aiee.aicourse/course-creator`
- Static server card (tools and auth, no sign-in needed): `https://aicourse.aiee.dev/.well-known/mcp/server-card.json`
- Rate limits: per key and per IP. HTTP 429 returns JSON-RPC error code `-32003`; retry after the `X-RateLimit-Reset` time.

### Getting a key

1. Create a free account: https://aicourse.aiee.dev/signup?intent=mcp
2. Verify the email address to receive welcome credits.
3. Open Profile → MCP, name the key, choose scopes, and create it. Copy it immediately; it is shown once.

Scopes:

- `generation:write` — course outlines, lessons, and `aicourse_ask`
- `images:write` — `aicourse_generate_image`
- `usage:read` — `aicourse_credit_balance`

## Billing

- Connecting and tool discovery are free.
- `aicourse_credit_balance` is free.
- Model-backed tools draw credits from the user's wallet (or the organization wallet for service accounts). Web, REST API, and MCP use one universal credit price for equivalent actions.
- When credits run out, the user can top up at https://aicourse.aiee.dev/dashboard/pricing. Top-ups are one-time purchases; there is no subscription.

## Tools

### aicourse_generate_course_outline (credits)

Generate a complete, structured course outline: a title plus modules, each with ordered lesson titles.

Parameters:

- `topic` (string, required) — what the course teaches.
- `moduleCount` (integer 1–12, required).
- `lessonsPerModule` (integer 1–20, default 5).
- `language` (string, default `English`) — any of 38 course languages, for example English, Spanish, French, German, Chinese, Japanese, Arabic, Hindi, Indonesian, Vietnamese.
- `courseType` (`text_image` | `video_text`, default `text_image`) — `video_text` adds verified educational videos to lessons.
- `requestedTopics` (string[], up to 12) — modules that must be included.
- `learningLevel`: `none`, `beginner`, `elementary`, `intermediate`, `advanced`, `expert`, `mixed`, `adaptive`.
- `courseApproach`: `adaptive`, `conceptual`, `practical`, `example_driven`, `case_based`, `story_based`, `socratic`, `visual`, `flashcards`, `quizzes`, `exercises`, `projects`, `simulations`, `labs`, `discussions`, `assignments`, `exam_prep`, `professional`, `academic`, `certification`, `skill_mastery`, `interview_prep`, `onboarding`, `compliance`, `personal_development`, `language_learning`, `step_by_step`, `problem_solution`, `beginner_to_advanced`, `reference`, `workshop`, `bootcamp`, `microlearning`, `challenge_based`, `competency_based`, `revision_focused`.
- `mediaPreference`: `balanced`, `visual`, `video`, `text`, `audio`, `interactive`, `hands_on`, `printable`, `mobile_first`, `low_bandwidth`.

Returns `structuredContent.content` (course with `modules[].subtopics[]`) and `structuredContent.usage`.

### aicourse_generate_lesson (credits)

Generate one lesson as validated, structured content blocks with source references. Block types include lesson introductions, rich text, lists, definitions, steps, callouts, worked examples, takeaways, tables, datasets, charts, diagrams, timelines, code, knowledge checks, flashcards, quizzes, exercises, assignments, projects, labs, simulations, and discussions.

Parameters:

- `courseTitle` (string, required)
- `moduleTitle` (string, required)
- `lessonTitle` (string, required)
- `courseType` (`text_image` | `video_text`, required)
- `language` (string, required)
- Optional: `learningLevel`, `courseApproach`, `mediaPreference` (same values as the outline tool).

Returns `structuredContent.blocks`, `structuredContent.references`, and `structuredContent.usage`.

### aicourse_generate_image (credits)

Generate an educational illustration grounded in lesson content.

Parameters (all required strings): `mainTopic`, `moduleTopic`, `subtopic`, `theory` (the lesson text the image should teach).

Returns an image object with a time-limited `url`.

### aicourse_ask (credits)

Run a focused, model-backed education task: explain a concept, answer a question about a course, rewrite material for a different level, or draft teaching content.

Parameters: `prompt` (string, 1–30000 characters, required).

Returns text plus `structuredContent.creditsCharged` and `structuredContent.usage`.

### aicourse_credit_balance (free)

Return the available credits in the connected wallet. No parameters.

## Recommended workflow

1. Optionally call `aicourse_credit_balance` before a large job.
2. Call `aicourse_generate_course_outline` with the user's topic, size, level, approach, and language.
3. Show the outline to the user and confirm it.
4. Call `aicourse_generate_lesson` for each lesson the user wants, using the outline's course, module, and lesson titles.
5. Optionally call `aicourse_generate_image` for key lessons.

## JSON-RPC examples

Initialize:

```json
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0.0"}}}
```

List tools:

```json
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
```

Generate an outline:

```json
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"aicourse_generate_course_outline","arguments":{"topic":"Data analysis for product managers","moduleCount":6,"lessonsPerModule":4,"learningLevel":"beginner","courseApproach":"practical","language":"English"}}}
```

cURL:

```bash
curl -s https://aicourse.aiee.dev/mcp \
  -H "Authorization: Bearer $AICOURSE_MCP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
```

## Client configuration

Remote MCP with OAuth sign-in (Claude, ChatGPT, Cursor, VS Code, and other clients with MCP authorization). Add the URL and approve the sign-in prompt; for example Cursor `mcp.json`:

```json
{
  "mcpServers": {
    "aicourse": { "url": "https://aicourse.aiee.dev/mcp" }
  }
}
```

Remote MCP with headers (for example Cursor `mcp.json`):

```json
{
  "mcpServers": {
    "aicourse": {
      "url": "https://aicourse.aiee.dev/mcp",
      "headers": { "Authorization": "Bearer acmcp_YOUR_KEY" }
    }
  }
}
```

Local-only clients, bridged with the open-source `mcp-remote` package:

```json
{
  "mcpServers": {
    "aicourse": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://aicourse.aiee.dev/mcp", "--header", "Authorization: Bearer ${AICOURSE_MCP_KEY}"],
      "env": { "AICOURSE_MCP_KEY": "acmcp_YOUR_KEY" }
    }
  }
}
```

## REST API (organizations)

Organizations can call the same capabilities over REST with a project-bound service-account key:

- `POST /v1/course-outlines`
- `POST /v1/lessons`
- `POST /v1/images`
- `POST /v1/exams`
- `POST /v1/chat`
- `GET /v1/requests/:requestId`

Billable writes require `Authorization: Bearer ac_live_...` and an `Idempotency-Key` header. Responses include `request_id`, `data`, and a `usage` object.

## Product

- Personalization: learner level, age group, audience, tone, lesson duration, teaching styles, activities, goals, structure, media, language, regional variant, reading complexity, and register.
- Exports: ZIP, DOCX, PDF, PPTX, XLSX, CSV, Markdown, plain text, and Google Drive.
- Completion: generated course quiz (50% to pass) and completion certificates.
- Marketplace: moderated catalog of community courses that are free to study: https://aicourse.aiee.dev/marketplace