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.

Encontrar o endpoint

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, então um cliente em loopback funciona sem mexer em nenhuma configuração. 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.

Conectar um cliente

Aponte seu cliente para o endpoint Streamable HTTP. O formato exato da configuração é problema do seu cliente; a URL é a mesma nos dois casos.

{
  "mcpServers": {
    "control-center": {
      "type": "http",
      "url": "http://127.0.0.1:9030/mcp"
    }
  }
}

Claude Code

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:

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.

Servir MCP além do host

1. Em Configurações → Servidor → Servidores MCP, na linha Token de autenticação, pressione Definir e cole um token
2. Envie-o como Authorization: Bearer <token> em toda requisição POST /mcp

Uma superfície sem token recusa com 403 qualquer chamador que não seja loopback. Isso é fail-closed por design: é o token que torna possível, afinal, o serviço fora do host.

Alterações no token se aplicam imediatamente à superfície ativa — sem reinicialização.

GET /sse recebe o token na query string

O fluxo de notificações passa pela verificação de token como qualquer outra rota, mas um EventSource de navegador não consegue enviar um cabeçalho Authorization — por isso /sse também aceita o token como ?token=<token>. Sem ele, responde 401.

Restringir cada chamada a um espaço de trabalho

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.

Saiba o que a superfície vai recusar

• 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.

Solução de problemas

O cliente não vê nenhuma ferramenta

• 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

403 de uma máquina que não é o servidor

Nenhum token Bearer está configurado. Defina um e envie-o.

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

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

Guias relacionados

• Ferramentas MCP
• Configurar guardrails
• Executar um servidor headless

Conceitos relacionados

• Arquitetura