> ## 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)

> Integre servidores MCP ao Cascade para acessar ferramentas personalizadas como GitHub, bancos de dados e APIs. Configure os transportes stdio, HTTP e SSE com controles de administrador para Teams.

**MCP (Model Context Protocol)** é um protocolo que permite que modelos de linguagem acessem ferramentas e serviços personalizados.
Um cliente MCP (o Cascade, neste caso) pode enviar solicitações a servidores MCP para acessar as ferramentas que eles disponibilizam.
O Cascade agora integra-se nativamente ao 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">
  ## Adicionando um novo MCP
</div>

Novos MCPs podem ser adicionados a partir do MCP Marketplace, que você acessa
clicando no ícone `MCPs` no menu superior direito do painel do Cascade, ou pela
seção `Windsurf Settings` > `Cascade` > `MCP Servers`.

Se você não encontrar o MCP desejado, é possível adicioná-lo manualmente editando diretamente o arquivo `mcp_config.json`.

MCPs oficiais aparecerão com um ícone de verificação azul, indicando que são feitos pela empresa do serviço correspondente.

Quando você clicar em um MCP, basta clicar em `Install` para disponibilizar o servidor e suas ferramentas no Cascade.

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

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

Para servidores `http`, a URL deve refletir a do endpoint e se assemelhar a `https://<your-server-url>/mcp`.

<Frame>
  <img src="https://mintcdn.com/codeium/Rm_zdSOuabDsfa9L/assets/windsurf/cascade/mcp/mcp-plugin-store.png?fit=max&auto=format&n=Rm_zdSOuabDsfa9L&q=85&s=1f6f2165d7017097ebb08cba65d43362" width="955" height="774" data-path="assets/windsurf/cascade/mcp/mcp-plugin-store.png" />
</Frame>

<div id="configuring-mcp-tools">
  ## Configurando ferramentas MCP
</div>

Cada MCP tem acesso a um determinado conjunto de ferramentas. O Cascade tem um limite de 100 ferramentas no total às quais pode ter acesso a qualquer momento.

Em cada página de configurações do MCP, você pode ativar ou desativar as ferramentas que deseja habilitar. Para abrir as configurações de um MCP, clique no ícone `MCPs` no menu superior direito do painel do Cascade e clique no MCP desejado.

<Frame>
  <img src="https://mintcdn.com/codeium/Rm_zdSOuabDsfa9L/assets/windsurf/cascade/mcp/mcp-manage-plugin-tools.png?fit=max&auto=format&n=Rm_zdSOuabDsfa9L&q=85&s=167fd87ffb6cf42228f6e62ff8cb6596" width="893" height="639" data-path="assets/windsurf/cascade/mcp/mcp-manage-plugin-tools.png" />
</Frame>

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

O arquivo `~/.codeium/windsurf/mcp_config.json` é um arquivo JSON que contém uma lista de servidores aos quais o Cascade pode se conectar.

Aqui está 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 e as variáveis de ambiente exigidos pelos servidores que você 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="popular-mcp-server-examples">
  ### Exemplos Populares de Servidores MCP
</div>

Abaixo estão alguns exemplos de configuração para servidores MCP bastante utilizados. Você pode adicioná-los ao seu arquivo `mcp_config.json`.

