Add a Remote MCP Server to Amazon Q Developer (CLI and IDE)

How to add a remote MCP server to Amazon Q Developer: the type http entry in a Q CLI agent file, the IDE's add-server form with URL and headers, OAuth sign-in through /mcp, the init timeout, the move to Kiro CLI, and fixing a server that will not connect.

MCP Hunter team 27 October 2026 6 min read

Amazon Q Developer CLI takes a remote MCP server as one entry with a type and a url in your agent configuration file [1]:

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp"
    }
  }
}

In the IDE plugin, you add the same server through a form in the chat panel instead, and Q writes the file for you [2].

Everything below is checked against AWS's Amazon Q Developer user guide and the Q Developer CLI repository on 27 October 2026 [1][2][3][4].

TL;DR:

Q Developer CLI now ships as Kiro CLI. The open-source CLI repository says it "is no longer being actively maintained and will only receive critical security fixes", and that "Amazon Q Developer CLI is now available as Kiro CLI, a closed-source product" [4]. On Kiro, follow the Kiro guide.
Write "type": "http" with the server's url. A remote server can be open or use OAuth [1].
OAuth starts from /mcp in a CLI session, which hands you a sign-in URL to open in the browser [1].
The IDE plugin works in VS Code and JetBrains and takes a URL, optional headers and a timeout in its add-server form [2].

Where the entry goes

Surface	Where	How you add it
Q Developer CLI	An agent file under `~/.aws/amazonq/cli-agents` [3]	Edit the agent's `mcpServers` field [1]
Q in the IDE, every project	`~/.aws/amazonq/default.json` [2]	The add-server form, global scope [2]
Q in the IDE, one project	`.amazonq/default.json` in the project [2]	The add-server form, local scope [2]
Legacy, both	`~/.aws/amazonq/mcp.json` and `.amazonq/mcp.json` [2][5]	Read only while `useLegacyMcpJson` is `true`, which is the default [2]

AWS's MCP overview gives the IDE's global file as ~/.aws/amazonq/agents/default.json [3], while its IDE page says ~/.aws/amazonq/default.json [2]. If you add the server through the form, you do not need to know which: Q writes it where it reads it.

In the IDE, the workspace configuration wins over the global one for servers, their permissions and settings [2].

Add the server in the CLI

Put the entry at the top in the mcpServers field of the agent you start Q with [1]. The URL is the MCP endpoint itself, usually ending in /mcp, not the product's homepage or its docs page.

Q loads MCP servers in the background, so you can start typing before every server is ready, and tools appear as each server finishes loading [3]. Run /tools to see which servers are still loading and which tools are already there [3].

The CLI also has commands for managing servers: add, remove, list, import and status, which AWS's reference writes as qchat mcp <command> [1]. status reports on one configured server [1].

A remote server that asks for OAuth starts out as "not yet loaded" [1]. Then [1]:

Run /mcp in the Q CLI session.
Q says the server needs authentication and prints a URL.
Open that URL in your browser, with the Q session still open, and sign in.
Go back to the terminal. The server's tools appear once sign-in succeeds.

In the IDE, Q opens the browser sign-in page on its own when an HTTP server needs authorization [2]. MCP OAuth covers what a server has to publish for that sign-in to work.

Add the server in the IDE

In VS Code, JetBrains or another supported IDE [2]:

Open the Q Developer panel, then the Chat panel, and choose the tools icon.
Choose the plus (+) symbol and pick global or local scope.
Enter a Name, select http as the transport, and paste the server's endpoint into URL.
Under Headers - optional, add any header the server needs, such as Authorization with Bearer and your key.
Set a Timeout if the server is slow, then choose Save.

Saving opens the tool permissions panel, where each tool is set to Ask, Always allow or Deny [2].

Choose which tools run without asking

In a CLI agent file, MCP tools are named with an @ prefix: @my-server covers every tool on that server and @my-server/search covers one [5]. The allowedTools list accepts those names and patterns with * and ?, such as "@my-server/read_*", but not a bare "*" [5]. Matching is case-sensitive [5].

When it will not connect

What you see	Usual cause	Fix
The server stays "not yet loaded"	It needs OAuth and nobody has signed in	Run `/mcp` and open the URL it prints [1]
No tools, or an error from the server	The URL is the homepage or docs page	Use the endpoint, usually ending in `/mcp`
You start chatting before the server's tools are ready	Q loads servers in the background	Check `/tools`; raise the wait with `q settings mcp.initTimeout <milliseconds>` [3]
An alert in the IDE panel after saving	The connection failed	Choose Fix Configuration and correct the entry [2]
A server from an old `mcp.json` appears or will not go away	`useLegacyMcpJson` is `true` by default	Move it into the agent or `default.json`, or set the field to `false` [2][5]
A server set globally behaves differently in one project	The project's `.amazonq/default.json` wins	Check the local file [2]
A tool runs without asking, or never runs	Its permission level or `allowedTools` pattern	Change it in the permissions panel, or fix the pattern's case [2][5]

For what the server's own error codes mean, see MCP server errors and MCP server connection failed.

Amazon Q connects from your own machine, so a server on localhost or your VPN works for you and for nobody else. Our MCP connection test calls your server from our network, runs the handshake and tools/list, and reports what a stranger on the internet gets back, with a dated URL you can share. If it passes there and fails in Q, the problem is in your configuration, not the server.

The same setup in other clients is in Kiro, Cursor, VS Code, Cline, Continue, Windsurf, Roo Code, LM Studio, Raycast, Claude Code, Codex, Gemini CLI, GitHub Copilot CLI, Claude Desktop and ChatGPT, and remote MCP server vs stdio covers whether your server should have a public address at all.