Pular para o conteúdo

Usar o servidor MCP

Este guia mostra como conectar um cliente MCP externo — Claude Code, um editor, o MCP Inspector — ao próprio servidor de ferramentas do Control Center.

O Control Center registra 110 ferramentas e as serve pelo Model Context Protocol na versão de protocolo 2024-11-05. Famílias inteiras de ferramentas que você poderia esperar estão ausentes: não há ferramentas de reunião nem de calendário, e nenhuma ferramenta de projeto.

A superfície MCP compartilha o listener principal do cc_server. Não existe uma porta MCP separada.

Endpoint Método Finalidade
/mcp POST Transporte Streamable HTTP — é o que um cliente fala
/mcp DELETE Encerrar uma sessão
/sse GET Fluxo de notificações enviadas pelo servidor

Assim, uma instalação local padrão fica em http://127.0.0.1:9030/mcp.

  1. Vá em Configurações → Servidor → Servidores MCP
  2. Leia o cartão Servidor MCP — ele mostra se está em execução ou parado e a porta em que está escutando

A superfície vem ativada por padrão em uma instalação nova. Somente o proprietário do servidor vê o token do cartão, e somente ele pode iniciar ou parar o endpoint. Iniciar ao abrir o app controla se ela volta depois de uma reinicialização; Iniciar / Parar são controles de sessão que não mudam essa preferência.

Por padrão, o servidor se vincula ao loopback, então o endpoint só é acessível a partir da máquina em que o cc_server roda, a menos que você o tenha iniciado com --bind any.

Toda requisição precisa do token MCP do servidor, de qualquer máquina, inclusive do loopback. O servidor o cria na primeira vez que inicia. Não há como desligá-lo nem como apagá-lo.

  1. Em Configurações → Servidor → Servidores MCP, encontre a linha Token de autenticação
  2. Pressione Mostrar token e copie-o
  3. Para substituí-lo, pressione Rotacionar token. O servidor passa para o novo token imediatamente, e todo cliente que ainda usar o antigo é recusado até que você lhe dê o novo

Aponte seu cliente para o endpoint Streamable HTTP e envie o token como Authorization: Bearer <token> em toda requisição, inclusive GET /sse. Não há outra forma de enviá-lo: um token na URL não é aceito. O formato exato da configuração é problema do seu cliente.

{
"mcpServers": {
"control-center": {
"type": "http",
"url": "http://127.0.0.1:9030/mcp",
"headers": { "Authorization": "Bearer <token>" }
}
}
}

O Claude Code não capta isso de um .mcp.json de projeto — ele deixa os servidores MCP com escopo de projeto atrás de um prompt de aprovação que um claude -p não interativo nunca responde. Passe a configuração explicitamente:

Janela do terminal
claude --mcp-config /path/to/mcp.json --strict-mcp-config

--strict-mcp-config faz o Claude usar apenas esse arquivo, para que o mesmo servidor não seja também descoberto no projeto e registrado duas vezes.

Ponto de verificação: peça ao cliente para listar as ferramentas dele. Você deve ver entradas mcp__* cobrindo tickets, espaços, memória, grafo de código e revisão.

O token abre todas as ferramentas do servidor, então o endpoint também recusa qualquer coisa que uma página web poderia ter enviado, antes de olhar o token:

