Como configurar um servidor MCP com parâmetros de ambiente no Cursor

Configurar servidores do Protocolo de Contexto de Modelo (MCP) com parâmetros de ambiente no Cursor permite que você passe informações sensíveis de forma segura e personalize o comportamento do servidor. Este guia fornece instruções detalhadas sobre como configurar e gerenciar variáveis de ambiente para seus servidores MCP.

Introdução à configuração de ambiente do servidor MCP

Os servidores do Protocolo de Contexto de Modelo (MCP) estendem as capacidades de IA do Cursor fornecendo ferramentas e recursos adicionais. Os parâmetros de ambiente permitem que você:

• Passe chaves de API e tokens de autenticação de forma segura
• Configure o comportamento do servidor sem modificar o código
• Configure diferentes ambientes (desenvolvimento, homologação, produção)
• Personalize a funcionalidade do servidor com base no contexto de implantação

Por que usar parâmetros de ambiente?

Os parâmetros de ambiente oferecem várias vantagens:

1. Segurança: Mantenha informações sensíveis fora do seu código
2. Flexibilidade: Altere a configuração sem modificar o código
3. Portabilidade: Execute o mesmo servidor em diferentes ambientes
4. Separação de responsabilidades: Mantenha a configuração separada da implementação

Entendendo a configuração do servidor MCP

Antes de adicionar parâmetros de ambiente, é importante entender a estrutura básica da configuração do servidor MCP no Cursor.

Estrutura do arquivo de configuração MCP

Os servidores MCP são configurados em um arquivo JSON com a seguinte estrutura:

{
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["/path/to/server.js"],
      "env": {
        "KEY1": "value1",
        "KEY2": "value2"
      },
      "disabled": false,
      "autoApprove": ["tool1", "tool2"]
    }
  }
}

Componentes principais:

• server-name: Um identificador único para seu servidor MCP
• command: O comando para executar seu servidor (ex: node, python)
• args: Argumentos passados para o comando
• env: Variáveis de ambiente passadas para o processo do servidor
• disabled: Se o servidor está desativado
• autoApprove: Lista de ferramentas que não requerem aprovação explícita

Guia passo a passo de configuração

1. Localize seu arquivo de configuração MCP

A localização do seu arquivo de configuração MCP depende do seu sistema operacional:

Windows:

%APPDATA%\Code\User\globalStorage\tencent-cloud.coding-copilot\settings\Craft_mcp_settings.json

macOS:

~/Library/Application Support/Code/User/globalStorage/tencent-cloud.coding-copilot/settings/Craft_mcp_settings.json

Linux:

~/.config/Code/User/globalStorage/tencent-cloud.coding-copilot/settings/Craft_mcp_settings.json

2. Edite o arquivo de configuração

1. Abra o arquivo de configuração no seu editor de texto preferido
2. Se o arquivo não existir ou estiver vazio, crie-o com a seguinte estrutura:

{
  "mcpServers": {}
}

3. Adicione ou modifique sua configuração de servidor:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/path/to/my-server.js"],
      "env": {
        "API_KEY": "sua-chave-api-aqui",
        "DEBUG": "true",
        "PORT": "3000"
      },
      "disabled": false
    }
  }
}

3. Adicione parâmetros de ambiente

Para adicionar parâmetros de ambiente ao seu servidor MCP:

1. Identifique as variáveis de ambiente que seu servidor precisa
2. Adicione-as ao objeto env na sua configuração de servidor
3. Salve o arquivo de configuração

Exemplo com múltiplas variáveis de ambiente:

"env": {
  "OPENAI_API_KEY": "sk-abcdef123456",
  "SERVER_PORT": "3000",
  "LOG_LEVEL": "info",
  "CACHE_ENABLED": "true",
  "MAX_TOKENS": "4096",
  "MODEL_NAME": "gpt-4",
  "TIMEOUT_MS": "30000"
}

4. Usando variáveis de ambiente no seu servidor MCP

No código do seu servidor MCP, você pode acessar essas variáveis de ambiente:

JavaScript/Node.js:

const apiKey = process.env.API_KEY;
const debug = process.env.DEBUG === 'true';
const port = parseInt(process.env.PORT || '3000', 10);

console.log(`Iniciando servidor com chave API ${apiKey} na porta ${port}`);
if (debug) {
  console.log('Modo de depuração ativado');
}

Python:

import os

api_key = os.environ.get('API_KEY')
debug = os.environ.get('DEBUG') == 'true'
port = int(os.environ.get('PORT', '3000'))

print(f"Iniciando servidor com chave API {api_key} na porta {port}")
if debug:
    print("Modo de depuração ativado")

Técnicas avançadas de configuração

Usando arquivos de ambiente

Para configurações mais complexas, você pode usar arquivos de ambiente:

1. Crie um arquivo .env:

API_KEY=sua-chave-api-aqui
DEBUG=true
PORT=3000

2. Atualize sua configuração do servidor MCP:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/path/to/my-server.js"],
      "env": {
        "ENV_FILE": "/path/to/.env"
      }
    }
  }
}

3. No código do seu servidor, carregue o arquivo de ambiente:

JavaScript/Node.js (usando dotenv):

require('dotenv').config({ path: process.env.ENV_FILE });

// Agora você pode acessar as variáveis
const apiKey = process.env.API_KEY;

Python (usando python-dotenv):

import os
from dotenv import load_dotenv

load_dotenv(os.environ.get('ENV_FILE'))

