AWS amazonq documentation change
Summary
Restructured MCP configuration documentation with added details about file precedence, timeout settings, environment variable substitution, and security best practices
Security assessment
The changes add security-adjacent documentation by recommending storing sensitive information in environment variables rather than hardcoding, and advising regular updates for security fixes. However, there is no evidence of addressing a specific existing vulnerability or security incident.
Diff
diff --git a/amazonq/latest/qdeveloper-ug/command-line-mcp-configuration.md b/amazonq/latest/qdeveloper-ug/command-line-mcp-configuration.md index 572d09974..dbf142b1c 100644 --- a//amazonq/latest/qdeveloper-ug/command-line-mcp-configuration.md +++ b//amazonq/latest/qdeveloper-ug/command-line-mcp-configuration.md @@ -5 +5 @@ -Configuration filesConfiguration formatExample configurationsConfiguration reference +Understanding MCP configuration @@ -11 +11,5 @@ MCP configuration in Amazon Q Developer CLI is managed through JSON files. This -## Configuration files +## 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 @@ -22 +26,3 @@ Amazon Q Developer CLI supports two levels of MCP configuration: -If both files exist, their contents are combined. In case of conflicts, the workspace configuration takes precedence. +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. + +Amazon Q Developer CLI watches these configuration files and automatically reloads the MCP configuration whenever you make changes to either file. @@ -24 +30 @@ If both files exist, their contents are combined. In case of conflicts, the work -## Configuration format +### Configuration file structure @@ -36,0 +43,2 @@ The MCP configuration file uses a JSON format with the following structure: + }, + "timeout": 60000 @@ -40 +47,0 @@ The MCP configuration file uses a JSON format with the following structure: - } @@ -42 +49,5 @@ The MCP configuration file uses a JSON format with the following structure: -Configuration fields: +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. @@ -44 +55 @@ Configuration fields: - * `mcpServers`: Object containing server definitions +### Stdio server configuration @@ -46 +57 @@ Configuration fields: - * `server-name`: A unique identifier for the MCP server +If the "command" property is present in an entry, this MCP server uses stdio transport. The following attributes are supported: @@ -48 +59 @@ Configuration fields: - * `command`: The command to execute to start the MCP server + * `command` (required): The shell command to use to launch the MCP server. This is a string that represents a valid shell command. @@ -50 +61 @@ Configuration fields: - * `args`: Array of command-line arguments to pass to the 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. @@ -52 +63 @@ Configuration fields: - * `env`: Environment variables to set when running 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. @@ -53,0 +65 @@ Configuration fields: + * `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. @@ -57 +68,0 @@ Configuration fields: -## Example configurations @@ -59 +70,30 @@ Configuration fields: -Basic example: +Environment variable substitution: + + * `${env:VAR_NAME}`: Substitutes the value of the environment variable VAR_NAME + + * `${file:/path/to/file}`: Substitutes the contents of the specified file + + + + +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: @@ -74 +114 @@ Basic example: -Example with environment variables: +Example with multiple MCP servers and environment variables: @@ -78,0 +119,8 @@ Example with environment variables: + "git-tools": { + "command": "npx", + "args": [ + "-y", + "@example/git-mcp" + ], + "timeout": 30000 + }, @@ -88 +136,2 @@ Example with environment variables: - } + }, + "timeout": 120000 @@ -93 +142 @@ Example with environment variables: -## Configuration reference +### Configuration best practices @@ -95 +144 @@ Example with environment variables: -The complete schema for MCP configuration files: + * Use descriptive names for your MCP servers to make them easily identifiable. @@ -96,0 +146 @@ The complete schema for MCP configuration files: + * Store sensitive information like API keys as environment variables rather than hardcoding them in the configuration file. @@ -98,12 +148,7 @@ The complete schema for MCP configuration files: - { - "mcpServers": { - "server-name": { - "command": "string", // Required: Command to execute - "args": ["string"], // Optional: Command-line arguments - "env": { // Optional: Environment variables - "ENV_VAR": "string" - } - ] - } - } - } + * 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. @@ -111 +155,0 @@ The complete schema for MCP configuration files: -Environment variable substitution: @@ -113 +156,0 @@ Environment variable substitution: - * `${env:VAR_NAME}`: Substitutes the value of the environment variable VAR_NAME @@ -115 +157,0 @@ Environment variable substitution: - * `${file:/path/to/file}`: Substitutes the contents of the specified file @@ -116,0 +159 @@ Environment variable substitution: +### Configuration commands @@ -117,0 +161 @@ Environment variable substitution: +Usage: `Usage: qchat mcp [OPTIONS] `COMMAND`` @@ -118,0 +163,8 @@ Environment variable substitution: +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)