Referência do servidor MCP

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 cobre os detalhes do protocolo: autenticação, transporte, especificações de ferramentas, descoberta OAuth e tratamento de erros.

Autenticação

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

Escopos

Requisitos de papel

Consulte o guia de autenticação para definições de papéis.

Transporte

O servidor usa o transporte Streamable HTTP em modo sem estado. Cada requisição é independente.

• POST /_emdash/api/mcp — Enviar chamadas de ferramentas JSON-RPC
• GET /_emdash/api/mcp — Retorna 405
• DELETE /_emdash/api/mcp — Retorna 405

Ferramentas

O servidor expõe ferramentas em oito domínios: conteúdo, esquema, mídia, busca, taxonomias, menus, revisões e configurações.

Ferramentas de conteúdo

content_list, content_get, content_create, content_update, content_delete, content_restore, content_permanent_delete, content_publish, content_unpublish, content_schedule, content_unschedule, content_compare, content_discard_draft, content_list_trashed, content_duplicate, content_translations

Ferramentas de esquema

schema_list_collections, schema_get_collection, schema_create_collection, schema_delete_collection, schema_create_field, schema_delete_field

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

Ferramentas de mídia

media_list, media_upload, media_create, media_get, media_update, media_delete, media_usage_repair

Ferramenta de busca

search

Busca de texto completo nas coleções de conteúdo.

Escopo: content:read | Somente leitura: Sim

Ferramentas de taxonomia

taxonomy_list, taxonomy_list_terms, taxonomy_create_term, taxonomy_update_term, taxonomy_delete_term

Ferramentas de menu

menu_list, menu_get, menu_create, menu_update, menu_delete, menu_set_items

Ferramentas de revisão

revision_list, revision_restore

Ferramentas de configurações

settings_get, settings_update

Descoberta OAuth

Metadados do recurso protegido

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"
}

Tratamento de erros

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

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

{
  "content": [
    { "type": "text", "text": "[INSUFFICIENT_SCOPE] Insufficient scope: requires content:write" }
  ],
  "isError": true,
  "_meta": { "code": "INSUFFICIENT_SCOPE" }
}

Erros a nível de transporte retornam código de erro JSON-RPC -32603 (Erro interno) sem expor detalhes de implementação.