Integrazione MCP di Cascade

MCP (Model Context Protocol) è un protocollo che consente agli LLM di accedere a strumenti e servizi personalizzati. Un client MCP (in questo caso, Cascade) può effettuare richieste ai server MCP per accedere agli strumenti che mettono a disposizione. Cascade ora si integra nativamente con MCP, consentendoti di usare in Cascade i server MCP che preferisci. Per ulteriori informazioni, consulta la documentazione ufficiale di MCP.

Gli utenti Enterprise devono attivare questa opzione manualmente da Settings

Aggiungere un nuovo plugin MCP

Puoi aggiungere nuovi plugin MCP dalla sezione Settings > Tools > Windsurf Settings > Add Server. Se non trovi il plugin MCP che vuoi usare, puoi aggiungerlo manualmente facendo clic sul pulsante View Raw Config e modificando il file mcp_config.json raw. Quando fai clic su un server MCP, ti basta fare clic su + Add Server per esporre il server e i relativi strumenti a Cascade.

Cascade supporta tre tipi di trasporto per i server MCP: stdio, Streamable HTTP e SSE. Cascade supporta anche OAuth per ogni tipo di trasporto. Per i server http, l’URL deve corrispondere a quello dell’endpoint e avere un formato simile a https://<your-server-url>/mcp.

Assicurati di premere il pulsante di aggiornamento dopo aver aggiunto un nuovo plugin MCP.

mcp_config.json

Il file ~/.codeium/mcp_config.json è un file JSON che contiene un elenco di server a cui Cascade può collegarsi. Ecco un esempio di configurazione che configura un singolo server per GitHub:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_PERSONAL_ACCESS_TOKEN>"
      }
    }
  }
}

Assicurati di fornire gli argomenti richiesti e le variabili d’ambiente per i server che intendi usare. Consulta il repository di riferimento ufficiale dei server MCP o OpenTools per alcuni esempi di server.

MCP HTTP remoti

È importante tenere presente che, per gli MCP HTTP remoti, la configurazione è leggermente diversa e richiede un campo serverUrl o url. Ecco un esempio di configurazione per un server HTTP:

{
  "mcpServers": {
    "remote-http-mcp": {
      "serverUrl": "<your-server-url>/mcp",
      "headers": {
        "API_KEY": "value"
      }
    }
  }
}

Interpolazione della configurazione

Il file ~/.codeium/mcp_config.json gestisce l’interpolazione delle variabili d’ambiente nei seguenti campi: command, args, env, serverUrl, url e headers. Ecco un esempio di configurazione che usa una variabile d’ambiente AUTH_TOKEN in headers.

{
  "mcpServers": {
    "remote-http-mcp": {
      "serverUrl": "<your-server-url>/mcp",
      "headers": {
        "API_KEY": "Bearer ${env:AUTH_TOKEN}"
      }
    }
  }
}

Controlli per gli amministratori (Team ed Enterprise)

Gli amministratori del team possono attivare o disattivare l’accesso a MCP per il proprio team, nonché inserire nella whitelist i server MCP approvati che il team può usare:

Settings MCP del team

Settings MCP configurabili per il tuo team.

Il collegamento sopra funzionerà solo se disponi dei privilegi di amministratore per il tuo team.

Per impostazione predefinita, gli utenti di un team possono configurare i propri server MCP. Tuttavia, una volta inserito nella whitelist anche un solo server MCP, tutti i server non presenti nella whitelist saranno bloccati per il tuo team.

Come funziona la corrispondenza dei server

Quando inserisci un server MCP nella whitelist, il sistema usa la corrispondenza tramite pattern regex secondo le seguenti regole:

Corrispondenza dell’intera stringa: tutti i pattern vengono ancorati automaticamente (racchiusi in ^(?:pattern)$) per evitare corrispondenze parziali
Campo comando: deve corrispondere esattamente oppure in base al pattern regex specificato
Array degli argomenti: ogni argomento viene confrontato singolarmente con il pattern corrispondente
Lunghezza dell’array: il numero di argomenti deve corrispondere esattamente tra la whitelist e la configurazione utente
Caratteri speciali: caratteri come $, ., [, ], (, ) hanno un significato speciale nelle regex e devono essere preceduti da \ se vuoi una corrispondenza letterale

Opzioni di configurazione

Opzione 1: impostazione predefinita del Plugin Store (consigliata)

Lascia vuoto il campo Server Config (JSON) per consentire l'uso della configurazione predefinita del Windsurf MCP Plugin Store.

Configurazione della whitelist Admin:

Server ID: github-mcp-server
Server Config (JSON): (lasciare vuoto)

{}

Configurazione utente corrispondente (mcp_config.json):

