Servidores MCP com Qwen Code

Este documento fornece um guia para configurar e usar servidores do Model Context Protocol (MCP) com o Qwen Code.

O que é um servidor MCP?

Um servidor MCP é um aplicativo que expõe ferramentas e recursos para a CLI por meio do Model Context Protocol, permitindo que ela interaja com sistemas externos e fontes de dados. Os servidores MCP atuam como uma ponte entre o modelo e seu ambiente local ou outros serviços, como APIs.

Um servidor MCP permite que a CLI:

Descobrir ferramentas: Listar ferramentas disponíveis, suas descrições e parâmetros por meio de definições de schema padronizadas.
Executar ferramentas: Chamar ferramentas específicas com argumentos definidos e receber respostas estruturadas.
Acessar recursos: Ler dados de recursos específicos (embora a CLI foque principalmente na execução de ferramentas).

Com um servidor MCP, você pode estender os recursos da CLI para realizar ações além das funcionalidades nativas, como interagir com bancos de dados, APIs, scripts personalizados ou fluxos de trabalho especializados.

Arquitetura de Integração Principal

O Qwen Code se integra a servidores MCP por meio de um sistema sofisticado de descoberta e execução integrado ao pacote principal (packages/core/src/tools/):

Camada de Descoberta (`mcp-client.ts`)

O processo de descoberta é orquestrado por discoverMcpTools(), que:

Itera sobre os servidores configurados na configuração mcpServers do seu settings.json
Estabelece conexões usando os mecanismos de transporte adequados (Stdio, SSE ou Streamable HTTP)
Busca as definições de ferramentas de cada servidor usando o protocolo MCP
Limpa e valida os schemas das ferramentas para compatibilidade com a API do Qwen
Registra as ferramentas no registro global de ferramentas com resolução de conflitos

Camada de Execução (`mcp-tool.ts`)

Cada ferramenta MCP descoberta é encapsulada em uma instância DiscoveredMCPTool que:

Gerencia a lógica de confirmação com base nas configurações de confiança do servidor e nas preferências do usuário
Gerencia a execução da ferramenta chamando o servidor MCP com os parâmetros adequados
Processa as respostas tanto para o contexto do LLM quanto para exibição ao usuário
Mantém o estado da conexão e gerencia timeouts

Mecanismos de Transporte

A CLI suporta três tipos de transporte MCP:

Transporte Stdio: Cria um subprocesso e se comunica via stdin/stdout
Transporte SSE: Conecta-se a endpoints de Server-Sent Events
Transporte Streamable HTTP: Usa streaming HTTP para comunicação

Como configurar seu servidor MCP

O Qwen Code usa a configuração mcpServers no seu arquivo settings.json para localizar e conectar-se a servidores MCP. Essa configuração suporta múltiplos servidores com diferentes mecanismos de transporte.

Configure o servidor MCP no settings.json

Você pode configurar servidores MCP no seu arquivo settings.json de duas formas principais: por meio do objeto mcpServers de nível superior para definições específicas de servidor, e por meio do objeto mcp para configurações globais que controlam a descoberta e execução de servidores.

Configurações Globais do MCP (`mcp`)

O objeto mcp no seu settings.json permite definir regras globais para todos os servidores MCP.

mcp.serverCommand (string): Um comando global para iniciar um servidor MCP.
mcp.allowed (array of strings): Uma lista de nomes de servidores MCP permitidos. Se definido, apenas os servidores desta lista (que correspondem às chaves no objeto mcpServers) serão conectados.
mcp.excluded (array of strings): Uma lista de nomes de servidores MCP a serem excluídos. Servidores nesta lista não serão conectados.

Exemplo:


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

Configuração Específica do Servidor (`mcpServers`)

O objeto mcpServers é onde você define cada servidor MCP individual ao qual deseja que a CLI se conecte.

Estrutura de Configuração

Adicione um objeto mcpServers ao seu arquivo settings.json:


{ ...file contains other config objects
  "mcpServers": {
    "serverName": {
      "command": "path/to/server",
      "args": ["--arg1", "value1"],
      "env": {
        "API_KEY": "$MY_API_TOKEN"
      },
      "cwd": "./server-directory",
      "timeout": 30000,
      "trust": false
    }
  }
}

Propriedades de Configuração

Cada configuração de servidor suporta as seguintes propriedades:

Obrigatório (um dos seguintes)

command (string): Caminho para o executável para transporte Stdio
url (string): URL do endpoint SSE (ex.: "http://localhost:8080/sse")
httpUrl (string): URL do endpoint de streaming HTTP

