Coroid como um servidor MCP

Coroid expõe um servidor de Protocolo de Contexto de Modelo (MCP) remoto. Um assistente ou agente externo, como Hermes, Codex, Claude Code ou Cursor, 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 abrange 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/mcp

O transporte é HTTP Streamable sem estado. Autentique-se com OAuth ou um token de acesso pessoal.

O que está habilitado#

Coroid habilita os recursos de MCP em etapas, para todas as organizações ao mesmo tempo.

Enquanto um recurso não estiver ativado, os clientes não verão suas ferramentas e o Coroid recusará chamadas a 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 somente de leitura; portanto, peça os escopos necessários, como faz o Codex.

Hermes#

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

Com um token de acesso em vez disso:

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

Forneça o token ao Hermes quando ele solicitá-lo. Armazene-o no repositório de credenciais do Hermes, e 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.delivery

Com 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_TOKEN

Claude Code#

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

Execute 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/mcp

Cursor#

Adicione o Coroid a ~/.cursor/mcp.json, ou a .cursor/mcp.json em um repositório para compartilhar a configuração com todos que trabalham nele:

{
  "mcpServers": {
    "coroid": {
      "url": "https://api.coroid.ai/mcp"
    }
  }
}

O Cursor faz login via OAuth: aprove a conexão no seu navegador quando solicitado. Verifique os escopos nessa tela, pois uma conexão sem escopos de escrita só permite leitura.

Com um token de acesso em vez disso:

{
  "mcpServers": {
    "coroid": {
      "url": "https://api.coroid.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${env:COROID_MCP_TOKEN}"
      }
    }
  }
}

Defina COROID_MCP_TOKEN no ambiente a partir do qual o Cursor é iniciado. Um .cursor/mcp.json em um repositório é commitado junto com ele; portanto, coloque a variável lá, nunca o token.

Outros clientes#

Qualquer cliente que suporte servidores MCP remotos via HTTP Streamable pode se conectar. O Coroid publica metadados OAuth para o endpoint e suporta registro dinâmico de clientes com PKCE. Um cliente sem OAuth pode enviar um token de acesso como token bearer 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. 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ó. Assim, revogar o acesso de um único cliente é 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 acessa 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 repositório 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.

Somente um Administrador ou Proprietário pode conceder um escopo cujo nível mínimo de permissão seja Administrador. Somente um Proprietário pode conceder um escopo cujo nível mínimo de permissão seja Proprietário.

Uma conexão limitada a alguns projetos não consegue acessar nada em outros projetos, mesmo por meio do 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#

Sua lista de clientes mostra apenas as ferramentas ativadas e permitidas pelos seus escopos e função. A coluna de aprovação indica o que acontece quando uma ferramenta é chamada:

Leitura#

Essas ferramentas exigem a função de Revisor e este escopo: mcp.read. Nenhuma delas precisa de aprovação.

Para saber sobre as ferramentas de Lançamento, veja Lançamentos via MCP.

Regras de Anti-slop do seu editor#

As duas ferramentas de Anti-slop permitem que o próprio agente do desenvolvedor mantenha seu trabalho de acordo com os padrões que o Controle de Qualidade aplica a todo pull request, antes mesmo que o pull request exista.

• anti_slop_rules retorna a política de Anti-slop publicada do projeto: as regras e quais delas bloqueiam, regras personalizadas, regras em quarentena, quais novas dependências o Coroid pode procurar nos registros públicos e um trecho para AGENTS.md que define as mesmas regras para um agente local. Cole o trecho em AGENTS.md, ou em uma regra em .cursor/rules para Cursor.
• anti_slop_scan verifica um branch, tag ou commit que o Coroid sincronizou com uma base, o branch padrão a menos que você especifique outro. Ele apenas lê: não altera arquivos, não executa comandos, não instala nada e não chama modelo algum. É limitado a 5 chamadas por minuto.

Uma varredura é uma prévia. O Controle de Qualidade ainda verifica o pull request, e seu veredito é o que conta. Veja Verificações de Anti-slop.

Criar e alterar trabalho#

