Coroid como servidor MCP

Coroid expone un servidor remoto del Model Context Protocol (MCP). Un asistente o agente externo, como Hermes, Codex o Claude Code, puede utilizarlo para trabajar con Coroid a través del mismo registro de herramientas gestionadas que usa el asistente de chat.

Configúrelo en Configuración → Conexiones → Coroid MCP server, lo que incluye Resumen, Configuración del cliente, Tokens de acceso, Aprobaciones y Políticas de automatización.

El punto de conexión#

El servidor MCP se ejecuta en la puerta de enlace de API, en esta dirección:

https://api.coroid.ai/mcp

El transporte utilizado es HTTP Streamable sin estado. La autenticación se realiza mediante OAuth o un token de acceso personal.

Qué funcionalidades están activadas#

Coroid activa las capacidades de MCP por etapas, de forma simultánea para todas las organizaciones.

Mientras una capacidad no esté activada, los clientes no verán sus herramientas y Coroid rechazará las llamadas a ellas. El resto de esta página describe el conjunto completo.

Conectar un cliente#

Utilice OAuth cuando su cliente lo soporte. Usted aprueba la conexión en su navegador y puede revocarla en cualquier momento. Los tokens de acceso duran 15 minutos y los tokens de renovación 30 días; cada renovación reemplaza el token de renovación.

El cliente solicita ámbitos al conectarse. Antes de aprobar, verá los ámbitos y decidirá si el cliente puede acceder a todos los proyectos o solo a algunos. Un cliente que no solicite ámbitos tendrá acceso de lectura únicamente; por eso, solicite los ámbitos que necesite, como hace el ejemplo de Codex.

Hermes#

hermes mcp add coroid --url https://api.coroid.ai/mcp --auth oauth
hermes mcp login coroid
hermes mcp test coroid

En su lugar, con un token de acceso:

hermes mcp add coroid --url https://api.coroid.ai/mcp --auth header

Proporcione el token a Hermes cuando lo solicite. Guárdelo en el almacén de credenciales de Hermes en lugar de en su archivo de configuración.

Codex#

codex mcp add coroid --url https://api.coroid.ai/mcp
codex mcp login coroid --scopes mcp.read,mcp.work.write,mcp.execute,mcp.delivery

En su lugar, con un token de acceso:

export COROID_MCP_TOKEN="cmp_pat_…"
codex mcp add coroid --url https://api.coroid.ai/mcp --bearer-token-env-var COROID_MCP_TOKEN

Claude Code#

claude mcp add --transport http --scope user coroid https://api.coroid.ai/mcp
/mcp

Ejecute el primer comando en su terminal. Luego escriba el segundo en Claude Code,\nelija coroid e inicie sesión en su navegador.

En su lugar, con un token de acceso:

export COROID_MCP_TOKEN="cmp_pat_…"
claude mcp add --transport http --scope user --header "Authorization: Bearer $COROID_MCP_TOKEN" coroid https://api.coroid.ai/mcp

Otros clientes#

Cualquier cliente que soporte servidores MCP remotos mediante HTTP streamable puede conectarse. Coroid publica metadatos de OAuth para el punto de conexión y admite el registro dinámico de clientes con PKCE. Un cliente sin OAuth puede enviar un token de acceso como token portador en este encabezado: Authorization.

Antes de que un agente realice cambios, pídale que liste las herramientas de Coroid y que lea este recurso: coroid://context. Muestra bajo qué identidad actúa el agente, con qué ámbitos y proyectos.

Tokens de acceso#

Los tokens se crean y gestionan en Tokens de acceso. Al igual que cualquier otra credencial, se muestran una sola vez y nunca se vuelven a entregar después.

Genere un token por cliente en lugar de compartir uno. De este modo, revocar el acceso de un único cliente es una acción aislada y no provoca interrupciones para todos.

Un token actúa como la persona que lo creó, y solo una persona con sesión iniciada en el portal puede crear uno. Cada token tiene sus propios ámbitos, caduca después de 30, 90 o 365 días y abarca todos los proyectos o solo los proyectos que seleccione. Un propietario también puede asociar una política de automatización. Todos los tokens comienzan con el mismo prefijo: cmp_pat_.

Guarde un token en el entorno de su cliente o en el almacén de credenciales. Nunca lo coloque en un repositorio ni en un prompt.

Ámbitos y roles#

Un ámbito define las acciones permitidas por una conexión. Su rol en la organización establece los límites: una herramienta necesita tanto el ámbito como al menos el rol correspondiente. Coroid verifica su rol actual en cada llamada, para que una conexión nunca conserve derechos que haya perdido.

Solo un administrador o propietario puede otorgar un ámbito cuyo rol mínimo sea Administrador. Solo un propietario puede otorgar un ámbito cuyo rol mínimo sea Propietario.

Una conexión limitada a algunos proyectos no puede acceder a nada en otros proyectos, ni siquiera mediante el ID de una tarea, plan, sprint, informe o lanzamiento. Tampoco puede usar herramientas a nivel de organización, como estas: list_plans, get_capacity_dashboard.

Herramientas#

Su cliente muestra solo las herramientas que están activadas y que sus ámbitos y rol permiten. La columna de aprobación indica qué ocurre al llamar a una herramienta:

Lectura#

Estas herramientas requieren el rol de Revisor y este ámbito: mcp.read. Ninguna de ellas necesita aprobación.

Para consultar las herramientas de lanzamientos, consulte Lanzamientos mediante MCP.

Creación y modificación de trabajo#

Estas herramientas requieren el rol de Miembro y este ámbito: mcp.work.write.

