Connect Qwen Code to tools via MCP

Qwen Code can connect to external tools and data sources through the Model Context Protocol (MCP). MCP servers give Qwen Code access to your tools, databases, and APIs.

What you can do with MCP

With MCP servers connected, you can ask Qwen Code to:

• Work with files and repos (read/search/write, depending on the tools you enable)
• Query databases (schema inspection, queries, reporting)
• Integrate internal services (wrap your APIs as MCP tools)
• Automate workflows (repeatable tasks exposed as tools/prompts)

[!tip]

If you’re looking for the “one command to get started”, jump to Quick start.

Quick start

Qwen Code loads MCP servers from mcpServers in your settings.json. You can configure servers either:

• By editing settings.json directly
• By using qwen mcp commands (see CLI reference)

Add your first server

1. Add a server (example: remote HTTP MCP server):

qwen mcp add --transport http my-server http://localhost:3000/mcp

2. Open MCP management dialog to view and manage servers:

qwen mcp

3. Restart Qwen Code in the same project (or start it if it wasn’t running yet), then ask the model to use tools from that server.

Where configuration is stored (scopes)

Most users only need these two scopes:

• Project scope (default): .qwen/settings.json in your project root
• User scope: ~/.qwen/settings.json across all projects on your machine

Write to user scope:

qwen mcp add --scope user --transport http my-server http://localhost:3000/mcp

[!tip]

For advanced configuration layers (system defaults/system settings and precedence rules), see Settings.

Configure servers

Choose a transport

[!note]

If a server supports both, prefer HTTP over SSE.

Configure via settings.json vs qwen mcp add

Both approaches produce the same mcpServers entries in your settings.json—use whichever you prefer.

Stdio server (local process)

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 (writes to project scope by default):

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

HTTP server (remote streamable HTTP)

JSON:

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

CLI:

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

SSE server (remote Server-Sent Events)

JSON:

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

CLI:

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

Safety and control

Trust (skip confirmations)

• Server trust (trust: true): bypasses confirmation prompts for that server (use sparingly).

OAuth authentication

Qwen Code supports OAuth 2.0 authentication for MCP servers. This is useful when accessing remote servers that require authentication.

Basic usage

When you add an MCP server with OAuth credentials, Qwen Code will automatically handle the authentication flow:

qwen mcp add --transport sse oauth-server https://api.example.com/sse/ \
  --oauth-client-id your-client-id \
  --oauth-redirect-uri https://your-server.com/oauth/callback \
  --oauth-authorization-url https://provider.example.com/authorize \
  --oauth-token-url https://provider.example.com/token

Important: Redirect URI configuration

The OAuth flow requires a redirect URI where the authorization provider sends the authentication code.

• Local development: By default, Qwen Code uses http://localhost:7777/oauth/callback. This works when running Qwen Code on your local machine with a local browser.

• Remote/cloud deployments: When running Qwen Code on remote servers, cloud IDEs, or web terminals, the default localhost redirect will NOT work. You MUST configure --oauth-redirect-uri to point to a publicly accessible URL that can receive the OAuth callback.

Example for remote servers:

qwen mcp add --transport sse remote-server https://api.example.com/sse/ \
  --oauth-redirect-uri https://your-remote-server.example.com/oauth/callback

Manual configuration via settings.json

You can also configure OAuth by editing settings.json directly:

{
  "mcpServers": {
    "oauthServer": {
      "url": "https://api.example.com/sse/",
      "oauth": {
        "enabled": true,
        "clientId": "your-client-id",
        "clientSecret": "your-client-secret",
        "authorizationUrl": "https://provider.example.com/authorize",
        "tokenUrl": "https://provider.example.com/token",
        "redirectUri": "https://your-server.com/oauth/callback",
        "scopes": ["read", "write"]
      }
    }
  }
}

OAuth configuration properties:

Token management

OAuth tokens are automatically:

• Stored securely in ~/.qwen/mcp-oauth-tokens.json
• Refreshed when expired (if refresh tokens are available)
• Validated before each connection attempt

Use the /mcp auth command within Qwen Code to manage OAuth authentication interactively.

Tool filtering (allow/deny tools per server)

Use includeTools / excludeTools to restrict tools exposed by a server (from Qwen Code’s perspective).

Example: include only a few tools:

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

Global allow/deny lists

The mcp object in your settings.json defines global rules for all MCP servers:

• mcp.allowed: allow-list of MCP server names (keys in mcpServers)
• mcp.excluded: deny-list of MCP server names

Example:

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

Troubleshooting

• Server shows “Disconnected” in qwen mcp list: verify the URL/command is correct, then increase timeout.
• Stdio server fails to start: use an absolute command path, and double-check cwd/env.
• Environment variables in JSON don’t resolve: ensure they exist in the environment where Qwen Code runs (shell vs GUI app environments can differ).

Reference

settings.json structure

Server-specific configuration (mcpServers)

Add an mcpServers object to your settings.json file:

// ... 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
    }
  }
}

Configuration properties:

Required (one of the following):

Optional:

<a id="qwen-mcp-cli"></a>

Manage MCP servers with qwen mcp

You can always configure MCP servers by manually editing settings.json, but the CLI is usually faster.

Adding a server (qwen mcp add)

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

--oauth-* flags apply only to --transport sse and --transport http. Combining them with --transport stdio is rejected.

Removing a server (qwen mcp remove)

qwen mcp remove <name>