Conecte o Qwen Code a ferramentas via MCP

O Qwen Code pode se conectar a ferramentas externas e fontes de dados por meio do Model Context Protocol (MCP) . Servidores MCP concedem ao Qwen Code acesso às suas ferramentas, bancos de dados e APIs.

O que você pode fazer com o MCP

Com servidores MCP conectados, você pode solicitar ao Qwen Code que:

• Trabalhe com arquivos e repositórios (leitura/pesquisa/gravação, dependendo das ferramentas habilitadas)
• Consulte bancos de dados (inspeção de esquema, consultas, relatórios)
• Integre serviços internos (envolva suas APIs como ferramentas MCP)
• Automatize fluxos de trabalho (tarefas repetíveis expostas como ferramentas/prompt)

Início rápido

O Qwen Code carrega servidores MCP a partir da configuração mcpServers no seu arquivo settings.json. Você pode configurar os servidores de duas maneiras:

• Editando diretamente o arquivo settings.json
• Usando os comandos qwen mcp (consulte a referência da CLI)

Adicione seu primeiro servidor

1. Adicione um servidor (exemplo: servidor remoto MCP HTTP):

qwen mcp add --transport http meu-servidor http://localhost:3000/mcp

2. Abra o diálogo de gerenciamento do MCP para visualizar e gerenciar servidores:

qwen mcp

3. Reinicie o Qwen Code no mesmo projeto (ou inicie-o, caso ainda não esteja em execução), depois peça ao modelo para usar ferramentas desse servidor.

Onde a configuração é armazenada (escopos)

A maioria dos usuários precisa apenas desses dois escopos:

• Escopo do projeto (padrão): .qwen/settings.json na raiz do seu projeto
• Escopo do usuário: ~/.qwen/settings.json em todos os projetos da sua máquina

Gravar no escopo do usuário:

qwen mcp add --scope user --transport http meu-servidor http://localhost:3000/mcp

Configurar servidores

Escolha um transporte

Configurar via settings.json ou qwen mcp add

Ambas as abordagens geram as mesmas entradas mcpServers no seu arquivo settings.json — use a que preferir.

Servidor Stdio (processo local)

JSON (.qwen/settings.json):

{
  "mcpServers": {
    "pythonTools": {
      "command": "python",
      "args": ["-m", "my_mcp_server", "--port", "8080"],
      "cwd": "./mcp-servers/python",
      "env": {
        "DATABASE_URL": "$DB_CONNECTION_STRING",
        "API_KEY": "${EXTERNAL_API_KEY}"
      },
      "timeout": 15000
    }
  }
}

CLI (escreve no escopo do projeto por padrão):

qwen mcp add pythonTools -e DATABASE_URL=$DB_CONNECTION_STRING -e API_KEY=$EXTERNAL_API_KEY \
  --timeout 15000 python -m my_mcp_server --port 8080

Servidor HTTP (HTTP transmitido remotamente)

JSON:

{
  "mcpServers": {
    "httpServerWithAuth": {
      "httpUrl": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer seu-token-de-api"
      },
      "timeout": 5000
    }
  }
}

CLI:

qwen mcp add --transport http httpServerWithAuth http://localhost:3000/mcp \
  --header "Authorization: Bearer seu-token-de-api" --timeout 5000

Servidor SSE (Eventos enviados pelo servidor remoto)

JSON:

{
  "mcpServers": {
    "sseServer": {
      "url": "http://localhost:8080/sse",
      "timeout": 30000
    }
  }
}

CLI:

qwen mcp add --transport sse sseServer http://localhost:8080/sse --timeout 30000

Segurança e controle

Confiança (pular confirmações)

• Confiança no servidor (trust: true): ignora os prompts de confirmação para esse servidor (use com moderação).

Filtragem de ferramentas (permitir/negar ferramentas por servidor)

Use includeTools / excludeTools para restringir as ferramentas expostas por um servidor (do ponto de vista do Qwen Code).

Exemplo: incluir apenas algumas ferramentas:

{
  "mcpServers": {
    "filteredServer": {
      "command": "python",
      "args": ["-m", "my_mcp_server"],
      "includeTools": ["safe_tool", "file_reader", "data_processor"],
      "timeout": 30000
    }
  }
}

Listas globais de permissão/negação

O objeto mcp no seu arquivo settings.json define regras globais para todos os servidores MCP:

• mcp.allowed: lista de permissões com os nomes dos servidores MCP (chaves em mcpServers)
• mcp.excluded: lista de negações com os nomes dos servidores MCP

Exemplo:

{
  "mcp": {
    "allowed": ["my-trusted-server"],
    "excluded": ["experimental-server"]
  }
}

Solução de problemas

• O servidor aparece como “Desconectado” em qwen mcp list: verifique se a URL ou o comando estão corretos e, em seguida, aumente o valor de timeout.
• O servidor stdio não inicia: use um caminho absoluto para command e verifique novamente cwd e env.
• Variáveis de ambiente em JSON não são resolvidas: certifique-se de que elas existam no ambiente onde o Qwen Code está sendo executado (ambientes de shell e de aplicativos gráficos podem diferir).

Referência

Estrutura de settings.json

Configuração específica do servidor (mcpServers)

Adicione um objeto mcpServers ao seu arquivo settings.json:

// ... o arquivo contém outros objetos de configuração
{
  "mcpServers": {
    "serverName": {
      "command": "caminho/para/o/servidor",
      "args": ["--arg1", "valor1"],
      "env": {
        "API_KEY": "$MY_API_TOKEN"
      },
      "cwd": "./diretorio-do-servidor",
      "timeout": 30000,
      "trust": false
    }
  }
}

Propriedades de configuração:

Obrigatórias (uma das seguintes):

Opcionais:

Gerenciar servidores MCP com qwen mcp

Você sempre pode configurar servidores MCP editando manualmente o arquivo settings.json, mas a CLI geralmente é mais rápida.

Adicionando um servidor (qwen mcp add)

qwen mcp add [opções] <nome> <comandoOuUrl> [argumentos...]

Removendo um servidor (qwen mcp remove)

qwen mcp remove <nome>