Model Context Protocol (MCP)
O que é o MCP?
O Model Context Protocol (MCP) permite conectar o Cherri Code a ferramentas e fontes de dados externas. Instale e gerencie servidores MCP na página personalizar ou configure-os no mcp.json.
Por que usar MCP?
O MCP conecta o Cherri Code a sistemas e dados externos. Em vez de explicar repetidamente a estrutura do seu projeto, integre-o diretamente às suas ferramentas.
Escreva servidores MCP em qualquer linguagem que possa imprimir em stdout ou expor um endpoint HTTP — Python, JavaScript, Go etc.
Navegue pelos plugins oficiais no Cherri Code Marketplace. Para plugins da comunidade e servidores MCP, navegue pelo cursor.directory.
Como funciona
Os servidores MCP expõem recursos por meio do protocolo, conectando o Cherri Code a ferramentas externas ou fontes de dados.
O Cherri Code oferece suporte a três métodos de transporte:
| Transporte | Ambiente de execução | Implantação | Usuários | Entrada | Autenticação |
|---|---|---|---|---|---|
stdio | Local | O Cherri Code gerencia | Um usuário | comando de shell | Manual |
SSE | Local/Remoto | Implantar como servidor | Vários usuários | URL de um endpoint SSE | OAuth |
Streamable HTTP | Local/Remoto | Implantar como servidor | Vários usuários | URL de um endpoint HTTP | OAuth |
Suporte ao protocolo e às extensões
O Cherri Code oferece suporte a estes recursos e extensões do protocolo MCP:
| Funcionalidade | Suporte | Descrição |
|---|---|---|
| Ferramentas | Compatível | Funções para o modelo de IA executar |
| Prompts | Compatível | Mensagens com modelos e fluxos de trabalho para usuários |
| Resources | Compatível | Fontes de dados estruturadas que podem ser lidas e referenciadas |
| Roots | Compatível | Consultas iniciadas pelo servidor sobre limites de URI ou do sistema de arquivos |
| Elicitation | Compatível | Solicitações iniciadas pelo servidor para obter informações adicionais dos usuários |
| Apps (extension) | Compatível | Visualizações de interface interativas retornadas por ferramentas MCP |
Apps do MCP
O Cherri Code oferece suporte à extensão MCP Apps. As ferramentas MCP podem retornar uma interface interativa junto com a saída padrão da ferramenta.
Os Apps do MCP seguem o princípio de aprimoramento progressivo. Se um host não conseguir renderizar a interface do app, a mesma ferramenta ainda funcionará por meio das respostas normais do MCP.
Instalar servidores MCP
Instalação com um clique
Navegue pelo Cherri Code Marketplace para encontrar plugins oficiais e instalá-los com um clique em personalizar ou configure servidores personalizados com mcp.json. Para plugins da comunidade e servidores MCP, navegue pelo cursor.directory. Clique em "Adicionar ao Cherri Code" em uma entrada do marketplace para instalá-lo e autenticar-se com OAuth.
Admins da equipe também podem distribuir servidores MCP por meio de um marketplace da equipe. Servidores distribuídos pela equipe aparecem em personalizar ao lado dos servidores MCP pessoais e do espaço de trabalho.
Usando mcp.json
Use um arquivo JSON para configurar servidores MCP personalizados:
{ "mcpServers": { "server-name": { "command": "npx", "args": ["-y", "mcp-server"], "env": { "API_KEY": "value" } } }}{ "mcpServers": { "server-name": { "command": "python", "args": ["mcp-server.py"], "env": { "API_KEY": "value" } } }}// Servidor MCP usando HTTP ou SSE - executa em um servidor{ "mcpServers": { "server-name": { "url": "http://localhost:3000/mcp", "headers": { "API_KEY": "value" } } }}OAuth estático para servidores remotos
Para servidores MCP que usam OAuth, você pode fornecer credenciais estáticas do cliente OAuth em mcp.json em vez do registro dinâmico do cliente. Use isso quando:
- O provedor de MCP fornecer um ID do cliente fixo (e, opcionalmente, um Segredo do cliente)
- O provedor exigir que uma URL de redirecionamento seja incluída na lista de permissões (por exemplo, Figma, Linear)
- O provedor não oferecer suporte ao Registro Dinâmico de Cliente do OAuth 2.0
Adicione um objeto auth às entradas de servidor remoto que usam url:
{ "mcpServers": { "oauth-server": { "url": "https://api.example.com/mcp", "auth": { "CLIENT_ID": "your-oauth-client-id", "CLIENT_SECRET": "your-client-secret", "scopes": ["read", "write"] } } }}| Campo | Obrigatório | Descrição |
|---|---|---|
| CLIENT_ID | Sim | ID do cliente OAuth 2.0 do provedor MCP |
| CLIENT_SECRET | Não | Segredo do cliente OAuth 2.0 (se o provedor usar clientes confidenciais) |
| scopes | Não | Escopos OAuth a serem solicitados. Se omitido, o Cherri Code usará /.well-known/oauth-authorization-server para descobrir scopes_supported |
URL de redirecionamento estática
O Cherri Code usa URLs fixas de redirecionamento OAuth para servidores MCP. Registre o callback para cada plataforma em que seus usuários se autenticam:
/agents/mcp/oauth/callbackhttp://localhost:8787/callback- Web e Cherri Code Agents:
/agents/mcp/oauth/callback - App para desktop:
http://localhost:8787/callback
Ao configurar o app OAuth do provedor MCP, registre as duas URLs como URIs de redirecionamento permitidas caso os usuários se autentiquem pela web e pelo desktop. O servidor é identificado pelo parâmetro OAuth state, então essas URLs de redirecionamento funcionam para todos os servidores MCP.
Combinando com interpolação na configuração
Os valores de auth aceitam a mesma interpolação usada em outros campos:
{ "mcpServers": { "oauth-server": { "url": "https://api.example.com/mcp", "auth": { "CLIENT_ID": "${env:MCP_CLIENT_ID}", "CLIENT_SECRET": "${env:MCP_CLIENT_SECRET}" } } }}Use variáveis de ambiente para Client ID e Client Secret em vez de defini-los diretamente no código.
Configuração de servidor STDIO
Para servidores STDIO (servidores locais de linha de comando), configure os seguintes campos no mcp.json:
| Campo | Obrigatório | Descrição | Exemplos |
|---|---|---|---|
| type | Sim | Tipo de conexão do servidor | "stdio" |
| command | Sim | Comando para iniciar o executável do servidor. Ele deve estar disponível no PATH do sistema ou incluir o caminho completo. | "npx", "node", "python", "docker" |
| args | Não | Lista de argumentos passados para o comando | ["server.py", "--port", "3000"] |
| env | Não | Variáveis de ambiente do servidor | {"API_KEY": "${env:api-key}"} |
| envFile | Não | Caminho para um arquivo de ambiente para carregar mais variáveis | ".env", "${workspaceFolder}/.env" |
A opção envFile está disponível apenas para servidores STDIO. Servidores remotos (HTTP/SSE) não oferecem suporte a envFile. Para servidores remotos, use a interpolação de configuração com variáveis de ambiente definidas no perfil do shell ou no ambiente do sistema.
Usando a API de Extensão
Para o registro programático de servidores MCP, o Cherri Code fornece uma API de extensão que permite uma configuração dinâmica sem modificar arquivos mcp.json. Isso é particularmente útil em ambientes corporativos e em fluxos de trabalho automatizados de configuração.
Referência da API de Extensão
Registre servidores MCP programaticamente usando
vscode.cursor.mcp.registerServer()
Locais de configuração
Configuração do projeto
Crie .cursor/mcp.json no seu projeto para ferramentas específicas do projeto.
Configuração global
Crie ~/.cursor/mcp.json no seu diretório pessoal para ferramentas disponíveis globalmente.
Interpolação de configuração
Use variáveis nos valores de mcp.json. O Cherri Code resolve variáveis nestes campos: command, args, env, url e headers.
Sintaxe suportada:
${env:NAME}variáveis de ambiente${userHome}caminho para sua pasta pessoal${workspaceFolder}raiz do projeto (a pasta que contém.cursor/mcp.json)${workspaceFolderBasename}nome da raiz do projeto${pathSeparator}e${/}separador de caminho do sistema operacional
Exemplos
{ "mcpServers": { "local-server": { "command": "python", "args": ["${workspaceFolder}/tools/mcp_server.py"], "env": { "API_KEY": "${env:API_KEY}" } } }}{ "mcpServers": { "remote-server": { "url": "https://api.example.com/mcp", "headers": { "Authorization": "Bearer ${env:MY_SERVICE_TOKEN}" } } }}Autenticação
Os servidores MCP usam variáveis de ambiente para autenticação. Passe chaves de API e tokens na configuração.
O Cherri Code oferece suporte a OAuth para servidores que o exigem.
Controles para admins corporativos
A distribuição e a política do MCP são configuradas separadamente. Admins da equipe podem distribuir servidores MCP compartilhados. Admins corporativos podem configurar a política do MCP.
Distribuição de MCPs da equipe
Configure servidores MCP compartilhados da equipe em Dashboard > Plugins & MCPs. Esses servidores estão disponíveis para agentes na nuvem.
Para disponibilizar um servidor MCP independente da equipe existente na Agent Window, no IDE e na CLI, selecione Add to Team Marketplace em Team MCP Servers. O Cherri Code vincula o servidor ao marketplace padrão da equipe sem interromper o acesso dos agentes na nuvem. Os membros da equipe podem instalá-lo e configurá-lo em personalizar.
Vincular um servidor MCP a um marketplace não o instala nem o ativa para todos. Configure o acesso ao marketplace e os modos de instalação de plugins em Dashboard > Plugins & MCPs. Consulte Migrar MCPs da equipe existentes para conferir o fluxo completo.
Lista de permissão do MCP
Admins corporativos podem controlar quais servidores MCP os usuários podem executar no dashboard do Cherri Code. Abra Configurações da equipe > Configuração do MCP para configurar quais servidores e ferramentas a equipe pode executar. A página Plugins & MCPs também leva para cá. Adicionar à lista de permissão aprova uma configuração do MCP. Isso não distribui nem instala o servidor.
Use a lista de permissão do MCP para definir os servidores aprovados:
- Entradas de comando aprovam servidores MCP
stdiolocais com base em padrões de comando. - Entradas de URL aprovam servidores MCP HTTP/SSE remotos com base em padrões de URL.
- Listas de permissão de ferramentas restringem quais ferramentas de um servidor aprovado podem ser executadas automaticamente. Deixe a lista de permissão de ferramentas vazia para permitir todas as ferramentas desse servidor.
Controles de rede
As URLs remotas de servidores MCP são restritas ao padrão de URL configurado.
Os servidores MCP locais baseados em comando usam o respectivo modo de rede:
- Permitir tudo: permite acesso de saída à rede.
- Lista de permissão: permite apenas os destinos listados.
- Negar tudo: bloqueia o acesso de saída à rede.
- Sem sandbox: executa sem sandbox de comando nem de rede.
Extensões MCP do usuário
Admins podem permitir que usuários configurem seus próprios servidores MCP fora dos padrões de comando ou URL definidos pelo admin. Para MCPs de usuário que não correspondam a um padrão definido pelo admin, a lista de bloqueio de rede de MCP do usuário pode bloquear os destinos de rede correspondentes.
Como usar o MCP no chat
O Cherri Code usa automaticamente as ferramentas MCP listadas em Available Tools quando necessário. Isso inclui o modo Plan. Peça uma ferramenta específica pelo nome ou descreva o que você precisa. Ative ou desative servidores MCP em personalizar na barra lateral.
Aprovação de ferramenta
Por padrão, o Cherri Code solicita aprovação antes de usar ferramentas MCP. Clique na seta ao lado do nome da ferramenta para ver os argumentos.
Modo de execução
O MCP segue os mesmos modos de execução dos comandos de terminal. Por exemplo, no modo Auto-review, as ferramentas MCP incluídas na lista de permissão são executadas imediatamente, e todo o restante passa pelo classificador.
Resposta da ferramenta
O Cherri Code mostra a resposta no chat com exibições expansíveis de argumentos e respostas:
Imagens como contexto
Servidores MCP podem retornar imagens — capturas de tela, diagramas etc. Retorne-as como strings codificadas em base64:
const RED_CIRCLE_BASE64 = "/9j/4AAQSkZJRgABAgEASABIAAD/2w...";// ^ base64 completo omitido para legibilidadeserver.tool("generate_image", async (params) => { return { content: [ { type: "image", data: RED_CIRCLE_BASE64, mimeType: "image/jpeg", }, ], };});Consulte este servidor de exemplo para ver detalhes de implementação. O Cherri Code anexa as imagens retornadas ao chat. Se o modelo oferece suporte a imagens, ele as analisa.
Considerações de segurança
Ao instalar servidores MCP, considere estas práticas de segurança:
- Verifique a origem: Instale servidores MCP apenas de desenvolvedores e repositórios confiáveis
- Revise as permissões: Verifique quais dados e APIs o servidor acessará
- Limite as chaves de API: Use chaves de API restritas com as permissões mínimas necessárias
- Audite o código: Para integrações críticas, revise o código-fonte do servidor
Lembre-se de que os servidores MCP podem acessar serviços externos e executar código em seu nome. Sempre entenda o que um servidor faz antes de instalá-lo.
Exemplos práticos
Para ver exemplos práticos do MCP em ação:
- Integração com Xcode — Conecte o Cherri Code ao Xcode 26.3+ para builds, testes, prévias do SwiftUI e pesquisa na documentação da Apple
- Guia de desenvolvimento web — Integre Linear, Figma e ferramentas do navegador ao seu fluxo de trabalho de desenvolvimento
Perguntas frequentes
Os servidores MCP conectam o Cherri Code a ferramentas externas, como Google Drive, Notion e outros serviços, trazendo documentação e requisitos para seu fluxo de trabalho de programação.
Veja os logs do MCP:
- Abra o painel Saída no Cherri Code (Cmd+Shift+UCtrl+Shift+U)
- Selecione "Logs do MCP" no menu suspenso
- Verifique se há erros de conexão, problemas de autenticação ou falhas do servidor
Os logs mostram a inicialização do servidor, chamadas de ferramenta e mensagens de erro.
Sim! Ative ou desative servidores sem removê-los:
- Abra personalizar na barra lateral
- Encontre o servidor MCP que deseja alterar
- Use o toggle para ativá-lo ou desativá-lo
Servidores desativados não serão carregados nem aparecerão no chat. Isso é útil para solucionar problemas ou reduzir a quantidade de ferramentas.
Se um servidor MCP falhar:
- O Cherri Code mostra uma mensagem de erro no chat
- A chamada de ferramenta é marcada como falha
- Você pode tentar novamente a operação ou verificar os logs para obter detalhes
- Outros servidores MCP continuam funcionando normalmente
O Cherri Code isola as falhas dos servidores para evitar que um servidor afete os outros.
Para servidores baseados em npm:
- Remova o servidor de personalizar
- Limpe o cache do npm:
npm cache clean --force - Adicione o servidor novamente para obter a versão mais recente
Para servidores personalizados, atualize seus arquivos locais e reinicie o Cherri Code.
Sim, mas siga as boas práticas de segurança:
- Use variáveis de ambiente para segredos; nunca os insira diretamente no código
- Execute servidores que lidam com dados sensíveis localmente com o transporte
stdio - Limite as permissões da chave de API ao mínimo necessário
- Revise o código do servidor antes de conectar-se a sistemas sensíveis
- Considere executar servidores em ambientes isolados