Referência do servidor MCP

O EmDash inclui um servidor Model Context Protocol (MCP) integrado em /_emdash/api/mcp que expõe operações de gerenciamento de conteúdo como ferramentas para assistentes de IA.

Esta página aborda os detalhes do protocolo: autenticação, transporte, especificações da ferramenta, descoberta OAuth e tratamento de erros.

Autenticação

O servidor MCP suporta três métodos de autenticação:

Os cookies de sessão (da UI administrativa) também funcionam, mas não são práticos para clientes MCP externos.

Escopos

Os tokens têm como escopo limitar quais operações um cliente pode realizar. Os escopos são solicitados durante a autorização do OAuth e aplicados em cada chamada de ferramenta.

O escopo admin concede acesso a tudo. A autenticação baseada em sessão (sem token) também tem acesso total com base na função do usuário.

content:write concede implicitamente taxonomies:manage e menus:manage para que os tokens de acesso pessoal emitidos antes da divisão desses escopos continuem a funcionar sem reemissão. Novos tokens devem solicitar escopos granulares.

Requisitos de função

Além dos escopos, algumas ferramentas exigem uma função mínima de RBAC. Ambos devem ser satisfeitos – um token com o escopo correto ainda falhará se a função do usuário chamador for muito baixa.

Consulte o Guia de autenticação para definições de funções.

Transporte

O servidor usa o transporte HTTP Streamable em modo sem estado. Cada solicitação é independente – não há sessões ou conexões de longa duração.

• POST /_emdash/api/mcp — Enviar chamadas de ferramenta JSON-RPC
• GET /_emdash/api/mcp — Retorna 405 (sem SSE no modo sem estado)
• DELETE /_emdash/api/mcp — Retorna 405 (nenhuma sessão para fechar)

As respostas seguem o formato JSON-RPC 2.0. Os erros usam códigos de erro JSON-RPC padrão, com códigos específicos do MCP para falhas de escopo e permissão.

Ferramentas

O servidor expõe 43 ferramentas em oito domínios: conteúdo, esquema, mídia, pesquisa, taxonomias, menus, revisões e configurações. Cada ferramenta retorna resultados como conteúdo de texto JSON ou uma mensagem de erro com isError: true em caso de falha.

Ferramentas de conteúdo

content_list

Liste itens de conteúdo em uma coleção com filtragem e paginação opcionais.

Escopo: content:read | Somente leitura: Sim

content_get

Obtenha um único item de conteúdo por ID ou slug. Retorna todos os valores de campo, metadados e um token _rev para simultaneidade otimista.

Escopo: content:read | Somente leitura: Sim

content_create

Crie um novo item de conteúdo. O objeto data deve conter valores de campo que correspondam ao esquema da coleção – use schema_get_collection para verificar quais campos estão disponíveis. Os itens são criados como draft por padrão.

Escopo: content:write

content_update

Atualize um item de conteúdo existente. Inclua apenas os campos que você deseja alterar – os campos não especificados permanecem inalterados.

Escopo: content:write

content_delete

Exclua um item de conteúdo de forma reversível, movendo-o para a lixeira. Use content_restore para desfazer ou content_permanent_delete para removê-lo permanentemente.

Escopo: content:write | Destrutivo: Sim

content_restore

Restaure um item de conteúdo excluído da lixeira.

Escopo: content:write

content_permanent_delete

Exclua permanente e irreversivelmente um item de conteúdo da lixeira. O item deve estar na lixeira primeiro.

Escopo: content:write | Destrutivo: Sim

content_publish

Publique um item de conteúdo, disponibilizando-o no site. Cria uma revisão publicada a partir do rascunho atual. Edições posteriores criam um novo rascunho sem afetar a versão ativa até ser republicada.

Escopo: content:write

content_unpublish

Reverter um item publicado para o status de rascunho. Ele não estará mais visível no site ativo, mas seu conteúdo será preservado.

Escopo: content:write

content_schedule

Agende um item de conteúdo para publicação futura. Ele será publicado automaticamente na data/hora especificada.

Escopo: content:write

content_unschedule

Cancele uma publicação previamente agendada. O item mantém seu status atual; apenas o carimbo de data/hora scheduledAt é apagado. Idempotente – chamar um item que não está programado é um ambiente autônomo.

Escopo: content:write

content_compare

Compare a versão publicada (ao vivo) de um item de conteúdo com seu rascunho atual. Retorna ambas as versões e um sinalizador indicando se há alterações.

Escopo: content:read | Somente leitura: Sim

content_discard_draft

Descarte o rascunho atual e reverta para a última versão publicada. Funciona apenas em itens que foram publicados pelo menos uma vez.

Escopo: content:write | Destrutivo: Sim

content_list_trashed

Lista itens de conteúdo excluídos de forma reversível na lixeira de uma coleção.

Escopo: content:read | Somente leitura: Sim

content_duplicate