Opcional

args (string[]): Argumentos de linha de comando para transporte Stdio
headers (object): Headers HTTP personalizados ao usar url ou httpUrl
env (object): Variáveis de ambiente para o processo do servidor. Os valores podem referenciar variáveis de ambiente usando a sintaxe $VAR_NAME ou ${VAR_NAME}
cwd (string): Diretório de trabalho para transporte Stdio
timeout (number): Timeout da requisição em milissegundos (padrão: 600.000ms = 10 minutos)
trust (boolean): Quando true, ignora todas as confirmações de chamada de ferramenta para este servidor (padrão: false)
includeTools (string[]): Lista de nomes de ferramentas a serem incluídas deste servidor MCP. Quando especificado, apenas as ferramentas listadas aqui estarão disponíveis neste servidor (comportamento de allowlist). Se não especificado, todas as ferramentas do servidor são habilitadas por padrão.
excludeTools (string[]): Lista de nomes de ferramentas a serem excluídas deste servidor MCP. As ferramentas listadas aqui não estarão disponíveis para o modelo, mesmo que sejam expostas pelo servidor. Nota: excludeTools tem precedência sobre includeTools - se uma ferramenta estiver em ambas as listas, ela será excluída.
targetAudience (string): O OAuth Client ID na allowlist do aplicativo protegido por IAP que você está tentando acessar. Usado com authProviderType: 'service_account_impersonation'.
targetServiceAccount (string): O endereço de e-mail da Conta de Serviço do Google Cloud a ser personificada. Usado com authProviderType: 'service_account_impersonation'.

Suporte a OAuth para Servidores MCP Remotos

O Qwen Code suporta autenticação OAuth 2.0 para servidores MCP remotos usando transportes SSE ou HTTP. Isso permite acesso seguro a servidores MCP que exigem autenticação.

Descoberta Automática de OAuth

Para servidores que suportam descoberta de OAuth, você pode omitir a configuração de OAuth e deixar a CLI descobri-la automaticamente:


{
  "mcpServers": {
    "discoveredServer": {
      "url": "https://api.example.com/sse"
    }
  }
}

A CLI irá automaticamente:

Detectar quando um servidor exige autenticação OAuth (respostas 401)
Descobrir endpoints OAuth a partir dos metadados do servidor
Realizar registro dinâmico de cliente, se suportado
Gerenciar o fluxo OAuth e os tokens

Fluxo de Autenticação

Ao conectar-se a um servidor com OAuth habilitado:

Tentativa inicial de conexão falha com 401 Unauthorized
Descoberta de OAuth encontra os endpoints de autorização e token
O navegador é aberto para autenticação do usuário (requer acesso a um navegador local)
O código de autorização é trocado por tokens de acesso
Os tokens são armazenados de forma segura para uso futuro
A nova tentativa de conexão é bem-sucedida com tokens válidos

Requisitos de Redirecionamento do Navegador

Importante: A autenticação OAuth exige que sua máquina local possa:

Abrir um navegador web para autenticação
Receber redirecionamentos em http://localhost:7777/oauth/callback

Este recurso não funcionará em:

Ambientes headless sem acesso a navegador
Sessões SSH remotas sem encaminhamento X11
Ambientes containerizados sem suporte a navegador

Gerenciando Autenticação OAuth

Use o comando /mcp auth para gerenciar a autenticação OAuth:


# List servers requiring authentication
/mcp auth
 
# Authenticate with a specific server
/mcp auth serverName
 
# Re-authenticate if tokens expire
/mcp auth serverName

Propriedades de Configuração do OAuth