{
  "mcpServers": {
    "github-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

In questo modo, gli utenti possono installare il server GitHub MCP con qualsiasi configurazione valida, purché l’ID del server corrisponda alla voce nel plugin store.

Opzione 2: configurazione con corrispondenza esatta

Fornisci la configurazione esatta che gli utenti devono usare. Deve corrispondere esattamente a questa configurazione.

Configurazione della whitelist Admin:

Server ID: github-mcp-server
Server Config (JSON):

{
  "command": "docker",
  "args": [
    "run",
    "-i",
    "--rm",
    "-e",
    "GITHUB_PERSONAL_ACCESS_TOKEN",
    "ghcr.io/github/github-mcp-server"
  ],
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": ""
  }
}

Configurazione utente corrispondente (mcp_config.json):

{
  "mcpServers": {
    "github-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Gli utenti devono usare questa configurazione esatta: qualsiasi variazione nel comando o negli argomenti verrà bloccata. La sezione env può contenere valori diversi.

Opzione 3: pattern regex flessibili

Usa pattern regex per consentire variazioni nelle configurazioni utente, mantenendo i controlli di sicurezza.

Configurazione della whitelist Admin:

Server ID: python-mcp-server
Server Config (JSON):

{
  "command": "python3",
  "args": ["/.*\\.py", "--port", "[0-9]+"]
}

Configurazione utente corrispondente (mcp_config.json):

{
  "mcpServers": {
    "python-mcp-server": {
      "command": "python3",
      "args": ["/home/user/my_server.py", "--port", "8080"],
      "env": {
        "PYTHONPATH": "/home/user/mcp"
      }
    }
  }
}

Questo esempio offre flessibilità agli utenti mantenendo la sicurezza:

La regex /.*\\.py corrisponde a qualsiasi percorso di file Python, ad esempio /home/user/my_server.py
La regex [0-9]+ corrisponde a qualsiasi porta numerica, ad esempio 8080 o 3000
Gli utenti possono personalizzare i percorsi dei file e le porte, mentre gli admin garantiscono che vengano eseguiti solo script Python

Pattern regex comuni

Pattern	Corrisponde a	Esempio
`.*`	Qualsiasi stringa	`/home/user/script.py`
`[0-9]+`	Qualsiasi numero	`8080`, `3000`
`[a-zA-Z0-9_]+`	Alfanumerico + trattino basso	`api_key_123`
`\\$HOME`	`$HOME` letterale	`$HOME` (non espanso)
`\\.py`	`.py` letterale	`script.py`
`\\[cli\\]`	`[cli]` letterale	`mcp[cli]`

Note

Linee guida per la configurazione Admin

Variabili d’ambiente: la sezione env non è soggetta a corrispondenza regex e può essere configurata liberamente dagli utenti
Strumenti disabilitati: l’array disabledTools viene gestito separatamente e non rientra nella corrispondenza con la whitelist
Sensibilità a maiuscole e minuscole: tutte le corrispondenze distinguono tra maiuscole e minuscole
Gestione degli errori: i pattern regex non validi verranno registrati nei log e comporteranno il rifiuto dell’accesso
Testing: testa con attenzione i tuoi pattern regex: pattern troppo restrittivi possono bloccare casi d’uso legittimi

Risoluzione dei problemi

Se gli utenti segnalano che i loro server MCP non funzionano dopo essere stati inseriti nella whitelist:

Verifica della corrispondenza esatta: assicurati che il pattern della whitelist corrisponda esattamente alla configurazione dell’utente
Verifica dell’escape regex: i caratteri speciali potrebbero richiedere l’escape (ad es. \. per i punti letterali)
Controlla i log: i pattern regex non validi vengono registrati con avvisi
Testa i pattern: usa un tester regex per verificare che i tuoi pattern funzionino come previsto

Ricorda: una volta inserito un qualsiasi server nella whitelist, tutti gli altri server vengono automaticamente bloccati per i membri del tuo team.

Informazioni generali

Poiché le chiamate agli strumenti MCP possono invocare codice scritto da implementatori di server di terze parti, non ci assumiamo alcuna responsabilità per errori nelle chiamate agli strumenti MCP. Per ribadirlo:
Attualmente supportiamo strumenti, risorse e prompt di un server MCP.

Documentation Index

​Aggiungere un nuovo plugin MCP

​mcp_config.json

​MCP HTTP remoti

​Interpolazione della configurazione

​Controlli per gli amministratori (Team ed Enterprise)

Settings MCP del team

​Come funziona la corrispondenza dei server

​Opzioni di configurazione

​Pattern regex comuni

​Note

​Linee guida per la configurazione Admin

​Risoluzione dei problemi

​Informazioni generali

Aggiungere un nuovo plugin MCP

mcp_config.json

MCP HTTP remoti

Interpolazione della configurazione

Controlli per gli amministratori (Team ed Enterprise)

Come funziona la corrispondenza dei server

Opzioni di configurazione

Pattern regex comuni

Note

Linee guida per la configurazione Admin

Risoluzione dei problemi

Informazioni generali