How to Add a Remote MCP Server to Qwen Code

How do I add a remote MCP server to Qwen Code?

Add the server to ~/.qwen/settings.json under mcpServers using the httpUrl key, then run /mcp inside Qwen Code, select the server, and choose its Auth action to approve in the browser. Qwen Code discovers the OAuth endpoint and registers itself automatically via dynamic client registration, so there are no credentials to obtain first. The httpUrl-not-url detail is the one that matters — it is inherited from the Gemini CLI lineage Qwen Code is built on.

Availability

The old Qwen OAuth free model tier was discontinued on April 15, 2026. The CLI itself remains free and open source, but you now bring your own model access — via the Alibaba Cloud coding plan, ModelScope's free tier, OpenRouter, or any compatible endpoint.

Whichever model route you pick, the MCP setup below is identical. Model access and MCP are separate concerns here, which is a theme worth carrying into the troubleshooting section.

Adding the server

Edit ~/.qwen/settings.json for a global setup, or .qwen/settings.json inside a project for project-only scope:

{
  "mcpServers": {
    "my-server": {
      "httpUrl": "https://mcp.example.com/mcp"
    }
  }
}

The key is httpUrl, not url. In Qwen Code, httpUrl means Streamable HTTP — the transport hosted MCP servers use. A plain url key means the legacy SSE transport and won't connect correctly.

The failure this produces is the annoying kind: not a rejection, but a server that connects and then times out or behaves oddly. If you are debugging strange behavior rather than an outright failure, check this key first.

Authorization

Start Qwen Code and open the MCP dialog:

/mcp

Select your server in the dialog, then choose its Auth action. Qwen Code discovers the server's OAuth endpoint and registers itself automatically — dynamic client registration is the default — and a browser tab opens with the consent screen. Sign in if prompted and approve. Tokens are stored in ~/.qwen/mcp-oauth-tokens.json and refreshed automatically.

The same /mcp dialog shows server status, so it is both where you authenticate and where you check the connection. Note that Qwen Code has no /mcp auth command — authentication moved into this dialog. /mcp auth <name> is a Gemini CLI command, and although Qwen Code inherits much of Gemini CLI's config shape (the httpUrl key above being the clearest example), it does not inherit that one.

What usually goes wrong

• Connects but behaves oddly or times out. url instead of httpUrl — url selects legacy SSE. Switch the key and restart.
• Connection fails immediately. Check the URL against exactly what the server publishes, including the path and any trailing slash.
• The browser doesn't open for authorization. Some terminal environments print the authorization link instead — look for an https:// URL in the output and open it manually. Also check pop-up blockers and your default browser setting.
• "Unauthorized" or stale-token errors. Delete the server's entry from ~/.qwen/mcp-oauth-tokens.json, then re-run the Auth action from the /mcp dialog for fresh tokens.
• /mcp auth reports an unknown command. There is no /mcp auth in Qwen Code — that is a Gemini CLI command, and Qwen Code inherits much of its config shape from Gemini CLI but not this. Authentication is managed inside the /mcp dialog instead.

Model errors are not server errors

Because you bring your own model route, there are two independent systems that can fail, and conflating them wastes time.

Errors mentioning quotas, endpoints, or your provider are the model route — your coding plan, ModelScope, or OpenRouter configuration. Fix them in your provider configuration, not in settings.json.

Errors naming the server, or OAuth, are the MCP connection. Fix them with the steps above.

A worked example

With a real server — Tempreon, a hosted MCP server that carries your context across every tool you connect:

{
  "mcpServers": {
    "tempreon": {
      "httpUrl": "https://api.tempreon.com/functions/v1/tempreon-mcp/mcp"
    }
  }
}

Then run /mcp, select tempreon, choose Auth, and approve in the browser. Because MCP lives in the harness rather than the model, the same connection works whichever model route you have configured — and keeps working if you change it. The account-holder walkthrough is in the Qwen Code setup doc.