Como configurar o mcp.json global e por projeto, todos os campos disponíveis, e exemplos prontos dos MCPs mais úteis para desenvolvedores.

Configurando MCPs no Cursor

O Cursor lê a configuração de servidores MCP de dois arquivos JSON. Entender onde cada um vive e quando usar qual é o primeiro passo para um setup sólido.

Onde ficam os arquivos

Escopo	Caminho	Quando usar
Global	`~/.cursor/mcp.json`	Ferramentas disponíveis em todos os projetos
Por projeto	`.cursor/mcp.json` (raiz do repo)	Ferramentas específicas do projeto, pode ser versionado no git

Quando ambos existem, as configurações do projeto têm precedência sobre as globais para servidores com o mesmo nome.

Estrutura completa do mcp.json

{
  "mcpServers": {
    "nome-do-servidor": {
      "command": "node",
      "args": ["/caminho/absoluto/server.js", "--flag-opcional"],
      "env": {
        "API_KEY": "sua-chave",
        "DATABASE_URL": "postgres://usuario:senha@localhost:5432/db"
      }
    },
    "via-npx": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/usuario/projetos"],
      "env": {}
    },
    "via-docker": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_SEU_TOKEN"
      }
    },
    "remoto-http": {
      "url": "https://mcp.suaempresa.com/mcp",
      "headers": {
        "Authorization": "Bearer SEU_TOKEN"
      }
    },
    "via-python": {
      "command": "uvx",
      "args": ["mcp-server-git", "--repository", "/caminho/do/repo"]
    }
  }
}

Campos disponíveis

Campo	Tipo	Descrição
`command`	`string`	Executável (caminho absoluto ou disponível no PATH)
`args`	`string[]`	Argumentos passados ao comando
`env`	`object`	Variáveis de ambiente (API keys, URLs, tokens)
`url`	`string`	URL do servidor HTTP (substitui `command` para servidores remotos)
`headers`	`object`	Headers HTTP para autenticação em servidores remotos

Como instalar um servidor no Cursor

1. Clique no botão "Add to Cursor" (mais fácil)

A maioria dos servidores populares tem um botão de instalação na sua documentação. Um clique e o Cursor abre um dialog de confirmação.

2. Pela interface gráfica

Cursor Settings → Tools & MCP → New MCP Server

3. Editando o arquivo manualmente

Abra ~/.cursor/mcp.json (ou crie se não existir) e adicione a entrada no objeto mcpServers.

Erros comuns de configuração

Problema	Causa	Solução
Servidor trava ao iniciar	`npx` sem a flag `-y` aguarda confirmação do usuário	Sempre adicione `-y` em args de npx
"Server not found"	Caminho relativo no `command`	Use caminho absoluto: `/home/usuario/...`
Ferramentas não aparecem	Chave raiz incorreta	Certifique que o JSON começa com `"mcpServers"`
Servidor ativo mas sem resposta	`console.log()` no código do servidor	Use `console.error()` — stdout é reservado para JSON-RPC
Nome ignorado	Nome do servidor com mais de 60 caracteres	Encurte o nome

MCPs prontos para usar

Filesystem — acesso a arquivos

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/home/usuario/projetos"
      ]
    }
  }
}

Ferramentas disponíveis: read_file, write_file, list_directory, search_files, move_file, create_directory.

Defina apenas as pastas que o agente deve acessar — isso cria uma sandbox implícita.

GitHub — gestão de repositórios

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

Ferramentas: criar issues, revisar PRs, verificar commits, gerenciar branches, criar arquivos. Gere o token em github.com/settings/tokens com os escopos mínimos necessários.

PostgreSQL — queries em tempo real

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://usuario:senha@localhost:5432/meubanco"
      }
    }
  }
}

O agente passa a consultar o schema e executar queries sem você precisar copiar e colar estruturas de tabelas.

Context7 — documentação atualizada

O MCP mais popular da comunidade. Resolve o problema clássico de o LLM usar APIs de versões antigas.

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@context7/mcp@latest"]
    }
  }
}

Uso: adicione use context7 ao final do seu prompt.

Como criar um Server Component no Next.js 16 com Suspense? use context7

O servidor detecta a biblioteca, busca a documentação da versão exata e injeta no contexto antes do modelo responder.

Fetch — conteúdo da web

{
  "mcpServers": {
    "fetch": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch"]
    }
  }
}

Busca e converte conteúdo de URLs para Markdown, otimizado para consumo por LLMs. Útil para pesquisa durante desenvolvimento.

Memory — memória persistente entre sessões

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

Implementa um grafo de conhecimento persistente. O agente pode salvar e recuperar informações entre conversas diferentes.

Sequential Thinking — raciocínio estruturado

{
  "mcpServers": {
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequentialthinking"]
    }
  }
}

Força o modelo a decompor problemas complexos em passos revisáveis antes de executar. Reduz alucinações em tarefas longas.

Puppeteer — automação de browser

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
    }
  }
}

Controla um Chrome/Chromium via código. Útil para testes de regressão visual, scraping de SPAs e automação de tarefas repetitivas.

Brave Search — busca sem chave de API

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "BSA_SEU_TOKEN"
      }
    }
  }
}

Busca web com foco em privacidade. Chave gratuita disponível em brave.com/search/api.

Setup completo recomendado para um dev solo

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/usuario/projetos"],
      "env": {}
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..." }
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@context7/mcp@latest"]
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequentialthinking"]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

Esse conjunto cobre: acesso a arquivos com sandbox, integração com GitHub, documentação sempre atualizada, raciocínio estruturado e memória persistente — sem nenhum servidor custom para manter.

Verificando se está funcionando

Após salvar o mcp.json, abra o Cursor e vá em:

Settings → Tools & MCP

Cada servidor deve aparecer com status verde (conectado). Se estiver vermelho, o log de erros fica disponível ali mesmo — normalmente é problema de caminho, token inválido ou npx sem -y.

Configurando MCPs no Cursor

On this page