Amazon Q Developer CLI MCP Server Setup 2026: mcp.json Configuration Guide

Amazon Q Developer CLI reads MCP server definitions from mcp.json — either globally at ~/.aws/amazonq/mcp.json or per-project at .amazonq/mcp.json — and loads them automatically when you start a q chat session. This guide covers both config locations, the q mcp command family for managing servers without hand-editing JSON, and how remote HTTP servers with OAuth differ from a local stdio server.

Key Takeaways

Prerequisites

Step 1: Decide Global vs. Workspace Config

Put a server in ~/.aws/amazonq/mcp.json if you want it available in every project — a search server, a general-purpose fetch tool, something not tied to one codebase.

Put it in .amazonq/mcp.json at the repo root if it's project-specific — a database connection string for this app's dev database, or an internal tool only relevant to this repo. This file can be committed (without secrets baked in — use env references or a .env file your shell loads before q chat starts) so teammates get the same server list automatically.

Step 2: Write the Config

Create the file if it doesn't exist, and add an mcpServers block:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://USERNAME:PASSWORD@HOST:5432/DBNAME"
      ]
    }
  }
}

For a server that needs environment variables instead of an inline connection string:

{
  "mcpServers": {
    "awslabs.cdk-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.cdk-mcp-server@latest"],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      }
    }
  }
}

Note the uvx command here — several of AWS's own reference MCP servers (the awslabs.* packages) ship as Python packages run through uv/uvx rather than npx, so don't assume every entry in your config will look like a Node package.

Step 3: Or Skip the JSON and Use the CLI

q mcp add writes the same config for you:

q mcp add --name postgres --command npx --args "-y,@modelcontextprotocol/server-postgres,postgresql://USERNAME:PASSWORD@HOST:5432/DBNAME"

If an argument itself contains a comma, either escape it or pass the whole --args value as a JSON array instead:

q mcp add --name server --command cmd --args '["arg1", "arg2,with,commas", "arg3"]'

Other commands you'll use regularly:

q mcp list              # show every configured server and its scope (global/workspace)
q mcp status --name postgres   # check whether a specific server is connected
q mcp remove --name postgres   # delete a server entry
q mcp import <file>      # pull server definitions from another mcp.json

Step 4: Start a Chat Session and Verify

q chat

On startup, Q CLI reports which servers loaded:

✓ postgres loaded in 0.42 s
✓ 1 of 1 mcp servers initialized

If a server fails, you'll see it listed as failed instead, with the underlying error — a missing binary, a bad connection string, or a nonzero exit code from the server process are the most common causes.

Inside the session, run /tools trust to see which tools each connected server exposes and whether they're currently trusted to run without a confirmation prompt.

Remote MCP Servers (HTTP + OAuth)

Amazon Q Developer CLI also supports remote servers that talk over HTTP instead of running as a local subprocess. The config shape is different — no command/args, just a type and a URL:

{
  "mcpServers": {
    "find-a-domain": {
      "type": "http",
      "url": "https://api.findadomain.dev/mcp"
    }
  }
}

Some remote servers are open with no auth required; others require OAuth. For an OAuth-protected server:

1. Start q chat with the server configured — it will initially show as "not yet loaded."
2. Run /mcp to begin authentication.
3. Q CLI prints a URL — open it in your browser while keeping the CLI session running.
4. Complete the sign-in flow in the browser.
5. Return to the terminal; the server should now show as connected, and its tools become available.

This matters if you're deciding between a local server and a hosted one for the same integration: local (stdio) servers run entirely on your machine and need a runtime (Node, Python) installed; remote (HTTP) servers run somewhere else and only need network access, at the cost of an OAuth dance the first time and a dependency on that host staying up. See local vs. remote MCP servers for the broader tradeoff, which applies the same way across every MCP client, not just Q CLI.

Where This Fits If You're Already on AWS

Because Amazon Q Developer CLI is AWS's own tool, it pairs naturally with AWS-native MCP servers rather than requiring you to bolt on third-party ones. If your workflow touches AWS resources directly — EC2, S3, IAM policy review — the AWS MCP server setup guide covers the read-only IAM policy pattern worth applying here too, since the underlying risk (an MCP server executing AWS API calls with whatever credentials your shell has active) is identical regardless of which client is driving it. If your infrastructure is defined in DynamoDB tables rather than a relational schema, the DynamoDB MCP server guide covers AWS's official server for that.

Troubleshooting

Server shows as failed on startup
Run the command from your config directly in a terminal (e.g. npx -y @modelcontextprotocol/server-postgres "connection-string"). If it errors outside of Q CLI too, the problem is the server or its arguments, not the CLI integration.

"command not found" for uvx or npx
Q CLI runs server processes using whatever's on your PATH at launch time — if you installed Node or uv after starting your terminal session, open a fresh shell before running q chat again.

Workspace config isn't picked up
Confirm you're running q chat from inside the project root (or a subdirectory Q CLI still resolves back to it) — .amazonq/mcp.json is resolved relative to your working directory, not a fixed path.

Remote server stuck on "not yet loaded"
This usually means the OAuth flow didn't complete. Run /mcp again inside the session to restart authentication, and check that the browser window actually reached the provider's login page rather than erroring on a redirect.

Tool calls silently do nothing
Check /tools trust — a connected server's tools can still be untrusted, in which case Q CLI will prompt for confirmation on every call rather than running silently. If you don't see a prompt and nothing happens, the tool call may be failing server-side; check q mcp status --name <server> for connection health.

Frequently Asked Questions

Q: Does Amazon Q Developer CLI support MCP servers outside of chat — like inline code completion?
A: No. As of this writing, MCP servers in Q CLI only work inside the q chat interface, not in command completion or the q translate feature. If you need MCP context available during inline suggestions, that's not currently how Q CLI's MCP integration is scoped.

Q: Can I use the same mcp.json I already built for another CLI tool, like Claude Code or Gemini CLI?
A: Not directly — the top-level mcpServers object and the command/args/env shape for local servers are similar across most MCP clients, so a simple stdio server config often needs only minor edits. But client-specific fields (Q CLI's remote type/url shape, trust settings, timeouts) don't carry over, and some clients use an entirely different file format — Codex CLI uses TOML, not JSON, for example.

Q: What happens if the same server name is defined in both the global and workspace mcp.json?
A: The workspace-level definition takes precedence for that server inside that project, which lets a repo override a general-purpose global server with project-specific connection details without touching your global config.

Q: Is there an official list of AWS-maintained MCP servers to pair with Q Developer CLI?
A: Yes — AWS publishes a set of reference servers under the awslabs.* namespace (covering services like CDK, and various AWS APIs), distributed as Python packages run via uvx rather than npm packages. Check AWS's own MCP documentation for the current list, since AWS has been adding to it.

Q: My server worked yesterday and fails to load today with no config changes — why?
A: For local servers, check whether the underlying package was updated and introduced a breaking change (pin a version in args instead of using @latest if this keeps happening). For remote servers, an expired OAuth token is a common cause — re-run /mcp to re-authenticate.

Related Guides