MCP configuration - Amazon Q Developer
Understanding MCP configuration

MCP configuration

MCP configuration in Amazon Q Developer CLI is managed through JSON files. This section covers how to configure MCP servers to extend Q's capabilities.

Understanding MCP configuration

MCP client configuration in Amazon Q Developer CLI is stored in JSON format, in a file named mcp.json. This section explains how MCP configuration works and how to structure your configuration files.

Configuration file locations

Amazon Q Developer CLI supports two levels of MCP configuration:

  1. Global Configuration: ~/.aws/amazonq/mcp.json - Applies to all workspaces

  2. Workspace Configuration: .amazonq/mcp.json - Specific to the current workspace

Both files are optional; neither, one, or both can exist. If both files exist, Amazon Q Developer CLI reads MCP configuration from both and combines them, taking the union of their contents. If there is a conflict (i.e., a server defined in the global config is also present in the workspace config), a warning is displayed and only the server entry in the workspace config is used.

Configuration file structure

The MCP configuration file uses a JSON format with the following structure:

{
  "mcpServers": {
    "server-name": {
      "command": "command-to-run",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR1": "value1",
        "ENV_VAR2": "value2"
      },
      "timeout": 60000
    }
  }
}

Each MCP server entry is an object, with the server name as the key. The name must be unique within each MCP config file and across global and project config files. The server name must not be empty and must not be longer than 250 characters.

Each MCP server entry object must have either the "command" property (for stdio transport) or the "url" property (for HTTP transport, which will be supported in a future release).

If there are any unexpected attributes in the JSON file, a warning is displayed and those attributes are ignored.

Stdio server configuration

If the "command" property is present in an entry, this MCP server uses stdio transport. The following attributes are supported:

  • command (required): The shell command to use to launch the MCP server. This is a string that represents a valid shell command.

  • args (optional): An array of command-line arguments to pass to the server when it is launched. The arguments are passed in the exact order they are defined in the config file. If not defined, no arguments are passed to the server.

  • env (optional): An object containing environment variables to set when launching the server. Each value must be a string. If not defined, no environment variables are set.

  • timeout (optional): The maximum time in milliseconds that the client will wait for a response from the MCP server for a tool call, prompt retrieval, or resource retrieval. This must be a positive integer value. If not defined, a default value of 60,000 ms (1 minute) is used.

Example of a stdio server configuration:

{
  "mcpServers": {
    "stdio-mcp-server": {
      "command": "mycommand",
      "args": [
        "arg1"
      ],
      "env": {
        "API_KEY": "value1"
      },
      "timeout": 60000
    }
  }
}

Configuration examples

Basic example with a single MCP server:

{
  "mcpServers": {
    "markdown-tools": {
      "command": "npx",
      "args": [
        "-y",
        "@example/markdown-mcp"
      ]
    }
  }
}

Example with multiple MCP servers and environment variables:

{
  "mcpServers": {
    "git-tools": {
      "command": "npx",
      "args": [
        "-y",
        "@example/git-mcp"
      ],
      "timeout": 30000
    },
    "api-tools": {
      "command": "npx",
      "args": [
        "-y",
        "@example/api-mcp"
      ],
      "env": {
        "API_URL": "https://api.example.com",
        "API_KEY": "your-api-key"
      },
      "timeout": 120000
    }
  }
}

Configuration best practices

  • Use descriptive names for your MCP servers to make them easily identifiable.

  • Use the global configuration file for MCP servers that you want to use across all projects.

  • Use workspace-specific configuration files for MCP servers that are only relevant to a particular project.

  • Adjust timeout values based on the expected response time of each MCP server.

  • Regularly check for updates to your MCP servers to ensure you have the latest features and security fixes.

Configuration commands

Usage: 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)