Servidor MCP de Workel

El servidor oficial del Model Context Protocol para Workel: un cliente fino y sin estado de la API pública de Workel v1. Expone un espacio de trabajo de Workel a agentes de IA (Claude, el SDK de OpenAI Agents o cualquier otro cliente que hable MCP) como un pequeño conjunto de herramientas bien delimitadas. Cada regla que de verdad importa — qué puede ver esta clave, qué puede escribir, a qué velocidad puede escribirlo — vive en la propia API de Workel; este paquete no tiene ninguna autoridad que la clave no tenga ya. Una petición curl hecha con la misma clave puede hacer exactamente lo que este servidor puede hacer, ni más.

Para la configuración completa por cliente (Claude Desktop, Claude Code, .mcp.json con ámbito de proyecto y el SDK de OpenAI Agents), consulta la documentación para desarrolladores de Workel.

¿Usas Claude? Probablemente no necesitas este paquete

Workel ejecuta un servidor MCP alojado. Añádelo en Claude en Configuración → Conectores → Añadir conector personalizado:

https://mcp.workel.com/mcp

Inicias sesión en Workel, eliges un espacio de trabajo y ya estás conectado. Sin instalación, sin archivo de configuración y sin clave de API: nunca la ves y tampoco la ve Claude. Autorizar requiere ser propietario o administrador del espacio de trabajo que elijas, y la conexión se vuelve a comprobar en cada petición, de modo que perder ese rol la desconecta sin que nadie tenga que acordarse de revocar una clave.

Puede leer tus proyectos, tareas, comentarios, eventos y miembros — incluida la imagen de portada de una tarea, sus archivos adjuntos y su historial completo — y puede crear tareas, comentarios y eventos, y actualizar tareas existentes: renombrarlas, cambiar fechas y prioridad, moverlas entre columnas y proyectos, y cambiar a quién están asignadas. No puede eliminar nada y no puede subir archivos. Los permisos de lectura y escritura se enumeran por separado en la pantalla de consentimiento, de modo que los apruebas con conocimiento en lugar de descubrirlos más tarde.

Conectar más de un espacio de trabajo

Una conexión cubre un espacio de trabajo, porque la credencial que hay detrás está vinculada a ese espacio. Para llegar a un segundo, añade el conector de nuevo y elige el otro espacio: cada conexión se registra por separado, así que coexisten, y cada una aparece con el nombre de su espacio de trabajo (workel — Acme) en lugar de como entradas idénticas que no puedes distinguir.

Una cosa a tener en cuenta: volver a autorizar una conexión existente la mueve, no la añade. Pasar de nuevo por el consentimiento en un conector que ya habías añadido reemplaza su credencial y desactiva la anterior, de modo que esa conexión cambia al espacio de trabajo que elijas. Si quieres ambos, añade un conector nuevo en lugar de volver a autorizar el que ya tienes.

Related MCP server: Google Workspace MCP Server

Ejecutarlo tú mismo

Este paquete es para los casos que el servidor alojado no cubre: Claude Code, agentes de CI, el SDK de OpenAI Agents — en cualquier lugar donde quieras ejecutar el proceso tú mismo y conservar la credencial. Todo lo que sigue trata de eso.

Gestiona varios espacios de trabajo de forma distinta, y mejor para este caso de uso: establece WORKEL_API_KEYS como una lista separada por comas, una clave por espacio de trabajo, y cada herramienta gana un argumento workspace que indica en cuál actuar. Diez herramientas siguen siendo diez herramientas por muchos espacios de trabajo que configures, en lugar de multiplicarse por espacio — lo cual importa porque cada definición de herramienta es contexto que el modelo paga en cada turno.

Acuña una clave dedicada de solo lectura antes de empezar

Antes de apuntar cualquier cliente de IA a este servidor, ve a Workel → Configuración → Desarrolladores y acuña una clave de API nueva solo para este propósito: no reutilices una clave que otra integración ya tenga. Acuñar una clave requiere un rol de propietario o administrador. Concédele solo los ámbitos read:* que las herramientas de esta versión usan realmente (read:projects, read:tasks, read:members, read:events — consulta Herramientas más abajo); deja sin marcar todos los ámbitos write:* a menos que hayas decidido deliberadamente dejar que un agente cree y edite cosas en tu espacio de trabajo por su cuenta. Usa una clave por máquina o agente, nómbrala para que recuerdes para qué es más tarde, y si una máquina se retira o un cliente se ve comprometido, revoca esa única clave en Configuración → Desarrolladores en lugar de rotar una clave que comparten varias herramientas: la revocación es instantánea y surte efecto en la siguiente petición.

Dos cosas que vale la pena entender antes de tocar las banderas que se describen a continuación:

• WORKEL_ENABLE_WRITES es una bandera de consentimiento del operador local, no un límite de autorización. Solo puede estrechar lo que se ofrece a una clave ya delimitada, nunca ampliarlo — y como vive en un archivo de configuración o una variable de entorno a la que un agente de codificación de IA normalmente tiene acceso de escritura, un agente que se ejecute en tu máquina puede volver a ponerla en true por sí mismo. Una bandera local no es algo que un agente no confiable pueda dejar en paz. Los propios ámbitos de la clave — concedidos deliberadamente al acuñarla y revocables en cualquier momento — son la puerta real.