Crie uma cópia de um item de conteúdo existente. A duplicata é criada como um rascunho com “(Cópia)” anexado ao título e um slug gerado automaticamente.

Escopo: content:write

content_translations

Obtenha todas as variantes de localidade de um item de conteúdo. Retorna o grupo de tradução e um resumo de cada versão de localidade. Relevante apenas quando i18n está habilitado.

Escopo: content:read | Somente leitura: Sim

Ferramentas de esquema

schema_list_collections

Liste todas as coleções de conteúdo definidas no CMS. Retorna slug, rótulo, recursos suportados e carimbos de data/hora.

Sem parâmetros.

Escopo: schema:read | Função mínima: Editor | Somente leitura: Sim

schema_get_collection

Obtenha informações detalhadas sobre uma coleção, incluindo todas as definições de campo. Os campos descrevem o modelo de dados: nome, tipo, restrições e regras de validação. Use isso para entender o que content_create e content_update esperam.

Escopo: schema:read | Função mínima: Editor | Somente leitura: Sim

schema_create_collection

Crie uma nova coleção de conteúdo. Isso cria uma tabela de banco de dados e uma definição de esquema. O slug deve ser alfanumérico minúsculo com sublinhados, começando com uma letra.

Escopo: schema:write | Função mínima: Administrador

schema_delete_collection

Exclua uma coleção e sua tabela de banco de dados. Isso é irreversível e exclui todo o conteúdo da coleção.

Escopo: schema:write | Função mínima: Administrador | Destrutivo: Sim

schema_create_field

Adicione um novo campo ao esquema de uma coleção. Isso adiciona uma coluna à tabela do banco de dados.

Tipos de campo: string, text, number, integer, boolean, datetime, select, multiSelect, portableText, image, file, reference, json, slug.

Para os tipos select e multiSelect, forneça valores permitidos em validation.options.

Escopo: schema:write | Função mínima: Administrador

schema_delete_field

Remova um campo de uma coleção. Isso descarta a coluna e exclui todos os dados desse campo. Irreversível.

Escopo: schema:write | Função mínima: Administrador | Destrutivo: Sim

Ferramentas de mídia

media_list

Liste os arquivos de mídia carregados com filtragem e paginação de tipo MIME opcionais.

Escopo: media:read | Somente leitura: Sim

media_create

Registre um arquivo de mídia que já foi carregado para armazenamento. O chamador é responsável por colocar o arquivo em storageKey (normalmente usando um URL de upload assinado da UI administrativa ou uma API separada). Esta ferramenta persiste o registro de metadados para que o arquivo possa ser descoberto via media_list / media_get e possa ser referenciado por conteúdo.

Escopo: media:write | Função mínima: Autor

media_get

Obtenha detalhes de um único arquivo de mídia por ID. Retorna metadados incluindo nome do arquivo, tipo MIME, tamanho, dimensões, texto alternativo e URL.

Escopo: media:read | Somente leitura: Sim

media_update

Atualize os metadados de um arquivo de mídia carregado. O arquivo em si não pode ser alterado.

Escopo: media:write

media_delete

Exclua permanentemente um arquivo de mídia. Remove o registro do banco de dados e o arquivo do armazenamento. O conteúdo que faz referência a esta mídia terá referências quebradas.

Escopo: media:write | Destrutivo: Sim

Ferramenta de pesquisa

search

Pesquisa de texto completo em coleções de conteúdo. As coleções devem ter search em sua lista supports e os campos devem ser marcados como searchable.

Escopo: content:read | Somente leitura: Sim

Ferramentas de taxonomia

taxonomy_list

Liste todas as definições de taxonomia (por exemplo, categorias, tags). Retorna nome, rótulo, se hierárquico e coleções associadas.

Sem parâmetros.

Escopo: content:read | Somente leitura: Sim

taxonomy_list_terms

Liste os termos em uma taxonomia com paginação.

Escopo: content:read | Somente leitura: Sim

taxonomy_create_term

Crie um novo termo em uma taxonomia. Para taxonomias hierárquicas, especifique parentId para criar um termo filho. A cadeia ancestral do pai não deve exceder 100 níveis.

Escopo: taxonomies:manage | Função mínima: Editor

taxonomy_update_term

Atualize um termo existente em uma taxonomia. Qualquer campo pode ser omitido para deixá-lo inalterado. A renomeação de um slug não deve colidir com outro termo da mesma taxonomia. Defina parentId como null para desconectar de um pai. O novo pai deve existir, pertencer à mesma taxonomia e não introduzir um ciclo.

Escopo: taxonomies:manage | Função mínima: Editor

taxonomy_delete_term

Exclua permanentemente um termo de uma taxonomia. Qualquer conteúdo marcado com o termo perde a associação. Não é possível excluir um termo que tenha filhos. Exclua os filhos primeiro.

Escopo: taxonomies:manage | Função mínima: Editor | Destrutivo: Sim

Menu Ferramentas

menu_list