enabled (boolean): Habilita OAuth para este servidor
clientId (string): Identificador do cliente OAuth (opcional com registro dinâmico)
clientSecret (string): Segredo do cliente OAuth (opcional para clientes públicos)
authorizationUrl (string): Endpoint de autorização OAuth (descoberto automaticamente se omitido)
tokenUrl (string): Endpoint de token OAuth (descoberto automaticamente se omitido)
scopes (string[]): Scopes OAuth obrigatórios
redirectUri (string): URI de redirecionamento personalizado (padrão: http://localhost:7777/oauth/callback)
tokenParamName (string): Nome do parâmetro de query para tokens em URLs SSE
audiences (string[]): Audiências para as quais o token é válido

Gerenciamento de Tokens

Os tokens OAuth são automaticamente:

Armazenados de forma segura em ~/.qwen/mcp-oauth-tokens.json
Atualizados quando expiram (se refresh tokens estiverem disponíveis)
Validados antes de cada tentativa de conexão
Removidos quando inválidos ou expirados

Tipo de Provedor de Autenticação

Você pode especificar o tipo de provedor de autenticação usando a propriedade authProviderType:

authProviderType (string): Especifica o provedor de autenticação. Pode ser um dos seguintes:
- dynamic_discovery (padrão): A CLI descobrirá automaticamente a configuração de OAuth a partir do servidor.
- google_credentials: A CLI usará as Google Application Default Credentials (ADC) para autenticar com o servidor. Ao usar este provedor, você deve especificar os scopes obrigatórios.
- service_account_impersonation: A CLI personificará uma Conta de Serviço do Google Cloud para autenticar com o servidor. Isso é útil para acessar serviços protegidos por IAP (foi projetado especificamente para serviços do Cloud Run).

Credenciais do Google


{
  "mcpServers": {
    "googleCloudServer": {
      "httpUrl": "https://my-gcp-service.run.app/mcp",
      "authProviderType": "google_credentials",
      "oauth": {
        "scopes": ["https://www.googleapis.com/auth/userinfo.email"]
      }
    }
  }
}

Personificação de Conta de Serviço

Para autenticar com um servidor usando Personificação de Conta de Serviço, você deve definir authProviderType como service_account_impersonation e fornecer as seguintes propriedades:

targetAudience (string): O OAuth Client ID na allowlist do aplicativo protegido por IAP que você está tentando acessar.
targetServiceAccount (string): O endereço de e-mail da Conta de Serviço do Google Cloud a ser personificada.

A CLI usará suas Application Default Credentials (ADC) locais para gerar um token de ID OIDC para a conta de serviço e audiência especificadas. Esse token será então usado para autenticar com o servidor MCP.

Instruções de Configuração

Crie ou use um OAuth 2.0 client ID existente. Para usar um OAuth 2.0 client ID existente, siga as etapas em How to share OAuth Clients .
Adicione o OAuth ID à allowlist para acesso programático do aplicativo. Como o Cloud Run ainda não é um tipo de recurso suportado no gcloud iap, você deve adicionar o Client ID à allowlist no projeto.
Crie uma conta de serviço. Documentação , Link do Cloud Console
Adicione a conta de serviço e os usuários à Política do IAP na aba “Security” do próprio serviço Cloud Run ou via gcloud.
Conceda a todos os usuários e grupos que acessarão o Servidor MCP as permissões necessárias para personificar a conta de serviço (ou seja, roles/iam.serviceAccountTokenCreator).
Ative a IAM Credentials API para o seu projeto.

Exemplos de Configuração

Servidor MCP Python (Stdio)


{
  "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
    }
  }
}

Servidor MCP Node.js (Stdio)


{
  "mcpServers": {
    "nodeServer": {
      "command": "node",
      "args": ["dist/server.js", "--verbose"],
      "cwd": "./mcp-servers/node",
      "trust": true
    }
  }
}

Servidor MCP baseado em Docker


{
  "mcpServers": {
    "dockerizedServer": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "API_KEY",
        "-v",
        "${PWD}:/workspace",
        "my-mcp-server:latest"
      ],
      "env": {
        "API_KEY": "$EXTERNAL_SERVICE_TOKEN"
      }
    }
  }
}

Servidor MCP baseado em HTTP


{
  "mcpServers": {
    "httpServer": {
      "httpUrl": "http://localhost:3000/mcp",
      "timeout": 5000
    }
  }
}

Servidor MCP baseado em HTTP com Headers Personalizados


{
  "mcpServers": {
    "httpServerWithAuth": {
      "httpUrl": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-api-token",
        "X-Custom-Header": "custom-value",
        "Content-Type": "application/json"
      },
      "timeout": 5000
    }
  }
}

Servidor MCP com Filtragem de Ferramentas


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

Servidor MCP SSE com Personificação de SA


{
  "mcpServers": {
    "myIapProtectedServer": {
      "url": "https://my-iap-service.run.app/sse",
      "authProviderType": "service_account_impersonation",
      "targetAudience": "YOUR_IAP_CLIENT_ID.apps.googleusercontent.com",
      "targetServiceAccount": "your-sa@your-project.iam.gserviceaccount.com"
    }
  }
}

Aprofundamento no Processo de Descoberta

Quando o Qwen Code é iniciado, ele realiza a descoberta de servidores MCP por meio do seguinte processo detalhado:

1. Iteração e Conexão do Servidor

Para cada servidor configurado em mcpServers:

O rastreamento de status começa: O status do servidor é definido como CONNECTING
Seleção de transporte: Com base nas propriedades de configuração:
- httpUrl → StreamableHTTPClientTransport
- url → SSEClientTransport
- command → StdioClientTransport
Estabelecimento da conexão: O cliente MCP tenta conectar com o timeout configurado
Tratamento de erros: Falhas de conexão são registradas em log e o status do servidor é definido como DISCONNECTED

2. Descoberta de Ferramentas

Após uma conexão bem-sucedida:

Listagem de ferramentas: O cliente chama o endpoint de listagem de ferramentas do servidor MCP
Validação de schema: A declaração de função de cada ferramenta é validada
Filtragem de ferramentas: As ferramentas são filtradas com base na configuração includeTools e excludeTools
Limpeza de nomes: Os nomes das ferramentas são limpos para atender aos requisitos da API do Qwen:
- Caracteres inválidos (não alfanuméricos, exceto underscore, ponto e hífen) são substituídos por underscores
- Nomes com mais de 63 caracteres são truncados com substituição no meio (___)

3. Resolução de Conflitos

Quando múltiplos servidores expõem ferramentas com o mesmo nome:

O primeiro registro vence: O primeiro servidor a registrar um nome de ferramenta obtém o nome sem prefixo
Prefixação automática: Servidores subsequentes recebem nomes prefixados: serverName__toolName
Rastreamento no registro: O registro de ferramentas mantém mapeamentos entre nomes de servidores e suas ferramentas

4. Processamento de Schema

Os schemas de parâmetros das ferramentas passam por limpeza para compatibilidade com a API:

Propriedades $schema são removidas
additionalProperties são removidos
anyOf com default têm seus valores padrão removidos (compatibilidade com Vertex AI)
Processamento recursivo é aplicado a schemas aninhados

5. Gerenciamento de Conexão

Após a descoberta:

Conexões persistentes: Servidores que registram ferramentas com sucesso mantêm suas conexões
Limpeza: Servidores que não fornecem ferramentas utilizáveis têm suas conexões fechadas
Atualizações de status: Os status finais dos servidores são definidos como CONNECTED ou DISCONNECTED

Fluxo de Execução de Ferramentas

Quando o modelo decide usar uma ferramenta MCP, o seguinte fluxo de execução ocorre:

1. Invocação da Ferramenta

O modelo gera um FunctionCall com:

Nome da ferramenta: O nome registrado (potencialmente prefixado)
Argumentos: Objeto JSON correspondente ao schema de parâmetros da ferramenta

2. Processo de Confirmação

Cada DiscoveredMCPTool implementa uma lógica de confirmação sofisticada:

Bypass Baseado em Confiança


if (this.trust) {
  return false; // No confirmation needed
}

Allow-listing Dinâmico

O sistema mantém allow-lists internas para:

Nível de servidor: serverName → Todas as ferramentas deste servidor são confiáveis
Nível de ferramenta: serverName.toolName → Esta ferramenta específica é confiável

Gerenciamento de Escolha do Usuário

Quando a confirmação é necessária, os usuários podem escolher:

Prosseguir uma vez: Executar apenas desta vez
Sempre permitir esta ferramenta: Adicionar à allow-list de nível de ferramenta
Sempre permitir este servidor: Adicionar à allow-list de nível de servidor
Cancelar: Abortar execução

3. Execução

Após a confirmação (ou bypass de confiança):

Preparação de parâmetros: Os argumentos são validados em relação ao schema da ferramenta

Chamada MCP: O CallableTool subjacente invoca o servidor com:


const functionCalls = [
  {
    name: this.serverToolName, // Original server tool name
    args: params,
  },
];

Processamento de resposta: Os resultados são formatados tanto para o contexto do LLM quanto para exibição ao usuário

4. Gerenciamento de Resposta

O resultado da execução contém:

llmContent: Partes brutas da resposta para o contexto do modelo de linguagem
returnDisplay: Saída formatada para exibição ao usuário (geralmente JSON em blocos de código markdown)

Como interagir com seu servidor MCP

Usando o Comando `/mcp`

O comando /mcp fornece informações abrangentes sobre a configuração do seu servidor MCP:


/mcp

Isso exibe:

