Ferramentas MCP

O cc_server aloja um único registo de ferramentas MCP (JSON-RPC 2.0), servido na porta principal do servidor (predefinida: 9030) em POST /mcp e GET /sse, com a versão de protocolo 2024-11-05. Todos os clientes chegam ao mesmo registo: a aplicação de ambiente de trabalho, a build web, os clientes MCP externos e o runtime de agentes integrado. Os servidores MCP externos podem ser ligados ao mesmo registo como uma camada dinâmica.

Dimensão do registo

Medida	Quantidade
Ferramentas registadas pelo `cc_server`	110
De `packages/cc_mcp`	108
De `packages/cc_mcp_client` (deteção de ferramentas)	2
Registadas no registo base (`server_mcp_registry.dart`)	63
Registadas após o arranque, à medida que os respetivos serviços ficam operacionais (`cc_server_runtime.dart`)	47
Das 63 do registo base, condicionais a um repositório de grafo de código	5

As cinco ferramentas de grafo de código só são registadas quando o anfitrião passa um repositório de grafo de código a buildServerMcpRegistry. O cc_server passa sempre um, pelo que todas as 110 estão ativas no binário distribuído.

O registo completo é anunciado em tools/list, sem restrição de deteção. As edições de tickets são ferramentas tipadas.

Parâmetros comuns

`workspace_id`

Obrigatório em todas as ferramentas que tocam dados no âmbito de um espaço de trabalho. Um workspace_id em falta ou inválido devolve um erro explícito, e um valor que não corresponda ao espaço de trabalho da entidade de destino é rejeitado em vez de ignorado em silêncio. Omita-o nas ferramentas genuinamente globais: list_workspaces e as seis ferramentas do feed de notícias (list_feeds, list_articles, get_article, set_article_read, set_article_saved, refresh_feeds), que usam a lista de feeds por utilizador do proprietário do servidor. As ferramentas de deteção (search_tool_bm25, list_my_tools) aceitam-no opcionalmente, para poderem classificar o que é invocável consoante o modo de conversa. Quando é o servidor que despacha um agente, o espaço de trabalho é imposto do lado do servidor, pelo que o agente não consegue alcançar outro espaço de trabalho passando um id alheio.

Deteção de ferramentas

Ambas vêm do cc_mcp_client, não do cc_mcp, e ambas consultam a proteção do modo, para indicarem o que é invocável no modo de conversa atual.

Ferramenta	Descrição
`search_tool_bm25`	Pesquisa o catálogo de ferramentas por palavra-chave; devolve as ferramentas correspondentes, os respetivos esquemas de argumentos e se cada uma pode ser invocada neste momento
`list_my_tools`	Lista as ferramentas que podem ser invocadas neste momento nesta conversa, filtradas pelo respetivo modo

Uma terceira ferramenta de deteção, search_tools, existe apenas dentro do harness integrado e não faz parte deste registo MCP. Classifica a própria superfície de ferramentas da execução e, ao contrário de search_tool_bm25, carrega os esquemas do que encontra, para que o agente possa invocar uma correspondência no turno seguinte. Os agentes no harness devem preferi-la; os clientes MCP têm search_tool_bm25.

Ferramentas de agente

Ferramenta	Descrição
`list_agents`	Lista os agentes registados num espaço de trabalho

Mensagens e delegação entre agentes pares

Os agentes comunicam entre si através de espaços (duráveis, visíveis no roster). O ask_agent é um pedido/resposta com um tempo limite obrigatório; o delegate_task é protegido do lado do servidor por limite de profundidade, deteção de ciclos, envelope orçamental e teto de autonomia.

Ferramenta	Descrição
`send_to_agent`	Envia uma mensagem unidirecional a outro agente, endereçada por `to_agent_id` ou por `to_agent_name` exato
`ask_agent`	Coloca uma pergunta a outro agente e aguarda a resposta, ou expira
`delegate_task`	Delega uma tarefa a outro agente como ticket acompanhado
`consult_agent`	Adiciona ao espaço o especialista que melhor corresponde em termos de skills e despacha-o com um briefing focado
`todo_read`	Lê a lista de tarefas persistida desta conversa

Ferramentas de skills

Todas as instalações e atualizações passam por uma verificação que falha em modo fechado antes de qualquer conteúdo de skill chegar ao disco ou a um prompt de agente.