Essas ferramentas exigem a função de Membro e este escopo: mcp.work.write.

O trabalho criado via MCP não passa pela 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.

Executar trabalho#

Essas ferramentas exigem a função de Membro e este escopo: mcp.execute.

Entrega#

Essas ferramentas exigem a função de Membro e este escopo: mcp.delivery. Os Lançamentos têm sua própria seção abaixo.

Administração#

Essas ferramentas alteram a forma como a organização e seus projetos são configurados.

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ção do Coroid, grava o conteúdo em um pacote, visualiza o pacote e depois o aplica. Essas ferramentas exigem a função de Proprietário e o seguinte escopo: mcp.organization.admin.

Um pacote contém placeholders em vez de valores de segredo, e o Coroid rejeita um pacote que inclua um segredo. Veja Exportar e importar configurações.

Lançamentos via MCP#

As ferramentas de release são as mesmas usadas pelo assistente de chat e passam pelo mesmo processo de Release API do portal:

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 pela pipeline e se o Coroid verificou a versão em execução. Um token limitado a alguns projetos não consegue acessar lançamentos em outros projetos. O processo de Release API ainda aplica suas próprias regras de aprovação, então uma aprovação via MCP conta exatamente como uma no portal.

list_release_pull_requests retorna os pull requests abertos de um projeto na ordem proposta pelo Coroid, com o motivo para qualquer um que seja excluído. bundle_release_pull_requests cria um release a partir deles: uma branch de release com os pull requests mesclados na ordem correta e um pull request de release. Ele envia uma branch e abre um pull request, portanto sempre aguarda a intervenção de uma pessoa. Exclua prNumbers para usar a seleção do Coroid.

Aprovações e políticas de automação#

Aprovações é uma fila de ações aguardando intervenção humana. Políticas de automação decide o que deve entrar nessa fila.

Esse é o controle mais importante. Um cliente externo agindo em seu nome deve poder realizar tarefas rotineiras livremente e apenas coisas relevantes com aprovação humana. Defina as políticas antes de entregar um token a qualquer componente que rode 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. Um Proprietário ou administrador analisa a ferramenta e os argumentos exatos, depois aprova ou rejeita a chamada. A aprovação executa a chamada exatamente como foi feita, e o cliente não pode alterá-la depois. Uma chamada não aprovada em até 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 nomeia as ferramentas exatas, pode ser limitada a alguns projetos e restringe o número de chamadas por hora, por dia e simultaneamente. Ela também pode expirar. Revogar uma política revoga todos os tokens vinculados a ela. Ferramentas marcadas como Sempre nunca são cobertas por uma política.

Uma conexão OAuth não pode carregar uma política. Via 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. O Coroid então retorna o primeiro resultado em vez de agir duas vezes. Uma chave reutilizada com argumentos diferentes é recusada.

Uma alteração também retorna uma operação que registra seu status e resultado. Essas quatro ferramentas funcionam para toda conexão:

O servidor também disponibiliza esses recursos:

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 ultrapassar o limite falhará e indicará quanto tempo aguardar antes de tentar novamente.

O que deliberadamente não é exposto#

O registro de ferramentas é gerenciado e as exclusões são intencionais. Ele não fornece nada disso:

• um shell
• Acesso Git
• o sistema de arquivos
• acesso bruto a banco de dados
• HTTP interno arbitrário
• As próprias ferramentas de administração MCP de saída do Coroid

Você ganha a capacidade de gerenciar tarefas — criar e inspecionar tarefas, planos, projetos e versões — não é um ambiente de execução remota. Um cliente MCP não pode usar Coroid para executar comandos arbitrários.

Para que serve#

Utilizar o Coroid a partir do lugar onde você já trabalha — um editor, um assistente, uma ferramenta interna — sem precisar acessar o portal. Criar uma tarefa pelo seu terminal ou fazer com que um assistente verifique o que está bloqueado vira uma ação local.

Relacionados#

• Formas de começar a trabalhar
• Exportar e importar configurações
• Servidores MCP externos
• Assistente de Chat
• Procedência