Lista de servidores: Todos os servidores MCP configurados
Status da conexão: CONNECTED, CONNECTING ou DISCONNECTED
Detalhes do servidor: Resumo da configuração (excluindo dados sensíveis)
Ferramentas disponíveis: Lista de ferramentas de cada servidor com descrições
Estado da descoberta: Status geral do processo de descoberta

Exemplo de Saída do `/mcp`


MCP Servers Status:

📡 pythonTools (CONNECTED)
  Command: python -m my_mcp_server --port 8080
  Working Directory: ./mcp-servers/python
  Timeout: 15000ms
  Tools: calculate_sum, file_analyzer, data_processor

🔌 nodeServer (DISCONNECTED)
  Command: node dist/server.js --verbose
  Error: Connection refused

🐳 dockerizedServer (CONNECTED)
  Command: docker run -i --rm -e API_KEY my-mcp-server:latest
  Tools: docker__deploy, docker__status

Discovery State: COMPLETED

Uso de Ferramentas

Uma vez descobertas, as ferramentas MCP ficam disponíveis para o modelo Qwen como ferramentas nativas. O modelo irá automaticamente:

Selecionar ferramentas apropriadas com base nas suas solicitações
Apresentar diálogos de confirmação (a menos que o servidor seja confiável)
Executar ferramentas com os parâmetros adequados
Exibir resultados em um formato amigável ao usuário

Monitoramento de Status e Solução de Problemas

Estados de Conexão

A integração MCP rastreia vários estados:

Status do Servidor (`MCPServerStatus`)

DISCONNECTED: O servidor não está conectado ou possui erros
CONNECTING: Tentativa de conexão em andamento
CONNECTED: O servidor está conectado e pronto

Estado da Descoberta (`MCPDiscoveryState`)

NOT_STARTED: A descoberta não começou
IN_PROGRESS: Descobrindo servidores no momento
COMPLETED: Descoberta finalizada (com ou sem erros)

Problemas Comuns e Soluções

O Servidor Não Conecta

Sintomas: O servidor mostra o status DISCONNECTED

Solução de problemas:

Verifique a configuração: Confirme se command, args e cwd estão corretos
Teste manualmente: Execute o comando do servidor diretamente para garantir que funciona
Verifique dependências: Garanta que todos os pacotes obrigatórios estão instalados
Revise os logs: Procure mensagens de erro na saída da CLI
Verifique permissões: Garanta que a CLI pode executar o comando do servidor

Nenhuma Ferramenta Descoberta

Sintomas: O servidor conecta, mas nenhuma ferramenta está disponível

Solução de problemas:

Verifique o registro de ferramentas: Garanta que seu servidor realmente registra ferramentas
Verifique o protocolo MCP: Confirme se seu servidor implementa a listagem de ferramentas MCP corretamente
Revise os logs do servidor: Verifique a saída stderr para erros no lado do servidor
Teste a listagem de ferramentas: Teste manualmente o endpoint de descoberta de ferramentas do seu servidor

Ferramentas Não Executam

Sintomas: As ferramentas são descobertas, mas falham durante a execução

Solução de problemas:

Validação de parâmetros: Garanta que sua ferramenta aceita os parâmetros esperados
Compatibilidade de schema: Verifique se seus schemas de entrada são JSON Schema válidos
Tratamento de erros: Verifique se sua ferramenta está lançando exceções não tratadas
Problemas de timeout: Considere aumentar a configuração timeout

Compatibilidade com Sandbox

Sintomas: Servidores MCP falham quando o sandboxing está habilitado

Soluções:

Servidores baseados em Docker: Use containers Docker que incluam todas as dependências
Acessibilidade de caminho: Garanta que os executáveis do servidor estejam disponíveis no sandbox
Acesso à rede: Configure o sandbox para permitir as conexões de rede necessárias
Variáveis de ambiente: Verifique se as variáveis de ambiente obrigatórias são repassadas

Dicas de Depuração

Habilite o modo debug: Execute a CLI com --debug para saída detalhada
Verifique stderr: O stderr do servidor MCP é capturado e registrado em log (mensagens INFO filtradas)
Teste isolado: Teste seu servidor MCP independentemente antes de integrar
Configuração incremental: Comece com ferramentas simples antes de adicionar funcionalidades complexas
Use /mcp frequentemente: Monitore o status do servidor durante o desenvolvimento

Notas Importantes

Considerações de Segurança

