MCP Servers
The VDClip MCP (Model Context Protocol) integration lets AI assistants and agent clients work
with VDClip projects on behalf of a signed-in user. The MCP tools map directly to the /v1/*
endpoints and return the same data, so it is a thin, type-safe layer over the REST API.
Unlike the REST API, which uses a static Authorization Bearer, MCP and agent clients authenticate through
the VDClip OAuth 2.1 Authorization Server. Each request carries a short-lived
Authorization: Bearer <JWT> token the user granted through the authorization-code flow with PKCE.
MCP servers, AI agents, and third-party integrations authenticate through the OAuth 2.1
endpoints because they act on a specific user’s behalf. For server-to-server automation that
does not represent an individual user, prefer the static Authorization Bearer surface
instead. Questions: contact@vdclip.com.
How it fits together
The MCP server adds no new data model. It is a connector that:
- Authenticates the client through the OAuth 2.1 Authorization Server at
/oauth2/*and/.well-known/*(issuerhttps://api.vdclip.com). - Translates each tool call into a call against the public
/v1/*endpoints. - Returns the data so the assistant can read projects, manage clips, and trigger renders.
Because the calls are the same /v1 endpoints, the behavior, scopes, and limits match the rest of
this reference. The authoritative endpoint and schema list is the OpenAPI document at
/en/api-reference.
Authentication
MCP and agent clients use the OAuth 2.1 Authorization Server, not an API key. The flow is:
- Discover the server metadata at
/.well-known/oauth-authorization-serverand the signing keys at/.well-known/jwks.json. - Register a client with Dynamic Client Registration (
POST /oauth2/application). - Drive the user through the authorization-code flow with PKCE
(
GET /oauth2/authorize, thenPOST /oauth2/authorize/complete). - Exchange the authorization code for tokens at
POST /oauth2/token, then call/v1/*withAuthorization: Bearer <JWT>.
The OAuth endpoints use standard RFC-shaped request and response bodies, not the /v1
direct JSON responses with errors[] on failure envelope used by the rest of the API. For the full flow,
parameters, and error codes, see OAuth 2.1.
OAuth 2.1
Authorization-code flow with PKCE for user-delegated clients
Authentication
API keys and the Authorization Bearer header for server-to-server
REST API
The /v1 endpoints the MCP tools map to
Scopes and capabilities
What an agent can do is bounded by the scopes the user granted. Scopes follow the
vdclip:<resource>:<action> convention and are the same scopes used by the REST API. A client
requests the scopes it needs at registration or authorization, and a token missing a required
scope is rejected with MISSING_SCOPE.
The full scope catalog is:
| Scope | Grants |
|---|---|
vdclip:account:read | Read account profile, plan, and credit balance |
vdclip:projects:read | List and read projects, clips, and share links |
vdclip:projects:write | Create and delete projects, manage share links |
vdclip:results:read | Read clip detail |
vdclip:results:write | Like or dislike clips |
vdclip:render:execute | Start renders and read render status (plan-gated) |
vdclip:social:read | List connected social accounts |
vdclip:social:publish | Publish or schedule a clip (plan-gated) |
vdclip:templates:read | List and read templates |
vdclip:templates:write | Create, update, and delete templates |
vdclip:assets:read | Read brand-kit assets |
vdclip:assets:write | Upload, confirm, and delete brand-kit assets |
vdclip:calendar:read | List scheduled and posted content |
vdclip:calendar:write | Reschedule, update, and cancel scheduled posts |
vdclip:media:upload | Mint presigned media upload URLs |
The table below maps each capability to the /v1 endpoints it calls and the scope it needs:
| Capability | Maps to | Scope |
|---|---|---|
| Read account profile and credit balance | GET /v1/account, GET /v1/credits | vdclip:account:read |
| List, read, and manage projects | /v1/projects | vdclip:projects:read, vdclip:projects:write |
| Read and react to clips | /v1/clips/{clip_id} | vdclip:results:read, vdclip:results:write |
| Read and manage templates | /v1/templates | vdclip:templates:read, vdclip:templates:write |
| Read and upload brand-kit assets | /v1/assets | vdclip:assets:read, vdclip:assets:write |
| Read and manage the calendar | /v1/calendar | vdclip:calendar:read, vdclip:calendar:write |
| Read social connections | social endpoints | vdclip:social:read |
| Render a clip | POST /v1/clips/{clip_id}/renders | vdclip:render:execute |
| Publish or schedule a clip | POST /v1/clips/{clip_id}/publish | vdclip:social:publish |
render:execute and social:publish are plan-gated, just like on the REST surface. Rendering
consumes credits, and publishing depends on the user’s plan and connected social accounts. If
a token holds the scope but the plan does not allow the action, the call fails with
INSUFFICIENT_CREDITS or a plan error. See pricing for plan
details.
Errors
Calls routed through the MCP server surface the same machine-readable error codes as the REST
API: INVALID_API_KEY, MISSING_SCOPE, INSUFFICIENT_CREDITS, RATE_LIMITED,
UPSTREAM_ERROR, VALIDATION_ERROR, INVALID_JSON, NOT_FOUND, and ORIGIN_REJECTED. When a
client is rate limited, the response is HTTP 429 with a Retry-After header. The OAuth
endpoints themselves return RFC-style error bodies instead.
See Errors and Rate limits for the full reference.
Tips & Best Practices
Ask for the narrowest set of vdclip:<resource>:<action> scopes that the integration actually uses. Fewer scopes means a cleaner consent screen and a smaller blast radius.
Access tokens are short-lived JWTs. Use the refresh token from /oauth2/token to obtain new access tokens instead of asking the user to re-authorize.
Respect the Retry-After header on rate-limited responses and back off. Bursty agent traffic is the most common cause of throttling.
Never embed an Authorization Bearer in client code. For user-facing agents, use the OAuth Bearer flow instead.