Servidores MCP
A integração MCP (Model Context Protocol) do VDClip permite que assistentes de IA e clientes de agente
trabalhem com projetos do VDClip em nome de um usuário logado. As ferramentas MCP mapeiam diretamente para os
endpoints /v1/* e retornam os mesmos dados, então é uma camada fina e type-safe sobre a API REST.
Diferente da API REST, que usa uma Authorization Bearer estática, os clientes MCP e de agente autenticam
através do Servidor de Autorização OAuth 2.1 do VDClip. Cada requisição carrega um token
Authorization: Bearer <JWT> de curta duração que o usuário concedeu pelo fluxo de authorization code com PKCE.
Servidores MCP, agentes de IA e integrações de terceiros autenticam através dos endpoints OAuth 2.1
porque atuam em nome de um usuário específico. Para automação servidor-a-servidor que
não representa um usuário individual, prefira a superfície estática Authorization Bearer
em vez disso. Dúvidas: contact@vdclip.com.
Como tudo se encaixa
O servidor MCP não adiciona um novo modelo de dados. É um conector que:
- Autentica o cliente através do Servidor de Autorização OAuth 2.1 em
/oauth2/*e/.well-known/*(emissorhttps://api.vdclip.com). - Traduz cada chamada de ferramenta em uma chamada aos endpoints públicos
/v1/*. - Retorna os dados para que o assistente possa ler projetos, gerenciar clipes e disparar renderizações.
Como as chamadas são os mesmos endpoints /v1, o comportamento, os escopos e os limites correspondem ao
resto desta referência. A lista autoritativa de endpoints e schemas é o documento OpenAPI em
/pt-BR/api-reference.
Autenticação
Os clientes MCP e de agente usam o Servidor de Autorização OAuth 2.1, não uma chave de API. O fluxo é:
- Descubra os metadados do servidor em
/.well-known/oauth-authorization-servere as chaves de assinatura em/.well-known/jwks.json. - Registre um cliente com Dynamic Client Registration (
POST /oauth2/application). - Conduza o usuário pelo fluxo de authorization code com PKCE
(
GET /oauth2/authorize, depoisPOST /oauth2/authorize/complete). - Troque o authorization code por tokens em
POST /oauth2/token, e depois chame/v1/*comAuthorization: Bearer <JWT>.
Os endpoints OAuth usam corpos de requisição e resposta no formato RFC padrão, não o envelope /v1
direct JSON responses with errors[] on failure usado pelo resto da API. Para o fluxo completo,
parâmetros e códigos de erro, veja OAuth 2.1.
OAuth 2.1
Fluxo de authorization code com PKCE para clientes que agem em nome de um usuário
Autenticação
Chaves de API e o cabeçalho Authorization Bearer para servidor-a-servidor
REST API
Os endpoints /v1 aos quais as ferramentas MCP mapeiam
Escopos e capacidades
O que um agente pode fazer é limitado pelos escopos que o usuário concedeu. Os escopos seguem a
convenção vdclip:<resource>:<action> e são os mesmos escopos usados pela REST API. Um cliente
solicita os escopos de que precisa no registro ou na autorização, e um token sem um escopo exigido
é rejeitado com MISSING_SCOPE.
O catálogo completo de escopos é:
| Escopo | Concede |
|---|---|
vdclip:account:read | Ler perfil da conta, plano e saldo de créditos |
vdclip:projects:read | Listar e ler projetos, clipes e links de compartilhamento |
vdclip:projects:write | Criar e excluir projetos, gerenciar links de compartilhamento |
vdclip:results:read | Ler detalhes do clipe |
vdclip:results:write | Curtir ou descurtir clipes |
vdclip:render:execute | Iniciar renderizações e ler o status do render (restrito por plano) |
vdclip:social:read | Listar contas sociais conectadas |
vdclip:social:publish | Publicar ou agendar um clipe (restrito por plano) |
vdclip:templates:read | Listar e ler templates |
vdclip:templates:write | Criar, atualizar e excluir templates |
vdclip:assets:read | Ler assets do brand kit |
vdclip:assets:write | Enviar, confirmar e excluir assets do brand kit |
vdclip:calendar:read | Listar conteúdo agendado e publicado |
vdclip:calendar:write | Reagendar, atualizar e cancelar postagens agendadas |
vdclip:media:upload | Gerar URLs de upload de mídia pré-assinadas |
A tabela abaixo mapeia cada capacidade aos endpoints /v1 que ela chama e ao escopo de que precisa:
| Capacidade | Mapeia para | Escopo |
|---|---|---|
| Ler perfil da conta e saldo de créditos | GET /v1/account, GET /v1/credits | vdclip:account:read |
| Listar, ler e gerenciar projetos | /v1/projects | vdclip:projects:read, vdclip:projects:write |
| Ler e reagir a clipes | /v1/clips/{clip_id} | vdclip:results:read, vdclip:results:write |
| Ler e gerenciar templates | /v1/templates | vdclip:templates:read, vdclip:templates:write |
| Ler e enviar assets do brand kit | /v1/assets | vdclip:assets:read, vdclip:assets:write |
| Ler e gerenciar o calendário | /v1/calendar | vdclip:calendar:read, vdclip:calendar:write |
| Ler conexões sociais | endpoints sociais | vdclip:social:read |
| Renderizar um clipe | POST /v1/clips/{clip_id}/renders | vdclip:render:execute |
| Publicar ou agendar um clipe | POST /v1/clips/{clip_id}/publish | vdclip:social:publish |
render:execute e social:publish são restritos por plano, assim como na superfície REST. A renderização
consome créditos, e a publicação depende do plano do usuário e das contas sociais conectadas. Se
um token tem o escopo mas o plano não permite a ação, a chamada falha com
INSUFFICIENT_CREDITS ou um erro de plano. Veja preços para detalhes
do plano.
Erros
As chamadas roteadas pelo servidor MCP expõem os mesmos códigos de erro legíveis por máquina que a REST
API: INVALID_API_KEY, MISSING_SCOPE, INSUFFICIENT_CREDITS, RATE_LIMITED,
UPSTREAM_ERROR, VALIDATION_ERROR, INVALID_JSON, NOT_FOUND e ORIGIN_REJECTED. Quando um
cliente atinge o limite de taxa, a resposta é HTTP 429 com um cabeçalho Retry-After. Os endpoints
OAuth em si retornam corpos de erro no estilo RFC.
Veja Erros e Limites de taxa para a referência completa.
Dicas e Boas Práticas
Peça o conjunto mais restrito de escopos vdclip:<resource>:<action> que a integração realmente usa. Menos escopos significam uma tela de consentimento mais limpa e um raio de impacto menor.
Os access tokens são JWTs de curta duração. Use o refresh token de /oauth2/token para obter novos access tokens em vez de pedir ao usuário para reautorizar.
Respeite o cabeçalho Retry-After em respostas com limite de taxa e faça backoff. Tráfego de agente em rajadas é a causa mais comum de throttling.
Nunca embuta uma Authorization Bearer em código de cliente. Para agentes voltados ao usuário, use o fluxo Bearer OAuth em vez disso.