Configurações de confiança: A opção trust ignora todos os diálogos de confirmação. Use com cautela e apenas para servidores que você controla completamente
Tokens de acesso: Tenha consciência de segurança ao configurar variáveis de ambiente contendo API keys ou tokens
Compatibilidade com sandbox: Ao usar sandboxing, garanta que os servidores MCP estejam disponíveis dentro do ambiente sandbox
Dados privados: O uso de personal access tokens com escopo amplo pode levar ao vazamento de informações entre repositórios

Desempenho e Gerenciamento de Recursos

Persistência de conexão: A CLI mantém conexões persistentes com servidores que registram ferramentas com sucesso
Limpeza automática: Conexões com servidores que não fornecem ferramentas são fechadas automaticamente
Gerenciamento de timeout: Configure timeouts apropriados com base nas características de resposta do seu servidor
Monitoramento de recursos: Servidores MCP rodam como processos separados e consomem recursos do sistema

Compatibilidade de Schema

Modo de conformidade de schema: Por padrão (schemaCompliance: "auto"), os schemas das ferramentas são repassados como estão. Defina "model": { "generationConfig": { "schemaCompliance": "openapi_30" } } no seu settings.json para converter modelos para o formato Strict OpenAPI 3.0.
Transformações OpenAPI 3.0: Quando o modo openapi_30 está habilitado, o sistema lida com:
- Tipos nullable: ["string", "null"] -> type: "string", nullable: true
- Valores const: const: "foo" -> enum: ["foo"]
- Limites exclusivos: exclusiveMinimum numérico -> forma booleana com minimum
- Remoção de keywords: $schema, $id, dependencies, patternProperties
Limpeza de nomes: Os nomes das ferramentas são limpos automaticamente para atender aos requisitos da API
Resolução de conflitos: Conflitos de nomes de ferramentas entre servidores são resolvidos por meio de prefixação automática

Essa integração abrangente torna os servidores MCP uma maneira poderosa de estender os recursos da CLI, mantendo segurança, confiabilidade e facilidade de uso.

Retornando Conteúdo Rico de Ferramentas

As ferramentas MCP não se limitam a retornar texto simples. Você pode retornar conteúdo rico e multipartes, incluindo texto, imagens, áudio e outros dados binários em uma única resposta de ferramenta. Isso permite criar ferramentas poderosas que podem fornecer informações diversificadas ao modelo em uma única interação.

Todos os dados retornados pela ferramenta são processados e enviados ao modelo como contexto para sua próxima geração, permitindo que ele raciocine ou resuma as informações fornecidas.

Como Funciona

Para retornar conteúdo rico, a resposta da sua ferramenta deve aderir à especificação MCP para um CallToolResult. O campo content do resultado deve ser um array de objetos ContentBlock. A CLI processará corretamente esse array, separando texto de dados binários e empacotando-o para o modelo.

Você pode combinar diferentes tipos de blocos de conteúdo no array content. Os tipos de blocos suportados incluem:

text
image
audio
resource (conteúdo embutido)
resource_link

Exemplo: Retornando Texto e uma Imagem

Aqui está um exemplo de uma resposta JSON válida de uma ferramenta MCP que retorna tanto uma descrição em texto quanto uma imagem:


{
  "content": [
    {
      "type": "text",
      "text": "Here is the logo you requested."
    },
    {
      "type": "image",
      "data": "BASE64_ENCODED_IMAGE_DATA_HERE",
      "mimeType": "image/png"
    },
    {
      "type": "text",
      "text": "The logo was created in 2025."
    }
  ]
}

Quando o Qwen Code recebe essa resposta, ele irá:

Extrair todo o texto e combiná-lo em uma única parte functionResponse para o modelo.
Apresentar os dados da imagem como uma parte inlineData separada.
Fornecer um resumo limpo e amigável na CLI, indicando que tanto texto quanto uma imagem foram recebidos.

Isso permite que você crie ferramentas sofisticadas que podem fornecer contexto rico e multimodal ao modelo Qwen.

Prompts MCP como Comandos de Barra

Além de ferramentas, servidores MCP podem expor prompts predefinidos que podem ser executados como comandos de barra dentro do Qwen Code. Isso permite criar atalhos para consultas comuns ou complexas que podem ser facilmente invocadas pelo nome.

Definindo Prompts no Servidor

Aqui está um pequeno exemplo de um servidor MCP stdio que define prompts:


import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';
 
const server = new McpServer({
  name: 'prompt-server',
  version: '1.0.0',
});
 
