Servidor MCP de Elido: Claude Desktop, Cursor y Claude Code

El servidor MCP de Elido es un pequeño proceso de Node que permite a Claude Desktop, Cursor o Claude Code crear enlaces cortos, listarlos y leer series temporales de clics desde dentro de un chat. Vive en el monorepo, en packages/mcp-server, habla MCP por stdio y se comunica con la misma API REST que todo lo demás.

Una corrección de entrada, porque una versión anterior de esta guía se equivocó: el paquete no está en npm y aún no es público. A fecha de 2026-11-11, npm view @elido/mcp-server devuelve un 404; pronto habrá una publicación pública. Hasta entonces lo ejecutas desde una compilación local. Todo lo que sigue se comprobó contra el código de packages/mcp-server y services/api-core.

Qué es MCP

El Model Context Protocol es un estándar abierto para que un cliente de IA llame a herramientas que viven fuera del modelo. El cliente inicia un servidor o se conecta a él, le pide la lista de herramientas y envía las llamadas a herramientas como mensajes JSON-RPC. El servidor hace el trabajo y devuelve texto que lee el modelo. El modelo nunca tiene tu clave de API; la tiene el servidor.

La especificación define dos transportes, stdio para procesos locales y Streamable HTTP para remotos (especificación MCP, última revisión 2026-07-28, consultado el 2026-10-25). El servidor de Elido implementa solo stdio.

Qué hace el servidor

Está escrito a mano, sin el @modelcontextprotocol/sdk oficial, para no tener dependencias. En src/index.ts responde a cuatro cosas: initialize (informando la versión de protocolo 2024-11-05), tools/list, tools/call y la notificación notifications/initialized. Cualquier otra cosa recibe un error de "method not found". No hay manejadores de recursos, prompts ni ping.