El trabajo creado mediante MCP no pasa por la fase de cualificación. Una solicitud del tamaño de un plan enviada a la herramienta de tareas se convierte en un plan borrador en lugar de una tarea. Los planos creados mediante MCP comienzan como borradores.

Ejecución de trabajo#

Estas herramientas requieren el rol de Miembro y este ámbito: mcp.execute.

Entrega#

Estas herramientas requieren el rol de Miembro y este ámbito: mcp.delivery. Los lanzamientos tienen su propia sección más abajo.

Administración#

Estas herramientas modifican la configuración de la organización y sus proyectos.

Configuración de la organización#

Un agente como Hermes puede configurar una organización a partir de capturas de pantalla, archivos o una descripción. Lee el formato de configuración de Coroid, lo escribe en un paquete, muestra una vista previa del paquete y, a continuación, lo aplica. Estas herramientas requieren el rol de Propietario y este ámbito: mcp.organization.admin.

Un paquete contiene marcadores de posición en lugar de valores de secreto, y Coroid rechaza un paquete que incluya un secreto. Consulte Exportar e importar configuraciones.

Lanzamientos mediante MCP#

Las herramientas de lanzamiento son las mismas que utiliza el asistente de chat y pasan por el mismo Release API que el portal:

create_release acepta un SHA completo de confirmación, un SHA corto de una confirmación reciente o latest, y deja la versión en manos del origen de versiones del proyecto a menos que usted la especifique. get_release informa, por entorno, sobre las comprobaciones realizadas, el último despliegue, la versión que indicó la canalización y si Coroid verificó la versión en ejecución. Un token limitado a ciertos proyectos no puede acceder a los lanzamientos de otros proyectos. El Release API sigue aplicando sus propias reglas de aprobación, por lo que una aprobación mediante MCP cuenta exactamente igual que una en el portal.

list_release_pull_requests Devuelve las solicitudes de extracción abiertas de un proyecto en el orden que propone Coroid, junto con el motivo por el cual excluye alguna de ellas. bundle_release_pull_requests crea un lanzamiento a partir de ellos: una rama de lanzamiento con los pull requests fusionados en orden y un pull request de lanzamiento. Envía una rama y abre un pull request, por lo que siempre espera a una persona. Omite prNumbers Para utilizar la selección de Coroid.

Aprobaciones y políticas de automatización#

Aprobaciones constituyen una cola de acciones que esperan la intervención humana. Políticas de automatización definen qué debe incluirse en esa cola.

Este es el control más importante. Un cliente externo que actúe en su nombre debe poder realizar tareas rutinarias libremente y solo llevar a cabo acciones trascendentales con la autorización de una persona. Configure las políticas antes de entregar un token a cualquier elemento que se ejecute de forma autónoma.

Cuando una llamada necesita aprobación, el cliente recibe un ID de aprobación y un enlace en lugar de un resultado. El propietario o administrador revisa la herramienta y los argumentos específicos, y luego aprueba o rechaza la llamada. Al aprobarla, se ejecuta tal como se solicitó y el cliente no puede modificarla posteriormente. Una llamada que no sea aprobada por nadie en un plazo de 10 minutos caducará.

Una política de automatización permite que un token de acceso ejecute herramientas marcadas como Policy sin necesidad de esperar aprobación. Solo los propietarios pueden crear políticas y asociarlas a tokens. Una política indica las herramientas exactas, puede limitarse a ciertos proyectos y establecer un límite de llamadas por hora, por día y simultáneamente. También puede caducar. Revocar una política implica revocar todos los tokens vinculados a ella. Las herramientas marcadas como Always nunca quedan cubiertas por una política.

Una conexión OAuth no puede incluir una política. Mediante OAuth, todas las herramientas marcadas como Policy esperan aprobación.

Reintentos, operaciones y recursos#

Toda herramienta que realice cambios requiere este parámetro: idempotencyKey. Utiliza una clave nueva para cada acción nueva y la misma clave al reintentar una. Coroid devolverá el primer resultado en lugar de ejecutar la acción dos veces. Si se reutiliza una clave con argumentos diferentes, se rechazará.

Un cambio también genera una operación que registra su estado y resultado. Estas cuatro herramientas funcionan para toda conexión:

El servidor también proporciona estos recursos:

También ofrece tres indicaciones: create_and_run_task, investigate_failure, prepare_release.

Cada herramienta tiene límites por minuto, por hora y por día. Una llamada que supere el límite fallará y indicará cuánto tiempo debe esperarse para reintentarla.

Qué no expone deliberadamente#

El registro de herramientas está regulado y las exclusiones son intencionadas. No proporciona ninguna de estas opciones:

• un shell
• Acceso a Git
• el sistema de archivos
• acceso directo a la base de datos
• HTTP interno arbitrario
• las herramientas de administración MCP salientes propias de Coroid

Obtendrá la posibilidad de gestionar el trabajo — crear e inspeccionar tareas, planes, proyectos y lanzamientos — no se trata de un entorno de ejecución remoto. Un cliente MCP no puede utilizar Coroid para ejecutar comandos arbitrarios.

Para qué sirve#

Gestionar Coroid desde el entorno en el que ya trabajas: un editor, un asistente o una herramienta interna, sin necesidad de cambiar al portal. Crear una tarea desde la terminal o pedir a un asistente que verifique qué está bloqueado pasa a ser una acción local.

Relacionado#

• Formas de comenzar a trabajar
• Exportar e importar configuraciones
• Servidores MCP externos
• Asistente de Chat
• Procedencia