---
title: "Vidext developers"
description: "Integration guide for agents: MCP endpoints, OAuth 2.1, rate limits, environments, versioning, and machine-readable assets."
canonical: "https://staging.vidext.com/developers"
last-updated: "2026-10-22T13:33:44.202Z"
---

# Vidext developers

Vidext's agents turn the documents and procedures your company already has into training for your frontline teams, grounded in your own material.

## Start here

- Integration quickstart: [Connect an AI client](https://docs.vidext.io/docs/api/connect-an-ai-client) ([Markdown](https://docs.vidext.io/docs/api/connect-an-ai-client.md))
- Documentation: [https://docs.vidext.io/docs/api](https://docs.vidext.io/docs/api) (MCP reference at [https://docs.vidext.io/docs/api/mcp](https://docs.vidext.io/docs/api/mcp))
- 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
```

This endpoint is the MCP integration surface for Claude, ChatGPT, Cursor, and other remote MCP clients. Tools that read a specific module take its id as the `moduleId` argument.

## Documentation endpoint

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

Read-only access to the Vidext documentation at https://docs.vidext.io: list the pages, search them, and read any page as markdown. No authentication. Tools: `list_docs`, `search_docs`, `read_doc`. Pair it with the Vidext endpoint so an agent can answer questions from the docs and work in a workspace over the same protocol.

## Tools

The MCP server exposes typed tools over one remote endpoint: read tools for knowledge and modules (`mcp:read`), and author tools that talk to the Vidext author, which plans and builds modules (`mcp:author`). A call to a tool whose scope the token lacks answers `403` with `error="insufficient_scope"` and the scopes to request.

## 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.list_modules` — list recent modules in the active workspace.
- `vidext.open_module` — open an existing module's page.
- `vidext.open_home_chat` — open the authoring chat at the active workspace's Home, or the sign-in page.
- `vidext.open_invite_dialog` — open the organization invite flow.

Public pages such as sign-in register read-only discovery tools through the same `document.modelContext` API without a session:

- `vidext.get_product_context` — Return Vidext's llms.txt: what the product does, when to use it, its MCP tools, and links to every machine-readable resource.
- `vidext.get_mcp_discovery` — Return the JSON discovery document for the Vidext MCP server: endpoint, transport, protocol versions, OAuth metadata locations, and tool names.
- `vidext.get_developer_guide` — Return the markdown developer guide: OAuth 2.1 onboarding, rate limits, error handling, environments, and versioning for agents integrating with Vidext.
- `vidext.get_agent_auth_guide` — Return auth.md: the step-by-step agentic registration flow that yields a scoped bearer token for the Vidext MCP endpoint.

Remote MCP clients should select the narrowest public tool for the task.

## Authentication

The Vidext MCP server uses OAuth 2.1 authorization-code with PKCE; a client registers dynamically or uses the HTTPS URL of its client ID metadata document as its `client_id`. Only organization admins and members can connect over MCP; learners and people whose request to join is still pending are refused. Unauthenticated MCP requests return a bearer challenge pointing clients to the protected-resource metadata.

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

## Rate limits and error handling

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

- MCP tools: **Read tools: 120 calls a minute and 12 in flight, per person, organization, and tool. Author tools: author_send and author_answer 100 calls a minute and one at a time per conversation; author_updates, author_stop, and list_conversations 60 calls a minute; per person and organization.**
- A call over a limit comes back as a tool error (rate_limit_exceeded or concurrency_limit_exceeded from a read tool, rate_limited or write_in_flight from an author tool), never as HTTP 429: back off a few seconds and retry. Retry only an error marked retryable.
- Unauthenticated MCP requests return 401 with a WWW-Authenticate header pointing to protected-resource metadata. A call to a tool whose scope the token lacks returns 403 with error="insufficient_scope" and the scopes to request.
- MCP tool failures return isError: true. A read tool's text content is a JSON error payload; an author tool's is a sentence for the person, ending with the error code.
- HTTP 429 comes only from the OAuth routes under /api/auth and the agent registration routes under /api/agent/auth; honor Retry-After when present, and rerun OAuth discovery on a 401 bearer challenge.
- Every tool error code, with whether to retry it: [Errors, limits, and correlation](https://docs.vidext.io/docs/api/mcp/errors-and-limits).

### Rate limit headers

Two groups of routes advertise their quota so an agent can self-throttle before hitting `429`: the OAuth routes under `/api/auth/*`, and the agent registration routes `/api/agent/auth` and `/api/agent/auth/claim/complete`. The authorize, token, and consent endpoints (`/api/auth/oauth2/authorize`, `/api/auth/oauth2/token`, `/api/auth/oauth2/consent`) and the MCP endpoint carry none of these headers.

- `RateLimit-Policy` — the policy in force as an IETF structured field, for example `"auth";q=50;w=10` (50 requests per 10 seconds), and `RateLimit-Limit`, the quota rather than what is left. Both groups send them.
- `RateLimit` with `limit`, `remaining`, and `reset` seconds, plus the legacy `RateLimit-Remaining` / `RateLimit-Reset` pair — the agent registration routes only.
- `Retry-After` on every `429` from either group.

### Idempotent retries

The agent-auth POST endpoints accept an `Idempotency-Key` header. Send a unique key (a UUID) per logical request: a retry with the same key and body returns the stored response with `Idempotent-Replayed: true`, the same key with a different body is refused with `422`, and a retry that overlaps the first request gets `409` with `Retry-After`. Keys are kept for 24 hours.

## Quickstart

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

On first use, the client follows the MCP OAuth challenge, registers dynamically or presents its client ID metadata document if it has no credentials yet, and sends the user through the browser authorization flow.

## Environments

- Production: `https://app.vidext.com` is the base URL integrations are registered against; OAuth tokens are audience-bound to its MCP endpoint.
- Zero-auth entry point: every discovery document and the documentation MCP server at `/api/mcp/docs` need no credentials, so an agent can read, search, and plan before its first authenticated call. The first authenticated call is one OAuth 2.1 flow (or one auth.md registration) away; no sales contact or manual provisioning sits in between.
- `https://staging.vidext.com` is an internal Vidext environment, not offered to customers or integrators. Use production: https://app.vidext.com.

## Versioning and deprecation

- The MCP surface is versioned by protocol revision, not by URL path. `/.well-known/mcp` advertises the supported revisions in `protocolVersions`: `2026-07-28`, and the 2025-era revisions, which are served statelessly over POST with no session. A 2026-07-28 client sends its revision on every request; a 2025-era client negotiates one in `initialize` and sends it in the `MCP-Protocol-Version` header afterwards.
- Deprecation policy: a revision scheduled for removal keeps being served for at least 90 days after the announcement. From the announcement on, every response to a request in that revision carries `Deprecation` (RFC 9745, the announcement time) and `Sunset` (RFC 8594, the removal date) headers plus `Link` relations `deprecation` and `sunset` pointing at this section, so an unattended client notices on its next call. The same window applies to tools and arguments named in the [MCP reference](https://docs.vidext.io/docs/api/mcp).
- A 2026-07-28 request naming a revision the server does not serve is answered with JSON-RPC error `-32022`, so a client learns about a removal on its first call. A 2025-era `initialize` naming an unknown revision is answered with the newest 2025 revision the server serves, as that era negotiates.
- The public discovery contract carries its own version in `info.version` of [/openapi.json](https://staging.vidext.com/openapi.json); tool names, arguments, and result shapes are documented in the [MCP reference](https://docs.vidext.io/docs/api/mcp) and only change there first.
- Re-read the discovery documents on each connect instead of caching tool lists across sessions: a removed revision or tool disappears from them before it stops being served.
- Endpoint paths follow the same policy. `/api/mcp/operator` is a deprecated alias of `/api/mcp`, served in full until 2027-01-15: every response from it carries `Deprecation`, `Sunset`, and a `Link` with `rel="successor-version"` naming `/api/mcp`. It is not redirected, because a token is bound to the path it was issued for; connect the client again at `/api/mcp` to move.

## What agents can do

- Search the organization's profile, sources and processed source content
- List modules and whether each is live
- Talk to the Vidext author over remote MCP: send the user's messages, answer its questions, follow its progress, and stop it
- Use browser-local WebMCP tools on authenticated Vidext app pages for page context, module navigation, and opening the chat
- Read product context, MCP discovery, and the developer and auth guides through read-only WebMCP tools on public pages, no session required

## 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)
- [/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)
- [Official Vidext skill](https://staging.vidext.com/.well-known/agent-skills/vidext/SKILL.md)