Requisição Resposta
Um cabeçalho Origin que não é uma página desta máquina (http://localhost, http://127.0.0.1 ou http://[::1], em qualquer porta) 403, “Cross-origin requests are not accepted”
Um cabeçalho Host que não é o endereço de loopback e a porta deste listener nem o nome de host público do servidor 403, “Unknown host”
Um POST cujo corpo não é application/json 415
Nenhum token, ou um token errado 401

Para servir MCP além do host, inicie o servidor com --bind any e envie o token da outra máquina, endereçando o servidor pelo nome de host público dele.

Toda ferramenta que toca dados com escopo de espaço de trabalho exige workspace_id, e uma chamada sem ele é recusada em vez de resolvida contra algum espaço de trabalho “atual”:

{
"workspace_id": "acme",
"title": "Fix login bug",
"priority": "high"
}

O id é o que aparece na URL do navegador ou do app: /workspaces/<workspace_id>/…. As únicas exceções são ferramentas que realmente abrangem espaços de trabalho, como list_workspaces e as ferramentas do feed de notícias — o feed de notícias é por usuário e um agente não tem usuário próprio, então essas ferramentas operam sobre os feeds do dono do servidor.

As ferramentas com escopo de repo também verificam se o repo está vinculado a esse espaço de trabalho.

  • Restrição por modo. Uma chamada é resolvida no servidor conforme o modo do espaço do agente que a faz. Um agente em um modo somente leitura não consegue alcançar uma ferramenta de escrita omitindo space_id — o modo é consultado a partir da execução ativa dele.
  • Guardrails de ação. As ferramentas de mutação declaram suas classes de efeito e passam pela mesma política que o resto do produto usa. Consulte Configurar guardrails.
  • Confirmação. Algumas ferramentas destrutivas montam um payload de confirmação que precisa ser aprovado antes de a chamada prosseguir.

O catálogo completo é anunciado em tools/list sem nenhuma restrição de descoberta — um cliente MCP externo se recusa a chamar uma ferramenta que não esteja na lista em cache dele, então esconder ferramentas as quebra em vez de organizá-las.

Servidores MCP pessoais continuam sendo do proprietário

Seção intitulada “Servidores MCP pessoais continuam sendo do proprietário”

Este guia trata do endpoint próprio do Control Center. A outra direção, os servidores MCP que o Control Center entrega aos agentes que ele executa, está listada em Configurações → Servidor → Servidores MCP → Servidores MCP externos. Servidores configurados na máquina do servidor para Claude, Codex, Cursor, Gemini, VS Code, Windsurf, OpenCode ou em um .mcp.json são encontrados ali automaticamente.

Esses servidores descobertos vêm da configuração de ferramentas do próprio usuário do servidor e agem com a identidade e as credenciais desse usuário; por isso pertencem ao proprietário do servidor:

  • Ficam disponíveis somente dentro de execuções do harness integrado que o proprietário do servidor inicia ou pelas quais é responsável, incluindo automações em um espaço de trabalho pelo qual o proprietário é responsável.
  • A execução de um membro, a automação vinculada a um membro e toda execução em um servidor sem proprietário registrado não recebem nenhum deles. Ali as ferramentas não aparecem na lista, não podem ser chamadas e não surgem na busca de ferramentas.
  • Este endpoint nunca lista, chama nem busca esses servidores, para ninguém, nem mesmo com o token do proprietário, e não repassa os recursos ou prompts deles. Assim, um CLI de agente que alcança o Control Center por MCP, como o Claude Code, também não os recebe pelo Control Center; ele usa a própria configuração.

Os servidores MCP configurados para o espaço de trabalho não são afetados por nada disso.

  • Verifique se o cartão Servidor MCP indica que está em execução
  • Verifique se a porta corresponde à porta do seu cc_server
  • No Claude Code, verifique se você passou --mcp-config e --strict-mcp-config

A requisição não trouxe token, ou trouxe um antigo. Copie o token atual da linha Token de autenticação e envie-o como Authorization: Bearer <token>. Um token na URL é ignorado.

A requisição trouxe um Origin de uma página web, ou um Host que o servidor não reconhece. Chame o endpoint a partir de um cliente, e não de uma página do navegador, pelo endereço de loopback do servidor ou pelo nome de host público dele.

Envie os corpos de POST /mcp como application/json.

Uma chamada de ferramenta falha com “Missing or invalid argument: workspace_id”

Seção intitulada “Uma chamada de ferramenta falha com “Missing or invalid argument: workspace_id””

Adicione workspace_id. Não existe espaço de trabalho implícito.

Uma chamada de ferramenta é recusada como desconhecida

Seção intitulada “Uma chamada de ferramenta é recusada como desconhecida”

Ferramentas MCP lista o catálogo. Chame o nome exatamente como ele aparece lá.