Cada llamada a una herramienta se convierte en una petición REST autenticada a ELIDO_API_BASE (por defecto https://api.elido.app) con Authorization: Bearer <key> y la cabecera User-Agent: elido-mcp-server/0.1.0. Las llamadas fallidas vuelven como un error que incluye el estado HTTP y los primeros 400 caracteres de la respuesta.

Sobre generate_qr: api-core sirve un POST /v1/qr/generate público y un diseño por enlace en GET /v1/workspaces/{id}/links/{link_id}/qr, pero nada en la ruta a la que llama la herramienta. Hasta que se concilie, no construiría un flujo de trabajo sobre ella. Está en el backlog.

Compilarlo y obtener una clave de API

El monorepo es privado, así que los pasos siguientes valen cuando tengas el código fuente del paquete (pronto habrá una publicación pública). Compila el paquete:

pnpm install
pnpm --filter @elido/mcp-server build

Eso produce packages/mcp-server/dist/index.js. Necesitas Node 20 o superior (engines en su package.json).

Para la clave, abre Dashboard, luego API keys (/dashboard/api-keys), pon a la clave el nombre del agente y elige un rol. El formulario ofrece viewer, editor y admin, y editor es el predeterminado. Las claves de Elido llevan un rol de espacio de trabajo, no permisos por herramienta. Una clave viewer es la opción de solo lectura: puede listar y leer analítica, y la API rechaza create_link. Define una caducidad si la clave es para una prueba. Copia la clave cuando se muestre y no la subas al control de versiones.

Configurar Claude Desktop

Claude Desktop lee claude_desktop_config.json. La ubicación de la configuración y la pestaña de ajustes de Developer se describen en la documentación de MCP (conectar servidores locales, consultado el 2026-10-25). En macOS el archivo es ~/Library/Application Support/Claude/claude_desktop_config.json, y en Windows %APPDATA%\Claude\claude_desktop_config.json.

{
  "mcpServers": {
    "elido": {
      "command": "node",
      "args": [
        "/absolute/path/to/url-shortener/packages/mcp-server/dist/index.js"
      ],
      "env": {
        "ELIDO_API_KEY": "elido_your_key_here",
        "ELIDO_WORKSPACE_ID": "42"
      }
    }
  }
}

Usa una ruta absoluta. ELIDO_WORKSPACE_ID es opcional solo cuando la clave ve exactamente un espacio de trabajo; entonces el servidor llama una vez a GET /v1/workspaces y guarda el id en caché. Con dos o más espacios de trabajo lanza un error que te dice que definas la variable, así que defínela desde el principio.

Reinicia Claude Desktop tras guardar. Si el servidor no aparece, ejecuta antes el mismo comando en un terminal. Que falte la clave no detiene el proceso, imprime una advertencia en stderr y todas las llamadas a herramientas fallan después.

Configurar Cursor y Claude Code

Cursor lee la misma estructura mcpServers desde .cursor/mcp.json en un proyecto, o desde ~/.cursor/mcp.json para todos los proyectos (documentación MCP de Cursor, consultado el 2026-10-25). Pega el bloque de arriba, añade el archivo a .gitignore porque contiene una clave real, y comprueba el servidor en los ajustes MCP de Cursor.

Claude Code añade un servidor stdio desde la línea de comandos (documentación MCP de Claude Code, consultado el 2026-10-25):

claude mcp add --env ELIDO_API_KEY=elido_your_key_here --env ELIDO_WORKSPACE_ID=42 \
  --transport stdio elido -- node /absolute/path/to/packages/mcp-server/dist/index.js

Las claves en un archivo de configuración están en texto plano. En una máquina compartida, da a cada persona su propia clave para que el rastro de auditoría signifique algo.

Dos sesiones, con las formas reales de las peticiones

Son conversaciones ilustrativas, no grabaciones, y los números son inventados. Los argumentos de las herramientas y los campos de resultado coinciden con el código.

Acortar un enlace de campaña. Le pides a Claude que acorte https://shop.example.com/spring con el slug spring y la etiqueta spring. Llama a create_link con destination_url, slug, title y tags. Como no se pasó domain_id, el servidor primero obtiene GET /v1/workspaces/{id}/domains y usa el primero que devuelva. Si tu espacio de trabajo tiene varios dominios, pasa tú mismo domain_id. La API responde con el registro del enlace, incluido short_url, y Claude lo pone en el borrador. Si el slug está en uso, la API devuelve 409 "slug already exists for this domain", y Claude puede elegir otro.

Leer los clics de la semana pasada. Pides los clics diarios de un enlace, en hora de Berlín. Claude llama a query_analytics con link_id, from, to, interval: "day" y tz: "Europe/Berlin". Las fechas son YYYY-MM-DD, y la API rechaza un rango en el que from no sea anterior a to, así que pasa el día siguiente a tu último día como to. Si las omites, el rango son los últimos 30 días. El resultado es {"items": [{"ts": "...", "count": 312}, ...]}. No hay campo total, así que pide a Claude que sume los recuentos. Solo clics: por esta herramienta no llega ningún desglose por país, dispositivo o referente.

Seguridad y límites

Roles, no permisos por herramienta. Elige el rol más bajo que haga el trabajo. Viewer para agentes de informes, editor para los que crean enlaces, admin solo con una razón concreta.

Lo que sale de tu máquina. El servidor envía peticiones a tu base de API de Elido y a ningún otro sitio. Lo que tu cliente de IA envía a su propio proveedor lo cubre la política de ese proveedor.

Rastro de auditoría. Crear una clave emite un evento de auditoría api_key.created, y crear un enlace emite link.created. No he verificado cómo se atribuye un evento a una clave concreta, así que no confíes en el registro de auditoría para distinguir a dos agentes. Dale a cada uno su propia clave y vigila la lista de claves.

Límites de tasa. Las llamadas cuentan para el límite del espacio de trabajo: 10 peticiones por segundo en Free, 30 en Pro y 100 en Business, con márgenes de ráfaga de 20, 60 y 200 (services/api-core/internal/httpserver/server.go). Un agente que cree cientos de enlaces debería usar POST /v1/workspaces/{id}/links/bulk a través de la API, como en importación masiva desde una hoja de Google.

MCP remoto. Sería un endpoint alojado con OAuth, para que un conector de Claude pudiera llegar a Elido sin un proceso local. Está planificado, no construido, y el catálogo de integraciones del panel solo lista el servidor local. Úsalo por ahora.

Deriva del protocolo. El servidor declara 2024-11-05 mientras la revisión actual de la especificación es 2026-07-28. No lo hemos probado con todas las versiones de cada cliente, así que comprueba el estado del servidor en tu cliente después de una actualización.

Hacia dónde va esto

Las lagunas de arriba están en el backlog: publicar el paquete, arreglar generate_qr, añadir Streamable HTTP y el endpoint remoto, añadir más herramientas (actualizar, eliminar, desgloses geográficos) y atribución de auditoría por clave. Para otra vía hacia la misma idea de agente, consulta la guía de Gemini y la guía de ChatGPT; para la higiene de claves, permisos de claves de API para herramientas de enlaces.

Relacionado en el blog

• Permisos de claves de API para herramientas de enlaces - roles, mínimo privilegio y rotación.

• Importar enlaces cortos de forma masiva desde una hoja de Google - la vía correcta para cientos de enlaces.

• Acortador de URL con Gemini - dónde funcionan las llamadas a herramientas en Gemini.

• Acortador de URL con ChatGPT - qué funciona y qué lo simula.

• Enlaces cortos como Terraform - gestión de enlaces al estilo infraestructura.

• Límites de tasa e idempotencia de la API de un acortador de URL - cómo se comportan los límites para los clientes.

• Marius