Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Amazon Q Developer can connect to remote MCP servers over HTTP and run local MCP servers over STDIO. In the IDE, add a server from the Chat tools menu, choose whether its configuration is global or workspace-local, enter the transport settings, save, and review the server’s tool permissions. The Q CLI also supports adding and managing MCP servers.
Choose HTTP or STDIO first
The transport determines how Amazon Q reaches the server. Use HTTP for a remote MCP service with an endpoint URL; use STDIO when Q should start a local process by running a command. The right choice depends on where the server runs, how it authenticates, and who operates it.
| Consideration | HTTP | STDIO |
|---|---|---|
| Server location | A remote service reached at an endpoint URL. | A process launched on the local machine. |
| Configuration | Endpoint URL and, if needed, HTTP headers and timeout. | Command, arguments, environment variables, and timeout. |
| Authentication | May use headers or browser-based authorization for a protected endpoint. | Depends on the local process and its environment. |
| Operational responsibility | The service operator maintains the remote endpoint and its availability. | The local setup must be able to run the configured command. |
| Typical diagnosis | Check endpoint reachability, authorization, and headers. | Check that the command and arguments work in the local environment. |
HTTP avoids installing and launching a server process locally, but it depends on network access and the remote service. STDIO keeps the process local, but Q must be able to start it with the command and environment you configure.
Add an HTTP MCP server in the IDE
- Open the Q Developer panel in your IDE, then open Chat.
- Select the tools icon to open MCP configuration.
- Select +, then choose global or local scope.
- Enter a server name and select
httpas the transport. - Enter the MCP endpoint URL. Add optional HTTP header key-value pairs or a timeout if the server requires them.
- Select Save.
- Review the permissions for each exposed tool and select Ask, Always allow, or Deny as appropriate.
For an endpoint that requires authorization, Amazon Q automatically opens a browser page so you can authorize access. Complete that authorization before concluding the server is unavailable; the connection may not be ready until the browser flow succeeds.
#1 Best Overall
Global or local configuration?
Choose global when you want the server configuration available across projects for your user account. Choose local when it should apply to the current workspace instead. Global IDE settings are stored in ~/.aws/amazonq/default.json; local settings are stored in .amazonq/default.json. Legacy ~/.aws/amazonq/mcp.json and .amazonq/mcp.json files are also supported. Workspace configuration takes precedence when both apply.
Add a local STDIO server in the IDE
- Open the Q Developer panel, choose Chat, and select the tools icon.
- Select + and choose the desired scope.
- Enter a server name, then select
stdio. - Enter the command that starts the server, along with its command arguments.
- Add any required environment variables and set a timeout if appropriate.
- Select Save, then review the permission choice for every exposed tool.
AWS documents an example using uvx as the command and awslabs.aws-documentation-mcp-server@latest as its argument. The example sets FASTMCP_LOG_LEVEL=ERROR and AWS_DOCUMENTATION_PARTITION=aws, with a 60-second timeout. uvx is an alias for uv tool run, which creates an ephemeral Python environment. Use this as a configuration example, not as a requirement for every STDIO server; other servers can require different commands, arguments, or environment values.
Configure an MCP server from the Q CLI
The CLI provides qchat mcp add to add or replace a server configuration, qchat mcp remove to remove one, qchat mcp list to list configurations, qchat mcp import to import configuration, qchat mcp status to inspect status, and qchat mcp help for command help.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchFor a remote HTTP server, add an entry to the agent configuration using the server name, type, and endpoint URL:
{
"mcpServers": {
"my-server": {
"type": "http",
"url": "https://example.com/mcp"
}
}
}Replace https://example.com/mcp with the actual MCP endpoint. The CLI supports both remote HTTP servers and local process servers. The example above shows the remote form; use the CLI’s own help for the precise local-process options applicable to your installed version rather than guessing a configuration shape.
Complete OAuth for a remote CLI server
- Start a CLI session with the agent configured to use the protected remote server.
- Run
/mcpin the session. - Open the URL Amazon Q provides and complete authentication in the browser.
- Return to the CLI session; the server’s tools become available after authentication succeeds.
Set tool permissions deliberately
Saving a server configuration is not the last decision: Amazon Q asks you to review permissions for its exposed tools. An MCP tool is an executable function with a unique name, a human-readable description, a JSON Schema input schema, and optional annotations. A server may also expose prompts and resources, such as files, database records, API responses, documentation, or configuration data.
| Permission | Practical effect | When it fits |
|---|---|---|
| Ask | Q asks before using the tool. | Use when you want to review calls individually, especially while learning what a server can do. |
| Always allow | Q can use the tool without asking each time. | Use only when the tool’s actions and inputs are sufficiently understood for the work you plan to do. |
| Deny | Q cannot use the tool. | Use when you do not want that capability available to the assistant. |
Read each tool’s description and consider what the operation can change or expose. A natural-language request can cause Q to invoke tools, and direct tool invocation is also possible. Permission choices therefore matter even when you did not manually select a tool in the moment.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesVerify that the server is ready
MCP servers load in the background. In a Q session, use /tools to see servers that are still loading and tools that are available. If initialization is taking longer than expected, adjust the wait in milliseconds with q settings mcp.initTimeout [value], replacing [value] with the desired value.
Rank #3
In the IDE, a connection failure appears as an alert. Choose Fix Configuration, correct the settings, and retry. Check the transport-specific fields first: the HTTP URL, headers, and authorization for a remote server; or the command, arguments, and environment for a local process.
Troubleshoot common connection and loading problems
- The server does not appear ready: It may still be loading in the background. Run
/toolsto check its status and available tools; if needed, change the initialization wait withq settings mcp.initTimeout [value]. - An HTTP server fails to connect: Recheck the endpoint URL and any required headers. For an authorization-protected endpoint, finish the browser authorization that Q opens. In the IDE, use Fix Configuration from the failure alert and retry.
- A STDIO server fails to start: Verify that the configured command is runnable in the local environment and that its arguments and environment variables match what the server expects. A valid HTTP URL is not a substitute for the command required by STDIO.
- The server connects but a tool cannot be used: Review the permissions assigned to that tool. A Deny permission prevents its use; Ask may require you to approve a request.
- The wrong configuration seems to apply: Check whether a workspace configuration is overriding the global one. Workspace configuration takes precedence, and IDE settings use different paths for global and local scope.
- CLI OAuth tools remain unavailable: In the configured agent session, run
/mcp, complete authentication at the provided browser URL, then return to the CLI and check whether the tools have become available.
Organization controls and their limits
Pro-tier customers using IAM Identity Center can turn MCP off or provide an HTTPS MCP registry allow-list through the Q Developer profile. The registry file must be served over HTTPS with a trusted certificate. Q fetches it at startup and every 24 hours. Registry parameters are read-only to users, although users can choose global or workspace scope, change timeouts, and add environment variables or headers.
AWS cautions: “Both the toggle and the registry settings are enforced on the client side. Be aware that your end users could circumvent it.” Treat these settings as client-side controls, not as a guarantee that users cannot bypass restrictions. The cited governance availability is limited to the stated Pro-tier and IAM Identity Center context.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Or skip the browser setup
If your goal is to capture a webpage rather than connect Q to an MCP server, ScreenshotNeo is a separate website screenshot API and MCP server for developers. It does not replace Amazon Q’s MCP configuration. Its one-call HTTP endpoint can return a screenshot or PDF; see the ScreenshotNeo API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, with response headers indicating the page verdict and billing status. An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan: 1,000 screenshots a month, no card required.
Frequently Asked Questions
Can Amazon Q use an MCP server that runs on another machine?
Yes, if it is exposed as a reachable remote HTTP MCP endpoint. A local STDIO configuration instead launches a process on the machine running Q.
Does Amazon Q automatically trust every tool from a server I add?
No. After saving, review the permissions for each exposed tool and choose Ask, Always allow, or Deny.
Can my organization force an MCP allow-list that users cannot bypass?
The described Q Developer profile controls are enforced client-side; AWS explicitly warns users could circumvent them.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