<AccordionGroup>
  <Accordion title="GitHub" description="Gerenciamento de repositórios, operações com arquivos e integração com a API do GitHub.">
    O servidor MCP do GitHub fornece ferramentas para gerenciamento de repositórios, operações com arquivos, rastreamento de issues e gerenciamento de pull requests.

    **Usando npx:**

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

    **Usando Docker:**

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

    Para criar um token de acesso pessoal, acesse [GitHub Settings > Developer settings > Personal access tokens](https://github.com/settings/tokens).
  </Accordion>

  <Accordion title="Slack" description="Recursos de gerenciamento de canais e mensagens para workspaces do Slack.">
    O servidor MCP do Slack permite gerenciamento de canais, envio de mensagens e interações com o workspace.

    ```json theme={null}
    {
      "mcpServers": {
        "slack": {
          "command": "npx",
          "args": ["-y", "@anthropic/mcp-server-slack"],
          "env": {
            "SLACK_BOT_TOKEN": "<YOUR_SLACK_BOT_TOKEN>",
            "SLACK_TEAM_ID": "<YOUR_SLACK_TEAM_ID>"
          }
        }
      }
    }
    ```

    Para configurar um token de bot do Slack:

    1. Crie um Slack App em [api.slack.com/apps](https://api.slack.com/apps)
    2. Adicione os escopos OAuth necessários (por exemplo, `channels:read`, `chat:write`, `users:read`)
    3. Instale o app no seu workspace e copie o Bot User OAuth Token
  </Accordion>

  <Accordion title="PostgreSQL" description="Acesso somente leitura ao banco de dados com recursos de inspeção de schema.">
    O servidor MCP do PostgreSQL fornece acesso somente leitura a bancos de dados PostgreSQL, incluindo inspeção de schema e execução de consultas (queries).

    ```json theme={null}
    {
      "mcpServers": {
        "postgres": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-postgres"],
          "env": {
            "POSTGRES_CONNECTION_STRING": "postgresql://user:password@localhost:5432/database"
          }
        }
      }
    }
    ```

    <Warning>O servidor PostgreSQL fornece acesso somente leitura por padrão, para maior segurança. Certifique-se de que sua string de conexão use credenciais apropriadas com permissões limitadas.</Warning>
  </Accordion>

  <Accordion title="Filesystem" description="Operações com arquivos seguras com controles de acesso configuráveis.">
    O servidor MCP de Filesystem fornece acesso seguro a arquivos e diretórios locais com controles de acesso configuráveis.

    ```json theme={null}
    {
      "mcpServers": {
        "filesystem": {
          "command": "npx",
          "args": [
            "-y", "@modelcontextprotocol/server-filesystem",
            "/path/to/allowed/directory"
          ]
        }
      }
    }
    ```

    Você pode especificar vários diretórios permitidos adicionando argumentos de caminho adicionais. Somente arquivos dentro desses diretórios ficarão acessíveis.
  </Accordion>

  <Accordion title="Brave Search" description="Pesquisa na web e local usando a Search API do Brave.">
    O servidor MCP do Brave Search habilita recursos de pesquisa na web usando a Search API do Brave.

    ```json theme={null}
    {
      "mcpServers": {
        "brave-search": {
          "command": "npx",
          "args": ["-y", "@anthropic/mcp-server-brave-search"],
          "env": {
            "BRAVE_API_KEY": "<YOUR_BRAVE_API_KEY>"
          }
        }
      }
    }
    ```

    Para obter uma chave de API do Brave, cadastre-se em [brave.com/search/api](https://brave.com/search/api/).
  </Accordion>

  <Accordion title="Memory" description="Sistema de memória persistente baseado em grafo de conhecimento.">
    O servidor MCP de Memory fornece um sistema de memória persistente usando um grafo de conhecimento, permitindo que o Cascade se lembre de informações entre sessões.

    ```json theme={null}
    {
      "mcpServers": {
        "memory": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-memory"]
        }
      }
    }
    ```

    O servidor de memória armazena dados localmente e persiste entre sessões, sendo útil para manter contexto sobre projetos, preferências e informações aprendidas.
  </Accordion>
</AccordionGroup>

<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/windsurf/mcp_config.json` é responsável pela interpolação de
variáveis de ambiente nesses campos: `command`, `args`, `env`, `serverUrl`, `url` e
`headers`.

Veja um exemplo de configuração que usa a variável de ambiente `AUTH_TOKEN`
no campo `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 ao MCP para sua equipe, bem como definir uma lista de servidores MCP aprovados para uso pela 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 da sua equipe.</Warning>

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

<Note>O ID do servidor na lista de permissões deve corresponder, respeitando a diferença entre maiúsculas e minúsculas, ao nome da chave usado no `mcp_config.json` do usuário.</Note>

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

Quando você coloca um servidor MCP na 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 conforme o seu padrão regex
* **Array de argumentos**: Cada argumento é comparado individualmente ao seu padrão correspondente
* **Tamanho do array**: O número de argumentos deve corresponder exatamente entre a allowlist 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) em branco 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 em branco)*

    ```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 exatamente a essa configuração.">
    **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 essa 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 regex flexíveis" description="Use padrões regex para permitir variações nas configurações do usuário 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 sem abrir mão da 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 arquivo e portas, enquanto os admins garantem que apenas scripts Python sejam executados
  </Accordion>
</AccordionGroup>

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

| Padrão          | Correspondências          | 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 do Admin
</div>

* **Variáveis de ambiente**: A seção `env` não é verificada por regex e pode ser configurada livremente pelos usuários
* **Ferramentas desativadas**: O array `disabledTools` é tratado separadamente e não faz parte da verificação por 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 os servidores MCP não estão funcionando após entrarem na lista de permissões:

1. **Verifique a correspondência exata**: Certifique-se de que o padrão da lista de permissões corresponde exatamente à configuração do usuário
2. **Verifique o escape em regex**: Caracteres especiais podem precisar de escape (por exemplo, `\.` para pontos literais)
3. **Confira os logs**: Padrões 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ê permite qualquer servidor na lista, **todos os outros servidores são automaticamente bloqueados** para os membros da sua equipe.

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

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