server.registerPrompt(
  'poem-writer',
  {
    title: 'Poem Writer',
    description: 'Write a nice haiku',
    argsSchema: { title: z.string(), mood: z.string().optional() },
  },
  ({ title, mood }) => ({
    messages: [
      {
        role: 'user',
        content: {
          type: 'text',
          text: `Write a haiku${mood ? ` with the mood ${mood}` : ''} called ${title}. Note that a haiku is 5 syllables followed by 7 syllables followed by 5 syllables `,
        },
      },
    ],
  }),
);
 
const transport = new StdioServerTransport();
await server.connect(transport);

Isso pode ser incluído no settings.json sob mcpServers com:


{
  "mcpServers": {
    "nodeServer": {
      "command": "node",
      "args": ["filename.ts"]
    }
  }
}

Invocando Prompts

Uma vez que um prompt é descoberto, você pode invocá-lo usando seu nome como um comando de barra. A CLI lidará automaticamente com a análise de argumentos.


/poem-writer --title="Qwen Code" --mood="reverent"

ou, usando argumentos posicionais:


/poem-writer "Qwen Code" reverent

Ao executar este comando, a CLI executa o método prompts/get no servidor MCP com os argumentos fornecidos. O servidor é responsável por substituir os argumentos no template do prompt e retornar o texto final do prompt. A CLI então envia esse prompt ao modelo para execução. Isso fornece uma maneira conveniente de automatizar e compartilhar fluxos de trabalho comuns.

Gerenciando Servidores MCP com `qwen mcp`

Embora você sempre possa configurar servidores MCP editando manualmente seu arquivo settings.json, a CLI fornece um conjunto conveniente de comandos para gerenciar suas configurações de servidor programaticamente. Esses comandos agilizam o processo de adicionar, listar e remover servidores MCP sem a necessidade de editar arquivos JSON diretamente.

Adicionando um Servidor (`qwen mcp add`)

O comando add configura um novo servidor MCP no seu settings.json. Com base no escopo (-s, --scope), ele será adicionado à configuração de usuário ~/.qwen/settings.json ou à configuração de projeto .qwen/settings.json.

Comando:


qwen mcp add [options] <name> <commandOrUrl> [args...]

<name>: Um nome exclusivo para o servidor.
<commandOrUrl>: O comando a ser executado (para stdio) ou a URL (para http/sse).
[args...]: Argumentos opcionais para um comando stdio.

Opções (Flags):

-s, --scope: Escopo da configuração (user ou project). [padrão: “project”]
-t, --transport: Tipo de transporte (stdio, sse, http). [padrão: “stdio”]
-e, --env: Define variáveis de ambiente (ex.: -e KEY=value).
-H, --header: Define headers HTTP para transportes SSE e HTTP (ex.: -H “X-Api-Key: abc123” -H “Authorization: Bearer abc123”).
--timeout: Define o timeout de conexão em milissegundos.
--trust: Confia no servidor (ignora todos os prompts de confirmação de chamada de ferramenta).
--description: Define a descrição para o servidor.
--include-tools: Uma lista separada por vírgulas de ferramentas a serem incluídas.
--exclude-tools: Uma lista separada por vírgulas de ferramentas a serem excluídas.

Adicionando um servidor stdio

Este é o transporte padrão para executar servidores locais.


# Basic syntax
qwen mcp add <name> <command> [args...]
 
# Example: Adding a local server
qwen mcp add my-stdio-server -e API_KEY=123 /path/to/server arg1 arg2 arg3
 
# Example: Adding a local python server
qwen mcp add python-server python server.py --port 8080

Adicionando um servidor HTTP

Este transporte é para servidores que usam o transporte streamable HTTP.


# Basic syntax
qwen mcp add --transport http <name> <url>
 
# Example: Adding an HTTP server
qwen mcp add --transport http http-server https://api.example.com/mcp/
 
# Example: Adding an HTTP server with an authentication header
qwen mcp add --transport http secure-http https://api.example.com/mcp/ --header "Authorization: Bearer abc123"

Adicionando um servidor SSE

Este transporte é para servidores que usam Server-Sent Events (SSE).


# Basic syntax
qwen mcp add --transport sse <name> <url>
 
# Example: Adding an SSE server
qwen mcp add --transport sse sse-server https://api.example.com/sse/
 
# Example: Adding an SSE server with an authentication header
qwen mcp add --transport sse secure-sse https://api.example.com/sse/ --header "Authorization: Bearer abc123"

Gerenciando Servidores (`qwen mcp`)