Ferramenta	Descrição
`list_skills`	Lista os slugs de skills disponíveis num espaço de trabalho
`create_skill`	Cria uma nova skill a partir de conteúdo markdown
`install_skill`	Instala o diretório completo de uma skill a partir de um repositório GitHub numa ref fixada
`update_skill`	Atualiza uma skill do GitHub instalada para uma nova ref, voltando a analisá-la e a fixá-la
`list_skill_updates`	Lista as skills com uma versão mais recente disponível
`verify_skills`	Verifica as skills bloqueadas face aos respetivos hashes de conteúdo em disco
`pin_skill`	Calcula o hash de uma skill existente em disco e regista-o em `skills-lock.json`

Ferramentas de planos, playbooks e artefactos

Ferramenta	Descrição
`submit_plan`	O contrato de saída do modo plano: emite um `PlanDocument` tipado que abre no Plan Studio
`create_playbook`	Guarda um plano como um modelo com nome e versão, com marcadores `{{param}}` tipados
`run_playbook`	Instancia um playbook com valores de parâmetros, produzindo um plano que o operador aprova
`publish_artifact`	Publica uma lista ordenada de blocos tipados (markdown, tabela, gráfico, mermaid, código, JSON) renderizados nativamente no cliente
`revise_artifact`	Substitui o conteúdo de um artefacto publicado
`list_artifacts`	Lista os artefactos do espaço de trabalho
`get_artifact`	Lê um artefacto
`complete_goal`	Declara alcançado o objetivo duradouro ativo da conversa (iniciado com `/goal` ou `/loop`)

Ferramentas de espaços de trabalho

Ferramenta	Descrição
`list_workspaces`	Lista todos os espaços de trabalho com os respetivos ids e nomes (global; sem `workspace_id`)

Ferramentas de repos

Ferramenta	Descrição
`list_repos`	Lista os repos registados num espaço de trabalho. Os agentes que a invocam recebem os caminhos das worktrees copy-on-write isoladas da sua conversa, nunca os checkouts originais

Ferramentas de mensagens

Ferramenta	Descrição
`list_spaces`	Lista os espaços de mensagens de um espaço de trabalho
`get_messages`	Obtém as mensagens de um espaço
`send_message`	Envia uma mensagem para um espaço como agente remetente com nome
`get_space_notes`	Lê o documento de transferência partilhado de um espaço
`update_space_notes`	Substitui o documento de transferência partilhado de um espaço
`todo_write`	Substitui a lista de tarefas desta conversa numa única chamada (passe a lista completa)

Ferramentas de revisão

Ferramenta	Descrição
`start_ai_review`	Inicia a revisão com IA de uma PR: calcula as áreas de revisão, distribui revisores especialistas pelo espaço da PR, redige o percurso guiado e finaliza
`add_review_node`	Adiciona uma constatação de revisão estruturada (ficheiro, linha, prioridade P0–P3) a um espaço de revisão
`confirm_review_node`	Confirma a constatação de um par; o autor não pode confirmar a sua própria
`resolve_review_node`	Marca uma constatação como corrigida depois de a alteração ser efetivamente feita; publica um registo no espaço de revisão
`dismiss_review_node`	Descarta uma constatação que não se aplica; regista um facto de supressão para que os revisores deixem de a assinalar
`request_peer_review`	Pede a outro agente revisor uma segunda análise de uma constatação
`dispatch_reviewers`	Despacha em simultâneo agentes revisores correspondentes para um espaço de revisão
`submit_reviewer_verdict`	Publica um veredicto ship/hold/block por revisor, com um nível de confiança e uma explicação
`finalize_review`	Calcula o consenso por nó e o veredicto por PR e fecha a revisão
`set_cohort_summary`	Define o resumo em linguagem simples de uma coorte de revisão
`add_review_diagram`	Anexa a uma coorte um diagrama estruturado e verificado pelo grafo (`sequence`, `entityRelation`, `stateMachine`)
`publish_review_to_github`	Publica a revisão finalizada no GitHub como comentários em linha e um corpo de resumo

Ferramentas de memória