Liste todos os menus de navegação. Retorna nome, rótulo e carimbos de data/hora.

Sem parâmetros.

Escopo: content:read | Somente leitura: Sim

menu_get

Obtenha um menu por nome incluindo todos os itens em ordem. Os itens têm rótulo, URL, tipo e pai opcional para aninhamento.

Escopo: content:read | Somente leitura: Sim

menu_create

Crie um novo menu de navegação. O name é o identificador estável usado pelos modelos de site; label é o nome legível mostrado no admin. Adicione itens posteriormente com menu_set_items.

Escopo: menus:manage | Função mínima: Editor

menu_update

Atualize o rótulo de um menu. O name (identificador estável) não pode ser alterado.

Escopo: menus:manage | Função mínima: Editor

menu_delete

Exclua um menu e todos os seus itens. Não pode ser desfeito.

Escopo: menus:manage | Função mínima: Editor | Destrutivo: Sim

menu_set_items

Substitua toda a lista de itens de um menu em uma chamada. Atômica: os itens existentes são excluídos e a nova lista é inserida na ordem fornecida. Use isso em vez de operações de adição/remoção por item para que a ordem resultante e os links pai sejam inequívocos.

Os itens são posicionados por índice de array. O aninhamento é expresso por meio de parentIndex - um item com parentIndex: 0 é aninhado sob o item no índice 0. O pai deve aparecer no início da lista. Itens sem parentIndex são de nível superior.

Cada MenuItem tem:

Escopo: menus:manage | Função mínima: Editor

Ferramentas de revisão

revision_list

Lista o histórico de revisões de um item de conteúdo, o mais recente primeiro. Requer que a coleção suporte revisions.

Escopo: content:read | Somente leitura: Sim

revision_restore

Restaure um item de conteúdo para uma revisão anterior. Substitui o rascunho atual pelos dados da revisão especificada. Não publicado automaticamente - use content_publish posteriormente, se necessário.

Escopo: content:write

Ferramentas de configurações

Configurações de todo o site – título, slogan, logotipo, favicon, URL canônico, tamanho de página padrão, formatação de data e hora, identificadores sociais e padrões de SEO.

settings_get

Obtenha todas as configurações de todo o site. As referências de mídia (logo, favicon, seo.defaultOgImage) incluem URLs resolvidos junto com o mediaId subjacente. Os valores não definidos são omitidos da resposta.

Sem parâmetros.

Escopo: settings:read | Função mínima: Editor | Somente leitura: Sim

settings_update

Atualize uma ou mais configurações em todo o site. Atualização parcial: apenas os campos fornecidos são alterados; os campos omitidos são deixados como estão. Retorna o objeto de configurações completo após a atualização.

Para definir uma referência de mídia (logo, favicon, seo.defaultOgImage), passe um objeto com mediaId (e opcional alt). O item de mídia já deve existir – use media_create primeiro.

O objeto seo aceita:

Escopo: settings:manage | Função mínima: Administrador

Descoberta OAuth

Os clientes MCP que suportam OAuth 2.1 podem descobrir automaticamente como autenticar. O servidor publica dois documentos de metadados:

Metadados de recursos protegidos

GET /.well-known/oauth-protected-resource

{
  "resource": "https://example.com/_emdash/api/mcp",
  "authorization_servers": ["https://example.com/_emdash"],
  "scopes_supported": [
    "content:read", "content:write",
    "media:read", "media:write",
    "schema:read", "schema:write",
    "taxonomies:manage", "menus:manage",
    "settings:read", "settings:manage",
    "admin"
  ],
  "bearer_methods_supported": ["header"]
}

Metadados do servidor de autorização

GET /.well-known/oauth-authorization-server/_emdash

{
  "issuer": "https://example.com/_emdash",
  "authorization_endpoint": "https://example.com/_emdash/oauth/authorize",
  "token_endpoint": "https://example.com/_emdash/api/oauth/token",
  "scopes_supported": ["content:read", "content:write", "..."],
  "response_types_supported": ["code"],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token",
    "urn:ietf:params:oauth:grant-type:device_code"
  ],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none"],
  "device_authorization_endpoint": "https://example.com/_emdash/api/oauth/device/code"
}

Quando uma solicitação não autenticada atinge o endpoint MCP, o servidor retorna:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://example.com/.well-known/oauth-protected-resource"

Isso aciona o fluxo padrão de descoberta do cliente MCP.

Tratamento de erros

Erros de ferramenta são retornados como conteúdo de texto com isError: true:

{
  "content": [{ "type": "text", "text": "Collection 'nonexistent' not found" }],
  "isError": true
}

Erros de escopo e permissão geram erros de protocolo MCP:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32600,
    "message": "Insufficient scope: requires content:write"
  },
  "id": 1
}

Erros no nível de transporte (configuração incorreta do servidor, exceções não tratadas) retornam o código de erro JSON-RPC -32603 (erro interno) sem vazar detalhes de implementação.