# Agora você pode acessar as variáveis
api_key = os.environ.get('API_KEY')

Expansão de variáveis de ambiente

Você pode referenciar outras variáveis de ambiente dentro da sua configuração:

"env": {
  "BASE_URL": "https://api.example.com",
  "API_ENDPOINT": "${BASE_URL}/v1/data",
  "HOME_DIR": "${HOME}/projects"
}

Usando variáveis de ambiente do sistema

Você pode referenciar variáveis de ambiente do sistema na sua configuração:

"env": {
  "USER_HOME": "${HOME}",
  "SYSTEM_TEMP": "${TEMP}",
  "CURRENT_USER": "${USER}"
}

Melhores práticas de segurança

Ao trabalhar com parâmetros de ambiente, especialmente para informações sensíveis como chaves de API, siga estas melhores práticas de segurança:

1. Nunca comite informações sensíveis

• Use .gitignore para excluir arquivos de ambiente
• Não comite arquivos de configuração com chaves de API reais
• Use valores de exemplo nos arquivos commitados

2. Use criptografia para valores sensíveis

• Considere criptografar variáveis de ambiente sensíveis
• Use um sistema seguro de gerenciamento de chaves quando possível

3. Limite o acesso aos arquivos de configuração

• Configure permissões de arquivo apropriadas
• Restrinja quem pode visualizar e editar arquivos de configuração

4. Faça rotação de segredos regularmente

• Mude chaves de API e tokens periodicamente
• Atualize seus arquivos de configuração quando os segredos mudarem

5. Valide variáveis de ambiente

No código do seu servidor, valide as variáveis de ambiente antes de usá-las:

function validateEnv() {
  const requiredVars = ['API_KEY', 'SERVER_PORT'];
  const missing = requiredVars.filter(varName => !process.env[varName]);
  
  if (missing.length > 0) {
    throw new Error(`Variáveis de ambiente obrigatórias ausentes: ${missing.join(', ')}`);
  }
}

validateEnv();

Solução de problemas comuns

Variáveis de ambiente não disponíveis

Problema: Variáveis de ambiente configuradas nas configurações MCP não estão disponíveis no seu servidor.

Soluções:

• Verifique a sintaxe do arquivo de configuração
• Verifique se o servidor está sendo iniciado corretamente
• Reinicie o Cursor após fazer alterações na configuração
• Verifique os logs do servidor para erros relacionados ao ambiente

Arquivo de configuração não encontrado

Problema: O Cursor não consegue encontrar seu arquivo de configuração MCP.

Soluções:

• Verifique se o caminho do arquivo está correto para seu sistema operacional
• Crie a estrutura de diretórios se ela não existir
• Verifique as permissões do arquivo
• Reinicie o Cursor após criar o arquivo

Formato JSON inválido

Problema: Arquivo de configuração tem erros de sintaxe JSON.

Soluções:

• Valide seu JSON usando um validador JSON
• Verifique se há vírgulas, colchetes ou aspas faltando
• Certifique-se de que todos os nomes de propriedades estão entre aspas duplas
• Remova vírgulas extras

Servidor trava na inicialização

Problema: Servidor MCP trava imediatamente após iniciar.

Soluções:

• Verifique os logs do servidor para mensagens de erro
• Verifique se todas as variáveis de ambiente necessárias foram fornecidas
• Certifique-se de que os valores das variáveis de ambiente estão no formato correto
• Verifique problemas de caminho em referências de arquivo

Exemplos para casos de uso comuns

1. Integração com API OpenAI

{
  "mcpServers": {
    "openai-tools": {
      "command": "node",
      "args": ["/path/to/openai-server.js"],
      "env": {
        "OPENAI_API_KEY": "sk-sua-chave-aqui",
        "MODEL": "gpt-4",
        "MAX_TOKENS": "8192",
        "TEMPERATURE": "0.7"
      }
    }
  }
}

2. Conexão com banco de dados

{
  "mcpServers": {
    "db-tools": {
      "command": "python",
      "args": ["/path/to/db-server.py"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_NAME": "mydb",
        "DB_USER": "usuario",
        "DB_PASSWORD": "senha",
        "CONNECTION_POOL_SIZE": "10"
      }
    }
  }
}

3. Configurações de desenvolvimento vs. produção

{
  "mcpServers": {
    "api-tools": {
      "command": "node",
      "args": ["/path/to/api-server.js"],
      "env": {
        "NODE_ENV": "development",
        "API_URL": "http://localhost:8080/api",
        "CACHE_ENABLED": "false",
        "LOG_LEVEL": "debug"
      }
    }
  }
}

Conclusão

Configurar servidores MCP com parâmetros de ambiente no Cursor fornece uma maneira flexível e segura de personalizar o comportamento do servidor e gerenciar informações sensíveis. Seguindo os passos e melhores práticas descritos neste guia, você pode configurar e gerenciar efetivamente variáveis de ambiente para seus servidores MCP.

Seja integrando com APIs externas, conectando a bancos de dados ou simplesmente personalizando o comportamento do servidor, os parâmetros de ambiente oferecem uma separação limpa entre configuração e código, melhorando a segurança e a manutenibilidade.

Recursos adicionais

• Documentação oficial do Cursor
• Especificação do Protocolo de Contexto de Modelo (MCP)
• Melhores práticas para variáveis de ambiente
• Guia de configuração JSON
• Fórum da comunidade Cursor