Usa il server MCP

Questa guida mostra come collegare un client MCP esterno — Claude Code, un editor, l’MCP Inspector — al server di strumenti di Control Center.

Control Center registra 110 strumenti e li espone tramite il Model Context Protocol, alla versione di protocollo 2024-11-05. Intere famiglie di strumenti che ti aspetteresti sono assenti: non ci sono strumenti per riunioni o calendario e nessuno strumento per i progetti.

Trova l’endpoint

La superficie MCP condivide il listener principale di cc_server. Non esiste una porta MCP separata.

Endpoint	Metodo	Scopo
`/mcp`	`POST`	Trasporto Streamable HTTP — è quello che parla un client
`/mcp`	`DELETE`	Termina una sessione
`/sse`	`GET`	Flusso di notifiche server-sent

Quindi un’installazione locale predefinita è su http://127.0.0.1:9030/mcp.

Vai su Impostazioni → Server → Server MCP
Leggi la scheda Server MCP: mostra se è in esecuzione o arrestato e la porta su cui è in ascolto

La superficie è attiva per impostazione predefinita in un’installazione nuova, quindi un client loopback funziona senza toccare le impostazioni. Avvia all’apertura dell’app controlla se torna attiva dopo un riavvio; Avvia / Ferma sono controlli di sessione che non modificano quella preferenza.

Il server si associa al loopback per impostazione predefinita, quindi l’endpoint è raggiungibile solo dalla macchina su cui è in esecuzione cc_server, a meno che tu non l’abbia avviato con --bind any.

Collega un client

Punta il tuo client sull’endpoint Streamable HTTP. La forma esatta della configurazione dipende dal tuo client; l’URL è lo stesso in ogni caso.

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

Claude Code

Claude Code non lo rileverà da un .mcp.json di progetto: subordina i server MCP con ambito di progetto a un prompt di approvazione a cui un claude -p non interattivo non risponde mai. Passa la configurazione esplicitamente:

claude --mcp-config /path/to/mcp.json --strict-mcp-config

--strict-mcp-config fa usare a Claude solo quel file, così lo stesso server non viene anche rilevato dal progetto e registrato due volte.

Verifica: chiedi al client di elencare i suoi strumenti. Dovresti vedere voci mcp__* che coprono ticket, spazi, memoria, grafo del codice e revisione.

Esponi MCP oltre l’host

Su Impostazioni → Server → Server MCP, sulla riga Token di autenticazione, premi Imposta token e incolla un token
Invialo come Authorization: Bearer <token> a ogni richiesta POST /mcp

Una superficie priva di token rifiuta con 403 qualsiasi chiamante non loopback. È una negazione predefinita ed è voluta: è il token a rendere possibile il servizio da un’altra macchina.

Le modifiche al token si applicano immediatamente alla superficie attiva: nessun riavvio.

Limita ogni chiamata a uno spazio di lavoro

Ogni strumento che tocca dati con ambito di spazio di lavoro richiede workspace_id, e una chiamata che ne è priva viene rifiutata invece di essere risolta su uno spazio di lavoro «corrente»:

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

L’id è quello presente nell’URL del browser o dell’app: /workspaces/<workspace_id>/…. Le uniche eccezioni sono gli strumenti che abbracciano davvero più spazi di lavoro, come list_workspaces e gli strumenti delle notizie: le notizie sono per utente e un agente non ha un utente proprio, quindi quegli strumenti operano sui feed del proprietario del server.

Gli strumenti con ambito di repository verificano inoltre che il repository sia collegato a quello spazio di lavoro.

Scopri cosa rifiuterà la superficie

Controllo tramite modalità. Una chiamata viene risolta lato server in base alla modalità dello spazio dell’agente chiamante. Un agente in una modalità di sola lettura non può raggiungere uno strumento di scrittura omettendo space_id: la modalità viene invece ricavata dalla sua esecuzione attiva.
Guardrail delle azioni. Gli strumenti che modificano lo stato dichiarano le loro classi di effetto e passano dalla stessa policy usata dal resto del prodotto. Vedi Configura i guardrail.
Conferma. Alcuni strumenti distruttivi costruiscono un payload di conferma che deve essere approvato prima che la chiamata proceda.

Il catalogo completo viene annunciato in tools/list senza alcun filtro in fase di scoperta: un client MCP esterno rifiuta di chiamare uno strumento che non è nella sua lista memorizzata nella cache, quindi nascondere gli strumenti li rompe invece di rimetterli in ordine.

Risoluzione dei problemi

Il client non vede alcuno strumento

Controlla che la scheda Server MCP indichi che è in esecuzione
Controlla che la porta corrisponda a quella del tuo cc_server
Su Claude Code, controlla di aver passato --mcp-config e --strict-mcp-config

403 da una macchina che non è il server

Non è configurato alcun token bearer. Impostane uno e invialo.

Una chiamata a uno strumento fallisce con «Missing or invalid argument: workspace_id»

Aggiungi workspace_id. Non esiste uno spazio di lavoro implicito.

Una chiamata a uno strumento viene rifiutata come sconosciuta

Strumenti MCP elenca il catalogo. Usa il nome esattamente come compare lì.

Guide correlate

Concetti correlati

Architettura