Ferramenta	Descrição
`search_memory`	Pesquisa factos e políticas (por palavra-chave, semântica ou híbrida — híbrida é a predefinição)
`propose_fact`	Armazena um facto curto em markdown num domínio
`supersede_fact`	Marca um facto como substituído por outro
`propose_policy`	Armazena uma regra normativa num domínio (requer permissão de escrita sobre ele)
`supersede_policy`	Retira uma política — marca-a como inativa, mantendo-a para auditoria
`list_policies`	Lista as políticas ativas, opcionalmente filtradas por domínio
`list_memory_domains`	Lista os domínios de memória do espaço de trabalho, com a contagem de factos e políticas
`record_observation`	Regista uma observação em bruto na memória de trabalho do agente
`get_my_notes`	Lê o bloco de notas da memória de trabalho do agente que a invoca
`update_my_notes`	Atualiza o bloco de notas da memória de trabalho do agente que a invoca
`remember`	Adiciona uma nota à memória de trabalho quente do agente para esta sessão (limitada por TTL e por número)
`consolidate_memory`	Executa uma passagem de consolidação («sono»): remove os itens quentes expirados e transfere os duradouros para factos de longo prazo
`harmonize_memory`	Executa a harmonização de crenças entre agentes (SHMR) e assinala contradições
`list_memory_conflicts`	Lista as contradições detetadas e a forma como cada uma foi resolvida

Ferramentas de governação

Ferramenta	Descrição
`create_goal`	Cria um objetivo organizacional (ao nível da empresa, da equipa, do agente ou da tarefa)
`list_goals`	Lista objetivos com o nível, o estado e o progresso agregado
`update_goal_progress`	Define o progresso de um objetivo
`create_approval`	Abre uma aprovação do conselho para uma ação governada (saída do modo de plano, merge, lançamento, contratação, personalizada)
`list_approvals`	Lista as aprovações, opcionalmente filtradas por estado
`decide_approval`	Regista uma decisão: aprovar, rejeitar, pedir revisão ou reenviar
`comment_approval`	Comenta uma aprovação do conselho
`exit_plan_mode`	Abre (e, depois de aprovada, consome) uma aprovação `plan_exit`, retirando a conversa do modo de plano
`agent_heartbeat`	Comunica a vivacidade (alive, idle, stuck); o silêncio faz a saúde do runtime passar a recently-lost e depois a offline
`list_runtime_health`	Lista a saúde do runtime de cada agente
`list_agent_presence`	Lista a presença de cada agente (saúde, ciclo de vida, contagens em execução e em fila, capacidade)
`get_org_chart`	Lê a árvore de reporte, com o CEO na raiz, aninhada por `reports_to`
`create_work_product`	Cria um entregável duradouro associado a um ticket
`save_work_product_revision`	Guarda uma nova revisão; passe `base_revision_id` para ser rejeitado numa edição em simultâneo
`list_work_products`	Lista os produtos de trabalho, opcionalmente filtrados para um único ticket
`get_work_product`	Lê um produto de trabalho com o respetivo histórico de revisões
`create_runtime_profile`	Define um perfil de runtime reutilizável (família de protocolos, comando CLI, argumentos de arranque fixos)
`list_runtime_profiles`	Lista os perfis de runtime do espaço de trabalho

Ferramentas de grafo de código

