O Coroid expõe um servidor Model Context Protocol (MCP) remoto. Um assistente ou agente externo, como Hermes, Codex ou Claude Code, pode usá-lo para trabalhar com o Coroid por meio do mesmo registro de ferramentas governadas que o assistente de chat utiliza.
Configure em Configurações → Conexões → Coroid MCP server, o que inclui Visão geral, Configuração do cliente, Tokens de acesso, Aprovações e Políticas de automação.
O endpoint
O servidor MCP roda no gateway do API, neste endereço:
https://api.coroid.ai/mcpO transporte utilizado é HTTP streamable sem estado. Autentique-se com OAuth ou um token de acesso pessoal.
O que está habilitado
O Coroid habilita os recursos de MCP em etapas, para todas as organizações de uma vez.
| Recurso | No coroid.ai |
|---|---|
| Login via OAuth | Ativado |
| Ler ferramentas | Ativado |
| Tokens de acesso pessoais | Ativado |
| Ferramentas que criam, alteram, executam ou entregam trabalho | Ativado |
| Ferramentas de administração, incluindo Configurações da organização | Ainda não |
Enquanto um recurso não estiver ativado, os clientes não verão suas ferramentas e o Coroid recusará chamadas para elas. O restante desta página descreve o conjunto completo.
Conectar um cliente
Use OAuth quando seu cliente suportar. Você aprova a conexão no seu navegador e pode revogá-la a qualquer momento. Os tokens de acesso duram 15 minutos e os tokens de atualização 30 dias; cada atualização substitui o token de atualização.
O cliente solicita escopos ao se conectar. Antes de aprovar, você vê os escopos e escolhe se o cliente pode acessar todos os projetos ou apenas alguns. Um cliente que não solicitar escopos terá acesso de leitura apenas; portanto, peça os escopos necessários, como faz o exemplo do Codex.
Hermes
hermes mcp add coroid --url https://api.coroid.ai/mcp --auth oauth
hermes mcp login coroid
hermes mcp test coroidCom um token de acesso em vez disso:
hermes mcp add coroid --url https://api.coroid.ai/mcp --auth headerForneça o token ao Hermes quando ele solicitá-lo. Armazene-o no repositório de credenciais do Hermes, não no arquivo de configuração.
Codex
codex mcp add coroid --url https://api.coroid.ai/mcp
codex mcp login coroid --scopes mcp.read,mcp.work.write,mcp.execute,mcp.deliveryCom um token de acesso em vez disso:
export COROID_MCP_TOKEN="cmp_pat_…"
codex mcp add coroid --url https://api.coroid.ai/mcp --bearer-token-env-var COROID_MCP_TOKENClaude Code
claude mcp add --transport http --scope user coroid https://api.coroid.ai/mcp
/mcpExecute o primeiro comando no seu terminal. Depois digite o segundo no Claude Code, escolha coroid e faça login no seu navegador.
Com um token de acesso em vez disso:
export COROID_MCP_TOKEN="cmp_pat_…"
claude mcp add --transport http --scope user --header "Authorization: Bearer $COROID_MCP_TOKEN" coroid https://api.coroid.ai/mcpOutros clientes
Qualquer cliente que suporte servidores MCP remotos via HTTP Streamable pode se conectar.
O Coroid publica metadados de OAuth para o endpoint e suporta registro dinâmico de clientes com PKCE. Um cliente sem OAuth pode enviar um token de acesso como um
Bearer Token neste cabeçalho: Authorization.
Antes que um agente altere algo, peça a ele que liste as ferramentas do Coroid e leia este recurso: coroid://context. Ele mostra como o agente age, com quais escopos e projetos.
Tokens de acesso
Os tokens são criados e gerenciados em Tokens de acesso. Assim como qualquer outra credencial, eles são exibidos uma única vez e nunca mais retornados posteriormente.
Emita um token por cliente em vez de compartilhar um só. Revogar o acesso de um único cliente será então uma ação isolada, e não uma interrupção para todos.
Um token age como a pessoa que o criou, e somente uma pessoa logada no portal pode criar um. Cada token tem seus próprios escopos, expira após 30, 90 ou
365 dias e abrange todos os projetos ou apenas os projetos que você selecionar. Um proprietário também pode associar uma política de automação. Todos os tokens começam com o mesmo prefixo:
cmp_pat_.
Mantenha um token no ambiente do seu cliente ou no armazenamento de credenciais. Nunca o coloque em um repositório ou em um prompt.
Escopos e funções
Um escopo define o que uma conexão pode fazer. Sua função na organização estabelece o limite: uma ferramenta precisa tanto do escopo quanto da função mínima exigida. O Coroid verifica sua função atual em cada chamada, para que uma conexão nunca mantenha direitos que você perdeu.
| Escopo | O que ele habilita | Função mínima |
|---|---|---|
mcp.read | Leitura de Projetos, Tarefas, Planos, Sprints, Relatórios, dependências, capacidade, execuções de agente, faixas da Factory, promoções e Lançamentos | Revisor |
mcp.work.write | Criar e alterar Tarefas, Planos, Sprints, dependências e Relatórios | Membro |
mcp.execute | Iniciar, parar, tentar novamente, pausar, retomar e cancelar trabalhos | Membro |
mcp.delivery | Aprovar planos, encerrar Sprints, promoções, validação de faixas e Lançamentos | Membro |
mcp.projects.admin | Criar, atualizar, arquivar e restaurar Projetos, além de controlar versões de Lançamento | Administrador |
mcp.schedules.admin | Ler, criar, atualizar, acionar e excluir agendamentos | Administrador |
mcp.integrations.admin | Ler, testar, ativar/desativar e excluir integrações | Administrador |
mcp.secrets.write | Criar integrações que armazenam credenciais | Proprietário |
mcp.organization.admin | Membros, convites, perfil da organização e Configurações da organização | Proprietário |
mcp.billing.read | Reservado. Nenhuma ferramenta o utiliza ainda | — |
mcp.billing.write | Reservado. Nenhuma ferramenta o utiliza ainda | Proprietário |
Apenas um administrador ou proprietário pode conceder um escopo cuja função mínima seja Administrador. Apenas um proprietário pode conceder um escopo cuja função mínima seja Proprietário.
Uma conexão limitada a alguns projetos não consegue acessar nada em outros projetos, mesmo pelo ID de uma tarefa, plano, sprint, relatório ou lançamento. Também não pode usar ferramentas válidas para toda a organização, como estas: list_plans,
get_capacity_dashboard.
Ferramentas
Seu cliente lista apenas as ferramentas que estão ativadas e que seus escopos e função permitem. A coluna de aprovação indica o que acontece quando uma ferramenta é chamada:
| Aprovação | O que acontece |
|---|---|
| Nenhum | A ferramenta é executada imediatamente |
| Política | A chamada aguarda aprovação, a menos que uma política de Automação a cubra |
| Sempre | A chamada sempre aguarda a aprovação de um proprietário ou administrador |
Leitura
Essas ferramentas precisam da função Revisor e deste escopo: mcp.read. Nenhuma delas necessita de aprovação.
| Área | Ferramentas |
|---|---|
| Projetos | list_projects, get_project, get_project_dependencies, list_project_branches |
| Tarefas | list_tasks, get_task, get_workflow_status, get_execution_status, check_task_can_start |
| Planos | list_plans, get_plan, get_plan_progress, list_plan_tasks |
| Sprints | list_sprints, get_sprint, get_sprint_status |
| Dependências | analyze_dependencies, get_dependency_graph, get_global_dependency_graph, get_cross_project_blockers |
| Relatórios | list_reports, get_report, export_report, explain_report_execution, list_report_folders, list_report_subscriptions, list_report_templates |
| Capacidade e atividade | get_capacity_dashboard, get_queue_eta, get_mission_control_activity, get_global_execution_stats, get_global_execution_actions, list_global_execution_runs |
| Execução de agentes | list_agent_executions, get_agent_execution, get_agent_execution_state, get_execution_conversation, list_tool_executions |
| Faixas e promoções da Factory | list_factory_lanes, get_factory_lane, list_factory_lane_tasks, get_factory_lane_gate_context, list_promotions, get_promotion |
| Histórico de código | explain_code |
Para ver as ferramentas de lançamento, consulte Lançamentos via MCP.
Criar e alterar trabalho
Essas ferramentas exigem a função de Membro e este escopo: mcp.work.write.
| Área | Ferramentas | Aprovação |
|---|---|---|
| Tarefas | create_task, update_task | Nenhum |
| Planos | create_plan, update_plan | Nenhum |
| Planos | delete_plan | Sempre |
| Sprints | create_sprint, plan_sprint, add_task_to_sprint | Nenhum |
| Sprints | remove_task_from_sprint | Sempre |
| Dependências | create_dependency | Nenhum |
| Relatórios | create_report, update_report, create_report_folder, update_report_folder, create_report_subscription, update_report_subscription | Nenhum |
| Relatórios | batch_update_reports, delete_report, delete_report_folder, delete_report_subscription | Sempre |
O trabalho criado via MCP não passa pela etapa de Qualificação. Uma solicitação do tamanho de um plano enviada à ferramenta de tarefas se torna um plano rascunho em vez de uma tarefa. Os planos criados via MCP começam como rascunhos.
Execução de trabalho
Essas ferramentas exigem a função de Membro e este escopo: mcp.execute.
| Área | Ferramentas | Aprovação |
|---|---|---|
| Tarefas | start_task_execution, retry_task_execution | Política |
| Tarefas | stop_task_execution | Sempre |
| Planos | start_planning_workflow, execute_plan, retry_plan_task_integration | Política |
| Planos | cancel_plan | Sempre |
| Sprints | start_sprint | Política |
| Relatórios | pause_report, resume_report, cancel_report, retry_report_generation | Política |
| Factory | start_global_execution, pause_global_execution, resume_global_execution, pause_factory_lane, resume_factory_lane | Política |
| Factory | cancel_global_execution, set_agent_execution_state | Sempre |
Entrega
Essas ferramentas exigem a função de Membro e este escopo: mcp.delivery. Os lançamentos possuem sua própria seção abaixo.
| Ferramentas | Aprovação |
|---|---|
approve_plan, close_sprint, create_promotion, approve_promotion, request_promotion_changes, validate_factory_lane | Política |
force_merge_promotion | Sempre |
Administração
Essas ferramentas alteram a forma como a organização e seus projetos são configurados.
| Ferramentas | Escopo | Função mínima | Aprovação |
|---|---|---|---|
create_project, update_project, restore_project | mcp.projects.admin | Administrador | Nenhum |
archive_project | mcp.projects.admin | Administrador | Sempre |
list_schedules, get_schedule, create_schedule, update_schedule | mcp.schedules.admin | Administrador | Nenhum |
trigger_schedule | mcp.schedules.admin | Administrador | Política |
delete_schedule | mcp.schedules.admin | Administrador | Sempre |
list_integrations, get_integration | mcp.integrations.admin | Administrador | Nenhum |
test_integration | mcp.integrations.admin | Administrador | Política |
set_integration_status, delete_integration | mcp.integrations.admin | Administrador | Sempre |
create_integration | mcp.secrets.write | Proprietário | Sempre |
list_organization_members, list_organization_invitations | mcp.organization.admin | Proprietário | Nenhum |
invite_organization_member, update_organization_member_role, remove_organization_member, revoke_organization_invitation, update_organization | mcp.organization.admin | Proprietário | Sempre |
Configurações da organização
Um agente como o Hermes pode configurar uma organização a partir de capturas de tela, arquivos ou uma descrição. Ele lê o formato de configurações do Coroid, escreve o conteúdo em um pacote, pré-visualiza o pacote e, em seguida, aplica as alterações. Essas ferramentas exigem a função de Proprietário e este escopo: mcp.organization.admin.
| Ferramenta | O que ela faz | Aprovação |
|---|---|---|
describe_organization_settings_schema | Retorna o formato de configurações, suas seções e dicas de mapeamento | Nenhum |
export_organization_settings | Exporta as configurações atuais, com segredos como placeholders | Nenhum |
preview_organization_settings_import | Mostra quais alterações um pacote causaria, sem aplicá-las | Nenhum |
apply_organization_settings_import | Aplica um pacote, mesclando-o às configurações atuais por padrão ou substituindo-as | Sempre |
Um pacote contém placeholders em vez de valores de segredo, e o Coroid rejeita um pacote que inclua algum segredo. Veja Exportar e importar configurações.
Lançamentos via MCP
As ferramentas de lançamento são as mesmas utilizadas pelo assistente de chat e passam pela mesma Release API que o portal:
| Ferramenta | Escopo | Aprovação |
|---|---|---|
list_releases, get_release, list_release_commits, preview_release, get_release_settings, list_release_pull_requests | mcp.read | Nenhum |
create_release, update_release, run_release_checks, draft_release_notes | mcp.delivery | Nenhum |
approve_release, request_release_deployment, bundle_release_pull_requests | mcp.delivery | Sempre |
update_release_versioning | mcp.projects.admin | Nenhum |
create_release aceita um SHA completo de commit, um SHA curto de um commit recente, ou
latest, e deixa a versão para a fonte de versão do projeto, a menos que você
especifique uma. get_release relata, por ambiente, as verificações, a última implantação, a versão informada pelo pipeline e se o Coroid confirmou a versão em execução. Um token limitado a alguns projetos não consegue acessar lançamentos em outros projetos. A Release API ainda aplica suas próprias regras de aprovação, portanto uma aprovação via MCP conta exatamente como uma feita no portal.
list_release_pull_requests Retorna os pull requests abertos de um projeto na ordem sugerida pelo Coroid, incluindo o motivo para excluir algum deles.
bundle_release_pull_requests Cria uma release a partir deles: um branch de release com os pull requests mesclados em ordem e um pull request de release. Ele envia um branch e abre um pull request, portanto sempre aguarda a intervenção de uma pessoa. Deixe de fora
prNumbers Para utilizar a seleção feita pelo Coroid.
Aprovações e políticas de automação
Aprovações é uma fila de ações aguardando aprovação humana. Políticas de automação definem o que deve entrar nessa fila.
Esse é o controle essencial. Um cliente externo agindo em seu nome deve poder realizar tarefas rotineiras livremente e apenas coisas relevantes com autorização humana. Defina as políticas antes de fornecer um token a qualquer componente que execute de forma autônoma.
Quando uma chamada precisa de aprovação, o cliente recebe um ID de aprovação e um link em vez de um resultado. O proprietário ou administrador analisa a ferramenta e os argumentos exatos e, então, aprova ou rejeita a chamada. A aprovação executa a chamada exatamente como foi feita, e o cliente não pode alterá-la posteriormente. Uma chamada sem aprovação em 10 minutos expira.
Uma política de automação permite que um token de acesso execute ferramentas marcadas como Policy sem aguardar aprovação. Apenas proprietários criam políticas e as vinculam a tokens. Uma política especifica as ferramentas exatas, pode ser restrita a determinados projetos e limita o número de chamadas por hora, por dia e simultaneamente. Ela também pode expirar. Revogar uma política revoga todos os tokens associados a ela. Ferramentas marcadas como Always nunca são abrangidas por uma política.
Uma conexão OAuth não pode transportar uma política. Por meio de OAuth, toda ferramenta marcada como Policy aguarda aprovação.
Tentativas, operações e recursos
Toda ferramenta que altera algo requer este parâmetro: idempotencyKey.
Use uma nova chave para cada nova ação e a mesma chave ao tentar novamente.Coroid então retorna
o primeiro resultado em vez de executar a ação duas vezes. Uma chave reutilizada com argumentos diferentes
é recusada.
Uma alteração também gera uma operação que registra seu status e resultado. Essas quatro ferramentas funcionam para qualquer conexão:
| Ferramenta | O que faz |
|---|---|
get_operation | Retorna o status e o resultado de uma operação |
wait_for_operation | Aguarda até 25 segundos pela alteração de uma operação |
cancel_operation | Cancela uma operação que ainda não começou |
get_approval | Retorna o status e o resultado de uma aprovação |
O servidor também disponibiliza esses recursos:
| Recurso | Conteúdo |
|---|---|
coroid://context | Quem a conexão representa, com sua função, escopos e projetos |
coroid://capabilities | As ferramentas que essa conexão pode usar |
coroid://operations/{operationId} | Uma operação |
coroid://approvals/{approvalId} | Uma aprovação |
Ele também oferece três prompts: create_and_run_task, investigate_failure,
prepare_release.
Cada ferramenta tem limites por minuto, por hora e por dia. Uma chamada que ultrapasse o limite falhará e indicará quanto tempo aguardar antes de tentar novamente.
O que ele deliberadamente não expõe
O registro de ferramentas é controlado, e as exclusões são intencionais. Ele não fornece nenhum desses itens:
- um shell
- acesso ao Git
- o sistema de arquivos
- acesso bruto ao banco de dados
- HTTP interno arbitrário
- ferramentas de administração MCP de saída próprias do Coroid
Você ganha a capacidade de gerenciar tarefas — criar e inspecionar tarefas, planos, projetos e lançamentos — não um ambiente de execução remoto. Um cliente MCP não pode usar o Coroid para executar comandos arbitrários.
Para que ele é adequado
Gerencie o Coroid diretamente do seu ambiente de trabalho atual — seja um editor, assistente ou ferramenta interna — sem precisar acessar o portal. Criar uma tarefa pelo terminal ou solicitar ao assistente que verifique o que está bloqueado torna-se uma ação local.