Referencia del servidor MCP
Datos técnicos para quien configura un asistente o escribe su propio cliente. Para conectar Claude, Cursor, Codex o VS Code basta con la página Asistentes de IA.
Direcciones del servidor
Todo está en el mismo dominio, https://excaliclaw.com. El servidor MCP habla JSON-RPC 2.0 sobre HTTP, sin estado (cada petición es independiente) y sin canal SSE.
| Dirección | Método | Para qué sirve |
|---|
/mcp | POST | El servidor MCP: initialize, tools/list, tools/call, prompts/list, prompts/get, resources/list y resources/read. Sin token válido responde 401 con una cabecera WWW-Authenticate que apunta a los metadatos. |
/.well-known/oauth-protected-resource y /.well-known/oauth-protected-resource/mcp | GET | Metadatos del recurso protegido (RFC 9728): indican qué servidor de autorización usar. |
/.well-known/oauth-authorization-server y /.well-known/openid-configuration | GET | Descubrimiento del servidor de autorización OAuth 2.1. |
/register | POST | Registro dinámico de clientes: el asistente se da de alta solo. |
/authorize | GET | Abre en el navegador la pantalla de consentimiento (exige PKCE S256). |
/token | POST | Cambia el código autorizado por el token de acceso y renueva el token. |
No hace falta implementar nada de esto a mano para usar Claude, Cursor, Codex o VS Code: ya hablan OAuth y MCP. La tabla es para quien escribe su propio cliente.
Autenticación
- OAuth 2.1 con registro dinámico de clientes y PKCE (S256). El usuario aprueba el acceso en el navegador con su cuenta; no hay clave que copiar.
- Permiso (scope)
drawings: el asistente actúa en nombre del usuario y ve y edita lo suyo, y lo que otras personas hayan compartido con él con permiso de edición. - Las claves API de la API REST no valen para el MCP: el MCP solo acepta tokens OAuth.
Las 37 herramientas
| Grupo | Herramientas |
|---|
| Leer y buscar | list_designs, search_designs (por nombre), get_design, list_design_versions, get_design_version, list_collections, get_live_scene |
| Crear y editar | create_design, update_design (añadir, cambiar o quitar elementos), delete_design, move_designs_to_collection, create_collection, add_sticky_note, apply_live_scene_change, wait_for_scene_change |
| Generar diagramas | create_flow_diagram, create_er_diagram, create_sequence_diagram, create_from_mermaid, create_architecture_from_files |
| Comprobar y ordenar | verify_design, lint_design, validate_design (ensayo en seco), get_diagram_graph, fix_overlaps, auto_layout, arrange_elements (alinear y distribuir), group_elements, reorder_elements (capas) |
| Exportar | export_design (PNG, SVG o fichero .excalidraw), export_as_mermaid |
| Guías y bibliotecas | get_diagram_example, get_skill, list_icons, list_library_components, get_library_component, save_library_component |
Diagramas: Mermaid, secuencia y arquitectura
- Mermaid:
create_from_mermaid lee flowchart/graph, stateDiagram, erDiagram, sequenceDiagram y mindmap. Solo lee la estructura y la coloca el servidor, sin solapes. Los tipos no soportados (clases, gantt...) se rechazan con un mensaje claro. - Secuencia:
create_sequence_diagram (hasta 12 participantes y 80 mensajes); cada texto cabe entre dos líneas de vida. - Arquitectura de un repositorio:
create_architecture_from_files lee docker-compose, wrangler y package.json y dibuja lo que declaran, con la evidencia de cada pieza. - Todas aceptan
theme: sketch (a mano), clean, mono (grises) o pastel.
Validación estricta
Toda escritura pasa por una puerta de validación: esquema tipado de los elementos más reglas de colocación (formas solapadas, texto que no cabe, texto suelto, flechas sin destino...). Si hay errores, la escritura se rechaza entera: no se guarda nada y la respuesta lista todos los errores con los ids afectados y una corrección ya calculada. No hay forma de saltársela. Después de escribir, verification.status queda en «pending» hasta que se llama a verify_design, que además devuelve la imagen.
Límites
- 60 llamadas por minuto y usuario.
- Una escena guardada no puede superar los 10 MB.
- Diagramas generados: hasta 100 nodos y 200 conexiones (flujo), 50 entidades (ER), 12 participantes y 80 mensajes (secuencia).
- Texto Mermaid: hasta 100 000 caracteres. Arquitectura desde ficheros: hasta 60 ficheros de 300 KB.
- El uso del MCP no cuenta contra ningún tope del plan: es ilimitado en todos los planes.
Recursos, guías y prompts
Además de las herramientas, el servidor ofrece recursos legibles por el asistente: 14 guías de buenas prácticas (excaliclaw://skills/<nombre>), ejemplos reales que ya pasan la validación (excaliclaw://examples/<nombre>) y una guía de estilo; y un prompt, design_diagram, que lleva al asistente por el flujo recomendado: mirar ejemplos, crear, verificar, corregir y compartir. La documentación para agentes está también en llms.txt.