• Una anulación de WORKEL_API_BASE_URL envía tu clave a otro host. Cada petición que hace este servidor lleva tu clave en la cabecera Authorization. Si WORKEL_API_BASE_URL apunta alguna vez a una URL que no controlas, ese host recibe tu clave en cada llamada. Este cliente rechaza una anulación de http:// simple excepto hacia localhost/127.0.0.1/[::1] precisamente por esta razón. La misma lógica se aplica a una clave real pegada en cualquier archivo: si alguna vez se confirma en git, rotar la clave es la única solución real — el historial de git es para siempre. Una confirmación posterior que elimine la línea no la quita del historial del repositorio, y cualquiera que haya clonado el repositorio mientras tanto sigue teniendo la clave antigua.

Instalación

npx -y @workel/mcp@0.4.0

Fija la versión: 0.4.0 arriba es la versión actual de este paquete; comprueba npm view @workel/mcp version para la última antes de fijarla. La forma sin fijar que aparece abajo es solo por conveniencia, válida para una prueba manual puntual, no para algo que la configuración de un agente ejecute sin supervisión:

npx -y @workel/mcp

Variables de entorno

doctor

Ejecuta npx -y @workel/mcp@0.4.0 doctor cada vez que tu cliente MCP informe solo de "el servidor no pudo arrancar" sin más detalle. Ejecuta exactamente la misma comprobación de arranque que ejecuta el propio servidor — cargar la configuración y luego sondear GET /me — e imprime un informe en texto plano en stdout en lugar de intentar hablar el protocolo MCP:

base URL: https://api.workel.com/api/public/v1
workspace: Acme Inc
key: ci-key
scopes: read:projects, read:tasks
2 tools would register: workel_whoami, workel_list_projects
write budget: 59/60 remaining this minute

doctor nunca inicia un transporte y nunca habla con tu cliente MCP — es un comando independiente que ejecutas desde una terminal, y termina con 0 en caso de éxito o 1 ante cualquier fallo (clave WORKEL_API_KEY ausente o no válida, una API inalcanzable, o una clave que la API rechaza). A diferencia del resumen de una línea que el servidor imprime en stderr en un arranque normal (que omite la URL base cuando es la predeterminada), doctor siempre imprime la URL base efectiva — incluso cuando es la predeterminada — porque una ejecución de doctor es exactamente el momento en que una WORKEL_API_BASE_URL manipulada necesita ser visible.

Herramientas

Esta versión registra las siguientes herramientas de lectura. workel_whoami no necesita ningún ámbito y funciona con cualquier clave válida; cualquier otra herramienta solo se registra cuando los ámbitos de la clave (descubiertos mediante la sonda GET /me anterior) incluyen el ámbito indicado. Las herramientas de listado devuelven 25 resultados por llamada por defecto (máximo 50 — este cliente limita deliberadamente por debajo del límite de 100 de la propia API, ver src/tools/conventions.ts) y paginan mediante un par opaco cursor / next_cursor.

Herramientas de escritura

Cuatro, y se registran solo cuando ambas condiciones se cumplen: la clave lleva el alcance write:* correspondiente y WORKEL_ENABLE_WRITES=true está establecido. Cualquiera de las dos por sí sola no registra nada, por lo que una instalación de solo lectura nunca los ve.

Ninguna herramienta elimina nada. workel_update_task está anotada con destructiveHint: true, por lo que un cliente que respeta las anotaciones solicita confirmación antes de cada llamada; las herramientas de lectura están anotadas como de solo lectura y se ejecutan sin una.

El servidor alojado en mcp.workel.com se ejecuta con escrituras habilitadas, por lo que las trece herramientas están disponibles allí.

Limitaciones

replayed no demuestra unicidad. Cada escritura que las herramientas de este servidor harían lleva una Idempotency-Key, y el almacén de idempotencia de la API de Workel (retención de 24 horas, limitado a la clave que llama) reproduce exactamente la misma respuesta para un intento repetido con la misma clave y el mismo cuerpo de solicitud: el segundo intento informa replayed: true, y no se crea ni cambia nada por segunda vez.

replayed: false significa que este intento en particular se ejecutó genuinamente; no significa que no exista un duplicado en ningún otro lugar. En particular: una respuesta de error nunca se almacena en caché, por lo que reintentar después de un fallo siempre se vuelve a ejecutar de verdad; el registro de idempotencia expira después de 24 horas, por lo que un reintento muy tardío se vuelve a ejecutar de verdad; y el almacén tiene un espacio de nombres por clave de API, por lo que el mismo valor literal de Idempotency-Key enviado con una clave diferente nunca choca con — y nunca protege contra un duplicado creado por — la primera. A menos que una llamada de herramienta reutilice explícitamente la misma clave de idempotencia en dos intentos, cada intento es una escritura genuinamente independiente en lo que el servidor puede decir.