# Vidext developers

Vidext turns a single prompt into a structured learning path — outline, narrated slides, and AI-generated imagery — grounded in the organization's own documents. Built for agents: the Vidext Operator is available over a remote MCP endpoint.

## Start here

- MCP discovery: [/.well-known/mcp](https://staging.vidext.com/.well-known/mcp)
- OpenAPI spec: [/openapi.json](https://staging.vidext.com/openapi.json)
- Registry server metadata: [/server.json](https://staging.vidext.com/server.json)
- Full product context: [llms.txt](https://staging.vidext.com/llms.txt) and [llms-full.txt](https://staging.vidext.com/llms-full.txt)
- API catalog: [/.well-known/api-catalog](https://staging.vidext.com/.well-known/api-catalog)
- OAuth metadata: [/.well-known/oauth-authorization-server](https://staging.vidext.com/.well-known/oauth-authorization-server) and [/.well-known/oauth-protected-resource](https://staging.vidext.com/.well-known/oauth-protected-resource)

## Core endpoint

```
https://staging.vidext.com/api/mcp/operator
```

The shared endpoint is the recommended MCP integration surface for Claude, ChatGPT, Cursor, and other remote MCP clients. Module-scoped URLs are also supported at `/api/mcp/operator/{moduleId}`; they pass the path module id to the operator as the active module.

## Operator run contract

The MCP server intentionally exposes one high-level tool, `ask_vidext_operator`. A single operator agent handles every turn and selects its own tools, so callers send the user's request as one prompt. Successful responses include a `run` envelope with `modelId`, `mutationLevel`, `availableToolNames`, correlated request/run ids, normalized module/planner/builder/course ids, and `nextAction` polling guidance when asynchronous work is still running.

A single operator agent handles every turn and selects its own tools. Send the user's request as one prompt and read the `run` envelope on the response:

| Field | Meaning |
|---|---|
| `modelId` | The model that drove the turn. |
| `mutationLevel` | `read` when only read tools ran, `write` when any write tool ran. |
| `availableToolNames` | Tools the operator had available for the turn. |
| `requestId`, `traceId` | Correlation ids for the request and trace. |
| `ids` | Normalized module, course, planner, and builder ids touched this turn. |
| `nextAction` | Polling guidance when asynchronous outline or build work is still running. |

## Browser-local WebMCP

Authenticated Vidext app pages expose browser-local WebMCP tools through `document.modelContext`. These tools use the signed-in browser session; they are separate from the remote OAuth MCP server and do not appear in remote `tools/list`.

- `vidext.get_page_context` — return auth state, active organization slug, pathname, locale, and current module id.
- `vidext.ask_operator` — send one Operator turn from the current browser workspace, automatically passing the current organization and module when available.
- `vidext.list_modules` — list recent modules in the active workspace.
- `vidext.create_module` — create a module and open it in the module workspace.
- `vidext.open_module` — open an existing module workspace or learner module view.
- `vidext.open_workspace_operator` — open the active workspace home or sign-in page.
- `vidext.open_invite_dialog` — open the organization invite flow.

Use `ask_vidext_operator` for remote MCP clients after OAuth authorization. Use `vidext.ask_operator` only when the agent is already running inside the authenticated Vidext browser context.

## Authentication

Vidext Operator uses OAuth 2.1 authorization-code with PKCE and dynamic client registration. Unauthenticated MCP requests return a bearer challenge pointing clients to the protected-resource metadata.

- Authorization: `/api/auth/mcp/authorize`
- Token: `/api/auth/mcp/token`
- Dynamic registration: `/api/auth/mcp/register`
- Userinfo: `/api/auth/mcp/userinfo`
- JWKS: `/api/auth/mcp/jwks`

## Rate limits and error handling

Vidext exposes public discovery endpoints without auth, but application routes still enforce rate limits and structured error behavior.

- Public tRPC routes: **75 requests / 10 seconds / IP**
- Protected tRPC routes: **250 requests / 10 seconds / IP**
- Server actions: **50 / 10 seconds / IP**
- Unauthenticated MCP requests return 401 with a WWW-Authenticate header pointing to protected-resource metadata.
- MCP tool failures return isError: true with a JSON error payload in the text content.
- Common error codes: `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `METHOD_NOT_ALLOWED`, `CONFLICT`, `TOO_MANY_REQUESTS`, `UNPROCESSABLE_ENTITY`, `FAILED_DEPENDENCY`, `INTERNAL_SERVER_ERROR`, `TIMEOUT`
- Treat 429 responses as retryable, honor Retry-After when present, and rerun OAuth discovery on 401 bearer challenges.

## Quickstart

```bash
claude mcp add --transport http vidext-operator-staging https://staging.vidext.com/api/mcp/operator
```

On first use, the client follows the MCP OAuth challenge, performs dynamic registration if needed, and sends the user through the browser authorization flow.

## What agents can do

- Ask the Operator to research connected sources and organization wiki context
- Create and revise training modules through the operator agent
- Continue module workflows by chat id or active module id
- Inspect module lists and outline/build workflow status
- Route module outlining, builds, and existing-module edits — course requests are fulfilled as modules
- Use browser-local WebMCP tools on authenticated Vidext app pages for page context, module navigation, and context-aware Operator turns

## Machine-readable assets

- [/openapi.json](https://staging.vidext.com/openapi.json)
- [/server.json](https://staging.vidext.com/server.json)
- [/.well-known/api-catalog](https://staging.vidext.com/.well-known/api-catalog)
- [/card.json](https://staging.vidext.com/card.json)
- [/.well-known/mcp/server-card.json](https://staging.vidext.com/.well-known/mcp/server-card.json)
- [/.well-known/agent-card.json](https://staging.vidext.com/.well-known/agent-card.json)
- [/compare](https://staging.vidext.com/compare)
- [/alternatives](https://staging.vidext.com/alternatives)
- [/best-ai-learning-path-generator-for-employee-training](https://staging.vidext.com/best-ai-learning-path-generator-for-employee-training)
- [AGENTS.md](https://github.com/vidext/vidext/blob/staging/AGENTS.md)
- [Official Vidext Operator skill](https://staging.vidext.com/.well-known/agent-skills/vidext-operator/SKILL.md)