MCP configuration in the CLI

This page covers CLI-specific options for configuring MCP servers.

Configuration commands

Usage: qchat mcp [OPTIONS] COMMAND

MCP configuration commands

Command	Description
qchat mcp add	Add or replace a configured server
qchat mcp remove	Remove a server from the MCP configuration
qchat mcp list	List configured servers
qchat mcp import	Import a server configuration from another file
qchat mcp status	Get the status of a configured server
qchat mcp help	Print this list of commands or help for the given subcommand(s)

MCP server arguments

The --args parameter now supports comma-containing arguments using escaping or JSON array format:

# Escaped commas
q mcp add --name server --command cmd --args "arg1,arg2\,with\,commas,arg3"

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

Remote MCP servers

In addition to local MCP servers that run as processes, Amazon Q Developer CLI supports remote MCP servers that communicate over HTTP. Remote servers can use OAuth authentication or be open (no authentication required).

Configuration

Remote MCP servers are configured in your agent configuration file using the type and url fields:

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

OAuth authentication flow

When using remote MCP servers that require OAuth authentication:

1. Start your Q CLI session with an agent that includes the remote MCP server

2. The server will initially show as "not yet loaded"

3. Use the /mcp command to begin authentication

4. Q CLI will indicate that the server requires authentication and provide a URL

5. Open the provided URL in your browser while keeping the Q CLI session open

6. Follow the authentication instructions in your browser

7. Return to the Q CLI window - you will be signed into the MCP server if authentication was successful

The server's tools will become available once authentication is complete.