Só são registadas quando o anfitrião fornece um repositório de grafo de código. O índice abrange o conjunto de gramáticas distribuído (Dart, JS/TS, PHP, Python, Rust, Zig, C/C++, Go, Java, Ruby, C#, Swift, Kotlin, R, Assembly, MATLAB, Ada); os símbolos de qualquer outra linguagem não estão presentes.

Ferramenta	Descrição
`search_code`	Pesquisa símbolos indexados por nome, assinatura e comentário de documentação (BM25 + semântica híbrido)
`code_symbol`	Procura símbolos por nome exato; devolve `file:line` e a assinatura
`code_callers`	Lista os símbolos que invocam ou dependem de um símbolo (arestas de entrada)
`code_callees`	Lista os símbolos que um símbolo invoca ou de que depende (arestas de saída)
`code_impact`	Calcula o raio de impacto transitivo de um símbolo, até uma determinada profundidade

Ferramentas de tickets

Ferramenta	Descrição
`create_ticket`	Cria um ticket no fornecedor configurado
`get_ticket`	Obtém um ticket pelo id
`list_tickets`	Lista tickets, opcionalmente filtrados por estado ou responsável
`update_ticket`	Atualiza o estado, o título, a descrição, a prioridade ou as etiquetas (o estado aceita aliases como `in_progress` / `completed`)
`assign_ticket`	Atribui um ticket a um agente e/ou a uma equipa
`reassign_ticket`	Reatribui um ticket a um agente diferente
`add_ticket_collaborator`	Convida um agente a colaborar num ticket (adicionado ao respetivo espaço)
`comment_on_ticket`	Comenta um ticket
`close_ticket`	Fecha um ticket (marca-o como concluído) com saída opcional
`fail_ticket`	Marca um ticket como falhado, com uma mensagem de erro
`delegate_ticket`	Delega um ticket a um agente, criando um ticket acompanhado
`ticket_pr_link`	Associa ou desassocia um ticket e uma pull request pelo id de nó da PR (`action`: `link` \| `unlink`)
`ticket_relation`	Adiciona ou remove uma relação entre dois tickets — `blocked_by`, `blocking`, `related_to`, `duplicate_of`, `duplicated_by`, `sub_issue_of`, `parent_of` (`action`: `add` \| `remove`)
`list_ticket_relations`	Lista o ticket principal, os sub-tickets e as ligações de dependência de um ticket

Ferramentas de equipas e pipelines

Ferramenta	Descrição
`record_team_activity`	Regista uma entrada de atividade de um líder de equipa num ticket
`preview_trigger`	Pré-visualiza quais execuções de pipeline um evento hipotético iniciaria, sem registar nada
`submit_output`	Submete a carga de saída estruturada para a execução de pipeline atual de quem a invoca; validada face ao esquema de saída declarado pela execução

Ferramentas de orquestração

Ferramenta	Descrição
`propose_orchestration`	Emite um plano de orquestração multiagente estruturado para uma única aprovação prévia; valida e devolve eventuais violações

Ferramentas do feed de notícias

Ferramenta	Descrição
`list_feeds`	Lista os feeds RSS/Atom registados
`list_articles`	Lista artigos, opcionalmente filtrados por feed, não lidos ou guardados
`get_article`	Obtém um artigo
`set_article_read`	Marca um artigo como lido ou não lido
`set_article_saved`	Guarda ou deixa de guardar um artigo
`refresh_feeds`	Obtém novamente todos os feeds ativados neste momento

Ferramentas de recinto (rig)

Controlam máquinas descartáveis — um navegador ou ambiente de trabalho Linux em recinto fechado, um emulador Android ou um iOS Simulator — a partir de dentro de uma execução. Registadas após o arranque, incondicionalmente: saber se uma máquina consegue de facto arrancar é uma questão de sondagem que as ferramentas respondem a cada chamada. Chamadas repetidas numa mesma conversa reutilizam a mesma máquina; as capturas de ecrã são devolvidas como conteúdo de imagem, com um orçamento de uma imagem por resultado, e o conteúdo de página/interface extraído é delimitado como dados não fidedignos. As quatro ferramentas de utilização, mais a rig_close, declaram a classe de ação enclosureControl (as ferramentas de utilização declaram também networkEgress e processSpawn; a mobile_use e a ios_use declaram ainda packageInstall), pelo que os modos só de leitura as negam. A rig_list não declara nenhuma — apenas lê o estado do espaço de trabalho. O vocabulário completo de verbos por superfície está na referência de Rigs.

Ferramenta	Descrição
`computer_use`	Controla um ambiente de trabalho Linux numa VM em recinto fechado: mover, clicar, arrastar, deslocar, escrever, redimensionar, área de transferência, captura de ecrã
`browser_use`	Controla um Chromium, Firefox ou WebKit headless (`engine`): navegar, clicar, preencher, extrair (a11y/DOM/consola), área de transferência, captura de ecrã
`mobile_use`	Controla o Android através de ADB: inspecionar/introduzir, capturas de ecrã, instalar/iniciar/parar/reiniciar/desinstalar aplicações, links diretos e comandos de dispositivo em formato argv
`ios_use`	Controla o iOS Simulator através de WebDriverAgent/CoreSimulator: inspecionar/introduzir, capturas de ecrã, instalar/iniciar/parar/desinstalar aplicações, links diretos e processos de simulador em formato argv
`rig_list`	Lista os rigs de um espaço de trabalho com a superfície, o estado, o tamanho do ecrã e o controlador
`rig_close`	Destrói um rig e descarta o estado da máquina que lhe pertence

Não expostas por MCP

O calendário e as reuniões não têm ferramentas MCP. Os agentes não conseguem ler o seu calendário, as reuniões, as transcrições, os itens de ação ou as decisões. O resumo que produz os itens de ação e as decisões é executado como o pipeline meeting_summary integrado, e não como uma ferramenta que um agente possa invocar.

Restrição de ferramentas por modo

A restrição é imposta duas vezes a partir de uma única tabela (ModeToolPolicy): uma vez no despachante MCP do adaptador Claude Code e outra no registo do harness integrado. Uma chamada bloqueada devolve o motivo.

Modo	Superfície de ferramentas
`chat`	Todas as ferramentas registadas; sem lista de autorizações
`plan`	Uma lista de autorizações escolhida a dedo. Sem escritas na worktree e sem os verbos de ticket `create` / `assign` / `delegate`, mas são permitidas a memória, os artefactos, as listas de tarefas, `submit_plan`, `exit_plan_mode` e os verbos de conclusão de tickets no ticket despachado
`review`	Uma lista de autorizações escolhida a dedo: participação em revisões, comunicação, obtenção de contexto só de leitura e o conjunto completo de verbos de tickets, incluindo `create_ticket` e `assign_ticket`
`orchestrate`	Uma lista de autorizações escolhida a dedo: ferramentas de investigação e de leitura, mais `propose_orchestration`, `create_playbook` e `run_playbook`. A contratação, a decomposição e a conclusão de tickets acontecem de forma determinística após a aprovação, nunca a meio da execução

Permitidas em todos os modos, independentemente da lista de autorizações:

Conjunto	Ferramentas
Memória e artefactos	`search_memory`, `propose_fact`, `propose_policy`, `supersede_fact`, `supersede_policy`, `record_observation`, `update_my_notes`, `get_my_notes`, `list_memory_domains`, `list_policies`, `publish_artifact`, `revise_artifact`, `list_artifacts`, `get_artifact`
Grafo de código	`search_code`, `code_symbol`, `code_callers`, `code_callees`, `code_impact`
Mecânica de execução	`search_tool_bm25`, `list_my_tools`, `todo_write`, `todo_read`

Estar numa lista de autorizações não torna uma ferramenta invocável, e o inverso também é verdade: a capacidade de colocar perguntas ao operador é uma ferramenta do harness (ask_user), pelo que nunca aparece neste catálogo MCP.

Ferramentas sujeitas a aprovação

Uma ferramenta pode declarar requiresApproval. O despachante constrói então um ApprovalPayload e apresenta-o através do ConfirmationPort antes de a ferramenta ser executada; o cc_server liga essa porta, pelo que o portão está ativo.

Ferramentas registadas que o declaram: create_ticket, update_ticket, assign_ticket, reassign_ticket, close_ticket, ticket_relation, create_goal, update_goal_progress, create_approval, decide_approval, comment_approval, create_work_product, save_work_product_revision, create_runtime_profile, install_skill, update_skill.

De forma independente, as barreiras de ação unificadas restringem qualquer ferramenta que declare um conjunto ActionClass não vazio. Uma decisão prompt sem nenhum aprovador ligado é negada. Ver Barreiras.

Capacidades sem ferramenta por trás

Nem todas as capacidades do produto são acessíveis a um agente. Estas não têm ferramenta nenhuma, pelo que um nome que possa ter visto referido noutro sítio devolve «unknown tool»:

Capacidade	Onde reside em alternativa
Contratar, despedir ou editar um agente	A interface de agentes. Não existe a ferramenta `hire_agent` / `fire_agent` / `update_agent`
Criar um espaço de trabalho	`workspace.upsert` por RPC, que inicializa e marca a propriedade
Projetos (criar / listar / atualizar / colocar um ticket)	A interface de tickets. Os projetos são uma superfície do operador — ver Projetos
Colocar ao operador uma pergunta bloqueante	A ferramenta `ask_user` do harness, não o MCP. Apresenta um formulário na conversa e bloqueia à espera da resposta
Diagnósticos por agente	Nada. Não existe `doctor` — ver Diagnóstico de um agente
Calendário e reuniões	RPC apenas para clientes humanos (ver acima)