> ## Documentation Index
> Fetch the complete documentation index at: https://docs.windsurf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Model Context Protocol (MCP)

> Configure servidores MCP para expandir o Cascade com ferramentas e serviços personalizados usando os transportes stdio, HTTP ou SSE, com controles administrativos para Teams e Enterprise.

**MCP (Model Context Protocol)** é um protocolo que permite que LLMs acessem ferramentas e serviços personalizados.
Um cliente MCP (o Cascade, neste caso) pode fazer solicitações a servidores MCP para acessar as ferramentas que eles fornecem.
O Cascade agora integra nativamente com o MCP, permitindo que você conecte sua própria seleção de servidores MCP para o Cascade usar.
Consulte a [documentação oficial do MCP](https://modelcontextprotocol.io/) para mais informações.

<Note>Usuários do plano Enterprise devem ativar isso manualmente nas configurações</Note>

<div id="adding-a-new-mcp-plugin">
  ## Adicionando um novo plugin MCP
</div>

Novos plugins MCP podem ser adicionados acessando `Settings` > `Tools` > `Windsurf Settings` > `Add Server`.

Se você não encontrar o plugin MCP desejado, pode adicioná-lo manualmente clicando no botão `View Raw Config` e editando o arquivo `mcp_config.json` diretamente.

Ao clicar em um servidor MCP, basta selecionar `+ Add Server` para disponibilizar o servidor e suas ferramentas no Cascade.

<Frame>
  <img src="https://mintcdn.com/codeium/d8O4q6w3H2CjrirL/assets/plugins/mcp-server-templates.jpg?fit=max&auto=format&n=d8O4q6w3H2CjrirL&q=85&s=06f96424bd8374333d6969006868456e" width="1666" height="1388" data-path="assets/plugins/mcp-server-templates.jpg" />
</Frame>

O Cascade oferece suporte a três [tipos de transporte](https://modelcontextprotocol.io/docs/concepts/transports) para servidores MCP: `stdio`, `Streamable HTTP` e `SSE`.

O Cascade também oferece suporte a OAuth para cada tipo de transporte.

Para servidores `http`, a URL deve corresponder ao endpoint e ter o formato `https://<your-server-url>/mcp`.

<Note>Certifique-se de clicar no botão de atualizar depois de adicionar um novo plugin MCP.</Note>

<div id="mcp_configjson">
  ## mcp\_config.json
</div>

O arquivo `~/.codeium/mcp_config.json` é um arquivo JSON que lista os servidores aos quais o Cascade pode se conectar.

Veja um exemplo de configuração que define um único servidor para o GitHub:

```json theme={null}
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<SEU_TOKEN_DE_ACESSO_PESSOAL>"
      }
    }
  }
}
```

Certifique-se de fornecer os argumentos necessários e as variáveis de ambiente para os servidores que deseja usar.

Consulte o [repositório oficial de referência de servidores MCP](https://github.com/modelcontextprotocol/servers) ou o [OpenTools](https://opentools.com/) para exemplos de servidores.

<div id="remote-http-mcps">
  ### MCPs HTTP remotos
</div>

É importante observar que, para MCPs HTTP remotos, a configuração é um pouco
diferente e requer o campo `serverUrl` ou `url`.

Veja um exemplo de configuração para um servidor HTTP:

```json theme={null}
{
  "mcpServers": {
    "remote-http-mcp": {
      "serverUrl": "<url-do-seu-servidor>/mcp",
      "headers": {
        "API_KEY": "value"
      }
    }
  }
}
```

<div id="config-interpolation">
  ### Interpolação de Configuração
</div>

O arquivo `~/.codeium/mcp_config.json` lida com a interpolação de
variáveis de ambiente nestes campos: `command`, `args`, `env`, `serverUrl`, `url` e
`headers`.

Aqui está um exemplo de configuração que usa a variável de ambiente `AUTH_TOKEN`
em `headers`.

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

<div id="admin-controls-teams-enterprises">
  ## Controles de administração (Teams & Enterprises)
</div>

Os administradores de equipe podem ativar ou desativar o acesso a MCP para sua equipe, bem como definir na lista de permissões os servidores MCP aprovados para uso da equipe:

<Card title="Configurações de MCP da equipe" horizontal={true} icon="hammer" href="https://windsurf.com/team/settings">
  Configurações de MCP personalizáveis para sua equipe.
</Card>

<Warning>O link acima só funcionará se você tiver privilégios de administrador para sua equipe.</Warning>

Por padrão, os usuários de uma equipe poderão configurar seus próprios servidores MCP. No entanto, assim que você colocar na lista de permissões mesmo um único servidor MCP, **todos os servidores que não estiverem na lista de permissões serão bloqueados** para sua equipe.

<div id="how-server-matching-works">
  ### Como funciona o Server Matching
</div>

Quando você coloca um servidor MCP na lista de permissões (allowlist), o sistema usa **correspondência por padrão regex** com as seguintes regras:

* **Correspondência de string completa**: Todos os padrões são automaticamente ancorados (envolvidos com `^(?:pattern)$`) para evitar correspondências parciais
* **Campo Command**: Deve corresponder exatamente ou de acordo com o seu padrão de regex
* **Array de argumentos**: Cada argumento é verificado individualmente em relação ao seu padrão correspondente
* **Comprimento do array**: O número de argumentos deve corresponder exatamente entre a lista de permissões e a configuração do usuário
* **Caracteres especiais**: Caracteres como `$`, `.`, `[`, `]`, `(`, `)` têm significado especial em regex e devem ser escapados com `\` se você quiser correspondência literal

<div id="configuration-options">
  ### Opções de configuração
</div>

<AccordionGroup>
  <Accordion title="Opção 1: Padrão da Plugin Store (recomendado)" description="Deixe o campo Server Config (JSON) vazio para usar a configuração padrão da Windsurf MCP Plugin Store.">
    **Configuração de lista de permissões do admin:**

    * **Server ID**: `github-mcp-server`
    * **Server Config (JSON)**: *(deixe vazio)*

    ```json theme={null}
    {}
    ```

    **Configuração correspondente do usuário (`mcp_config.json`):**

    ```json theme={null}
    {
      "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"
          }
        }
      }
    }
    ```

    Isso permite que os usuários instalem o servidor MCP do GitHub com qualquer configuração válida, desde que o Server ID corresponda à entrada da Plugin Store.
  </Accordion>

  <Accordion title="Opção 2: Configuração de correspondência exata" description="Forneça a configuração exata que os usuários devem usar. Os usuários devem corresponder a esta configuração exatamente.">
    **Configuração de lista de permissões do admin:**

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

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

    **Configuração correspondente do usuário (`mcp_config.json`):**

    ```json theme={null}
    {
      "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"
          }
        }
      }
    }
    ```

    Os usuários devem usar exatamente esta configuração — qualquer desvio em command ou args será bloqueado. A seção `env` pode ter valores diferentes.
  </Accordion>

  <Accordion title="Opção 3: Padrões flexíveis com regex" description="Use padrões regex para permitir variações nas configurações dos usuários mantendo os controles de segurança.">
    **Configuração de lista de permissões do admin:**

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

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

    **Configuração correspondente do usuário (`mcp_config.json`):**

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

    Este exemplo oferece flexibilidade aos usuários mantendo a segurança:

    * O regex `/.*\\.py` corresponde a qualquer caminho de arquivo Python, como `/home/user/my_server.py`
    * O regex `[0-9]+` corresponde a qualquer porta numérica, como `8080` ou `3000`
    * Os usuários podem personalizar caminhos de arquivos e portas, enquanto os administradores garantem que apenas scripts Python sejam executados
  </Accordion>
</AccordionGroup>

<div id="common-regex-patterns">
  ### Padrões comuns de regex
</div>

| Padrão          | Corresponde a             | Exemplo                 |
| --------------- | ------------------------- | ----------------------- |
| `.*`            | Qualquer string           | `/home/user/script.py`  |
| `[0-9]+`        | Qualquer número           | `8080`, `3000`          |
| `[a-zA-Z0-9_]+` | Alfanumérico + sublinhado | `api_key_123`           |
| `\\$HOME`       | Literal `$HOME`           | `$HOME` (não expandido) |
| `\\.py`         | Literal `.py`             | `script.py`             |
| `\\[cli\\]`     | Literal `[cli]`           | `mcp[cli]`              |

<div id="notes">
  ## Notas
</div>

<div id="admin-configuration-guidelines">
  ### Diretrizes de Configuração de Administração
</div>

* **Variáveis de ambiente**: A seção `env` não usa correspondência por regex e pode ser configurada livremente pelos usuários
* **Ferramentas desativadas**: O array `disabledTools` é tratado separadamente e não faz parte da correspondência por lista de permissão (whitelist)
* **Diferença entre maiúsculas e minúsculas**: Toda a correspondência diferencia maiúsculas de minúsculas
* **Tratamento de erros**: Padrões de regex inválidos serão registrados e resultarão em negação de acesso
* **Testes**: Teste seus padrões de regex com cuidado — padrões excessivamente restritivos podem bloquear casos de uso legítimos

<div id="troubleshooting">
  ### Solução de problemas
</div>

Se os usuários relatarem que seus servidores MCP não estão funcionando após a inclusão na lista de permissões:

1. **Verifique a correspondência exata**: Certifique-se de que o padrão da lista de permissões corresponda exatamente à configuração do usuário
2. **Verifique a escape de regex**: Caracteres especiais podem precisar ser escapados (por exemplo, `\.` para pontos literais)
3. **Revise os logs**: Padrões de regex inválidos são registrados com avisos
4. **Teste os padrões**: Use um validador/testador de regex para verificar se seus padrões funcionam como esperado

Lembre-se: Depois que você incluir qualquer servidor na lista de permissões, **todos os outros servidores serão bloqueados automaticamente** para os membros da sua equipe.

<div id="general-information">
  ### Informações gerais
</div>

* Como as chamadas de ferramentas MCP podem invocar código escrito por implementadores de servidor arbitrários, não assumimos responsabilidade por falhas nessas chamadas. Reiterando:
* Atualmente oferecemos suporte às [ferramentas](https://modelcontextprotocol.io/docs/concepts/tools), [recursos](https://modelcontextprotocol.io/docs/concepts/resources) e [prompts](https://modelcontextprotocol.io/docs/concepts/prompts) de um servidor MCP.