Pular para o conteúdo principal

O que é o MCP?

Model Context Protocol (MCP) permite que o Cursor se conecte a ferramentas e fontes de dados externas.

Por que usar MCP?

O MCP conecta o Cursor a sistemas e dados externos. Em vez de explicar a estrutura do teu projeto repetidamente, integra direto com as tuas ferramentas. Escreve servidores MCP em qualquer linguagem que consiga imprimir em stdout ou expor um endpoint HTTP — Python, JavaScript, Go, etc.

Como funciona

Servidores MCP expõem funcionalidades por meio do protocolo, conectando o Cursor a ferramentas ou fontes de dados externas. O Cursor oferece suporte a três métodos de transporte:
TransporteAmbiente de execuçãoImplantaçãoUsuáriosEntradaAutenticação
stdioLocalGerenciado pelo CursorUsuário únicoComando de shellManual
SSELocal/RemotoImplantar como servidorMúltiplos usuáriosURL para um endpoint SSEOAuth
Streamable HTTPLocal/RemotoImplantar como servidorMúltiplos usuáriosURL para um endpoint HTTPOAuth

Suporte ao protocolo

O Cursor oferece suporte a estes recursos do protocolo MCP:
RecursoSuporteDescrição
ToolsSuportadoFunções que o modelo de IA pode executar
PromptsSuportadoMensagens e fluxos de trabalho baseados em templates para usuários
ResourcesSuportadoFontes de dados estruturadas que podem ser lidas e referenciadas
RootsSuportadoConsultas iniciadas pelo servidor sobre limites de URI ou do sistema de arquivos nos quais operar
ElicitationSuportadoSolicitações iniciadas pelo servidor para obter informações adicionais dos usuários

Instalação de servidores MCP

Instalação com um clique

Instala servidores MCP da nossa coleção e faz a autenticação com OAuth.

Usando mcp.json

Configura servidores MCP personalizados com um arquivo JSON:
{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "mcp-server"],
      "env": {
        "API_KEY": "value"
      }
    }
  }
}

Configuração do servidor STDIO

Para servidores STDIO (servidores locais de linha de comando), configura estes campos no teu mcp.json:
CampoObrigatórioDescriçãoExemplos
typeSimTipo de conexão do servidor"stdio"
commandSimComando para iniciar o executável do servidor. Precisa estar disponível no teu PATH do sistema ou conter o caminho completo."npx", "node", "python", "docker"
argsNãoArray de argumentos passados para o comando["server.py", "--port", "3000"]
envNãoVariáveis de ambiente para o servidor{"API_KEY": "${input:api-key}"}
envFileNãoCaminho para um arquivo de ambiente para carregar mais variáveis".env", "${workspaceFolder}/.env"

Usando a API de Extensão

Para registro programático de servidores MCP, o Cursor oferece uma API de Extensão que permite configuração dinâmica sem modificar arquivos mcp.json. Isso é especialmente útil para ambientes corporativos e fluxos de configuração automatizada.

Referência da API de Extensão MCP

Aprende como registrar servidores MCP programaticamente usando vscode.cursor.mcp.registerServer()

Locais de configuração

Configuração do projeto

Cria .cursor/mcp.json no teu projeto para ferramentas específicas do projeto.

Configuração global

Cria ~/.cursor/mcp.json no teu diretório pessoal para ferramentas disponíveis em qualquer lugar.

Interpolação de configuração