Para visualizar e gerenciar todos os servidores MCP atualmente configurados, use o comando manage ou simplesmente qwen mcp. Isso abre um diálogo TUI interativo onde você pode:

Visualizar todos os servidores MCP com seu status de conexão
Habilitar/desabilitar servidores
Reconectar a servidores desconectados
Visualizar ferramentas e prompts fornecidos por cada servidor
Visualizar logs do servidor

Comando:


qwen mcp
# or
qwen mcp manage

O diálogo de gerenciamento fornece uma interface visual mostrando o nome de cada servidor, detalhes de configuração, status de conexão e ferramentas/prompts disponíveis.

Removendo um Servidor (`qwen mcp remove`)

Para excluir um servidor da sua configuração, use o comando remove com o nome do servidor.

Comando:


qwen mcp remove <name>

Exemplo:


qwen mcp remove my-server

Isso encontrará e excluirá a entrada “my-server” do objeto mcpServers no arquivo settings.json apropriado com base no escopo (-s, --scope).

Servidores MCP com Qwen Code

O que é um servidor MCP?

Arquitetura de Integração Principal

Camada de Descoberta (mcp-client.ts)

Camada de Execução (mcp-tool.ts)

Mecanismos de Transporte

Como configurar seu servidor MCP

Configure o servidor MCP no settings.json

Configurações Globais do MCP (mcp)

Configuração Específica do Servidor (mcpServers)

Estrutura de Configuração

Propriedades de Configuração

Obrigatório (um dos seguintes)

Opcional

Suporte a OAuth para Servidores MCP Remotos

Descoberta Automática de OAuth

Fluxo de Autenticação

Requisitos de Redirecionamento do Navegador

Gerenciando Autenticação OAuth

Propriedades de Configuração do OAuth

Gerenciamento de Tokens

Tipo de Provedor de Autenticação

Credenciais do Google

Personificação de Conta de Serviço

Instruções de Configuração

Exemplos de Configuração

Servidor MCP Python (Stdio)

Servidor MCP Node.js (Stdio)

Servidor MCP baseado em Docker

Servidor MCP baseado em HTTP

Servidor MCP baseado em HTTP com Headers Personalizados

Servidor MCP com Filtragem de Ferramentas

Servidor MCP SSE com Personificação de SA

Aprofundamento no Processo de Descoberta

1. Iteração e Conexão do Servidor

2. Descoberta de Ferramentas

3. Resolução de Conflitos

4. Processamento de Schema

5. Gerenciamento de Conexão

Fluxo de Execução de Ferramentas

1. Invocação da Ferramenta

2. Processo de Confirmação

Bypass Baseado em Confiança

Allow-listing Dinâmico

Gerenciamento de Escolha do Usuário

3. Execução

4. Gerenciamento de Resposta

Como interagir com seu servidor MCP

Usando o Comando /mcp

Exemplo de Saída do /mcp

Uso de Ferramentas

Monitoramento de Status e Solução de Problemas

Estados de Conexão

Status do Servidor (MCPServerStatus)

Estado da Descoberta (MCPDiscoveryState)

Problemas Comuns e Soluções

O Servidor Não Conecta

Nenhuma Ferramenta Descoberta

Ferramentas Não Executam

Compatibilidade com Sandbox

Dicas de Depuração

Notas Importantes

Considerações de Segurança

Desempenho e Gerenciamento de Recursos

Compatibilidade de Schema

Retornando Conteúdo Rico de Ferramentas

Como Funciona

Exemplo: Retornando Texto e uma Imagem

Prompts MCP como Comandos de Barra

Definindo Prompts no Servidor

Invocando Prompts

Gerenciando Servidores MCP com qwen mcp

Adicionando um Servidor (qwen mcp add)

Adicionando um servidor stdio

Adicionando um servidor HTTP

Adicionando um servidor SSE

Gerenciando Servidores (qwen mcp)

Removendo um Servidor (qwen mcp remove)

Camada de Descoberta (`mcp-client.ts`)

Camada de Execução (`mcp-tool.ts`)

Configurações Globais do MCP (`mcp`)

Configuração Específica do Servidor (`mcpServers`)

Usando o Comando `/mcp`

Exemplo de Saída do `/mcp`

Status do Servidor (`MCPServerStatus`)

Estado da Descoberta (`MCPDiscoveryState`)

Gerenciando Servidores MCP com `qwen mcp`

Adicionando um Servidor (`qwen mcp add`)

Gerenciando Servidores (`qwen mcp`)

Removendo um Servidor (`qwen mcp remove`)