Usar o servidor MCP

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

O Control Center regista 110 ferramentas e serve-as através do Model Context Protocol, na versão de protocolo 2024-11-05. Faltam famílias inteiras de ferramentas que poderia esperar: não há ferramentas de reuniões nem de calendário e não há ferramentas de projetos.

Encontrar o endpoint

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

Endpoint	Método	Objetivo
/mcp	POST	Transporte HTTP streamable — é o que um cliente utiliza
/mcp	DELETE	Terminar uma sessão
/sse	GET	Fluxo de notificações enviado pelo servidor

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

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

A superfície está ativa por predefinição numa instalação nova, pelo que um cliente loopback funciona sem mexer nas definições. Iniciar ao abrir a aplicação controla se volta depois de um reinício; Iniciar / Parar são controlos de sessão que não alteram essa preferência.

Por predefinição, o servidor liga-se a loopback, pelo que o endpoint só é acessível a partir da máquina onde o cc_server corre, a menos que o tenha iniciado com --bind any.

Ligar um cliente

Aponte o seu cliente ao endpoint HTTP streamable. A forma exata da configuração é uma questão do seu cliente; o URL é o mesmo de qualquer das formas.

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

Claude Code

O Claude Code não deteta isto a partir de um .mcp.json de projeto — coloca os servidores MCP com âmbito de projeto atrás de um pedido 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 com que o Claude use apenas esse ficheiro, para que o mesmo servidor não seja também detetado a partir do projeto e registado duas vezes.

Ponto de verificação: peça ao cliente para listar as suas ferramentas. Deverá ver entradas mcp__* que abrangem tickets, espaços, memória, grafo de código e revisão.

Servir MCP para além do anfitrião

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

Uma superfície sem token recusa qualquer autor de chamada não-loopback com 403. Isso é fail-closed por conceção: é o token que torna possível, de todo, o serviço fora do anfitrião.

As alterações ao token aplicam-se imediatamente à superfície em execução — sem reinício.

GET /sse recebe o token na query string

O fluxo de notificações é verificado por token como todas as outras rotas, mas um EventSource do navegador não consegue enviar um cabeçalho Authorization — por isso /sse também aceita o token como ?token=<token>. Sem ele, responde 401.

Limitar cada chamada a um espaço de trabalho

Todas as ferramentas que tocam dados com âmbito de espaço de trabalho exigem workspace_id, e uma chamada sem ele é recusada em vez de resolvida contra um qualquer espaço de trabalho «atual»:

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

O id é o que aparece no URL do seu navegador ou da aplicação: /workspaces/<workspace_id>/…. As únicas exceções são as ferramentas que abrangem genuinamente vários espaços de trabalho, como list_workspaces e as ferramentas do feed de notícias — o feed de notícias é por utilizador e um agente não tem utilizador próprio, pelo que essas ferramentas operam sobre os feeds do proprietário do servidor.

As ferramentas com âmbito de repo verificam ainda que o repo está ligado a esse espaço de trabalho.

Saber o que a superfície vai recusar

• Restrição por modo. Uma chamada é resolvida no servidor em função do modo do espaço do agente que a faz. Um agente num modo só de leitura não consegue chegar a uma ferramenta de escrita omitindo space_id — o modo é procurado a partir da sua execução ativa.
• Guardrails de ação. As ferramentas mutáveis declaram as suas classes de efeitos e passam pela mesma política que o resto do produto usa. Consulte Configurar guardrails.
• Confirmação. Algumas ferramentas destrutivas constroem um payload de confirmação que tem de ser aprovado antes de a chamada prosseguir.

O catálogo completo é anunciado em tools/list, sem restrição de deteção — um cliente MCP externo recusa chamar uma ferramenta que não esteja na sua lista em cache, pelo que esconder ferramentas quebra-as em vez de as arrumar.

Resolução de problemas

O cliente não vê ferramentas

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

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

Não há nenhum token bearer configurado. Defina um e envie-o.

Uma chamada de ferramenta falha com «Missing or invalid argument: workspace_id»

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

Uma chamada de ferramenta é recusada como desconhecida

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

Guias relacionados

• Ferramentas MCP
• Configurar guardrails
• Executar um servidor headless

Conceitos relacionados

• Arquitetura