Usa variáveis nos valores de mcp.json. O Cursor resolve variáveis nesses campos: command, args, env, url e headers. Sintaxe compatível:
  • ${env:NAME} variáveis de ambiente
  • ${userHome} caminho pra tua pasta inicial
  • ${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. Passa as chaves de API e os tokens pela config. O Cursor oferece suporte a OAuth para servidores que exigem isso.

Usando MCP no chat

O Composer Agent usa automaticamente as ferramentas MCP listadas em Available Tools quando relevante. Pede uma ferramenta específica pelo nome ou descreve o que tu precisa. Ativa ou desativa ferramentas nas configurações.

Alternar ferramentas

Ativa ou desativa ferramentas MCP direto na interface do chat. Clica no nome de uma ferramenta na lista para alternar. Ferramentas desativadas não são carregadas no contexto nem ficam disponíveis para o Agent.

Aprovação de ferramenta

Por padrão, o Agent pede aprovação antes de usar ferramentas MCP. Clica na seta ao lado do nome da ferramenta pra ver os argumentos.

Execução automática

Ativa a execução automática para o Agent usar ferramentas MCP sem pedir confirmação. Funciona como comandos de terminal. Lê mais sobre as configurações de execução automática aqui.

Resposta da ferramenta

O Cursor exibe a resposta no chat com visões expansíveis dos argumentos e das respostas:

Imagens como contexto

Servidores MCP podem retornar imagens — capturas de tela, diagramas etc. Retorna elas como strings codificadas em base64:
const RED_CIRCLE_BASE64 = "/9j/4AAQSkZJRgABAgEASABIAAD/2w...";
// ^ base64 completo truncado para facilitar a leitura

server.tool("generate_image", async (params) => {
  return {
    content: [
      {
        type: "image",
        data: RED_CIRCLE_BASE64,
        mimeType: "image/jpeg",
      },
    ],
  };
});
Veja este servidor de exemplo para ver os detalhes de implementação. O Cursor anexa as imagens retornadas à conversa. Se o modelo tiver suporte a imagens, ele as analisa.

Considerações de segurança

Ao instalar servidores MCP, considera estas práticas de segurança:
  • Confere a origem: Só instala servidores MCP de desenvolvedores e repositórios confiáveis
  • Revisa as permissões: Verifica quais dados e APIs o servidor vai acessar
  • Limita as chaves de API: Usa chaves de API restritas com as permissões mínimas necessárias
  • Audita o código: Para integrações críticas, revisa o código-fonte do servidor
Lembra que servidores MCP podem acessar serviços externos e executar código em teu nome. Sempre entende o que um servidor faz antes da instalação.

Exemplos do mundo real

Para ver exemplos práticos do MCP em ação, dá uma olhada no nosso guia de desenvolvimento web, que mostra como integrar Linear, Figma e ferramentas de navegador ao teu fluxo de desenvolvimento.

FAQ

Servidores MCP conectam o Cursor a ferramentas externas como Google Drive, Notion e outros serviços para trazer documentos e requisitos pro seu fluxo de trabalho de código.
Veja os logs do MCP assim: 1. Abre o painel Output no Cursor (Ctrl+Shift+U) 2. Seleciona “MCP Logs” no menu dropdown 3. Procura por erros de conexão, problemas de autenticação ou travamentos do servidor. Os logs mostram a inicialização do servidor, chamadas de ferramentas e mensagens de erro.
Sim! Alterna servidores on/off sem remover: 1. Abre Settings ( Ctrl+Shift+J) 2. Vai em Features → Model Context Protocol 3. Clica no toggle ao lado de qualquer servidor pra ativar/desativar. Servidores desativados não carregam nem aparecem no chat. Isso é útil pra solucionar problemas ou reduzir a bagunça de ferramentas.
Se um servidor MCP falhar: - O Cursor mostra uma mensagem de erro no chat - A chamada de ferramenta é marcada como falha - Você pode tentar a operação de novo ou checar os logs pra detalhes - Outros servidores MCP continuam funcionando normalmente. O Cursor isola falhas de servidor pra evitar que um servidor afete os outros.
Para servidores baseados em npm: 1. Remove o servidor nas configurações 2. Limpa o cache do npm: npm cache clean --force 3. Adiciona o servidor de novo pra obter a versão mais recente. Para servidores customizados, atualiza seus arquivos locais e reinicia o Cursor.
Sim, mas segue as melhores práticas de segurança: - Usa variáveis de ambiente pra segredos, nunca faz hardcode - Executa servidores sensíveis localmente com transporte stdio - Limita as permissões das chaves de API ao mínimo necessário - Revisa o código do servidor antes de conectar a sistemas sensíveis - Considera executar servidores em ambientes isolados