How to Set Up an MCP Server with Amazon Q Developer

Direct answer: Add an MCP server to Amazon Q Developer from the IDE’s MCP configuration panel or with the q mcp command family in the CLI. Use STDIO when Q should launch a local process, or HTTP when the server is hosted at a URL. Then review each tool’s permission, verify that the server loads, and test a tool in a Q session.

Amazon Q Developer discovers tools exposed by MCP servers and can invoke them from its IDE integrations and CLI. The exact command, package, environment variables, headers and authentication method depend on the server you connect.

Product date: AWS currently lists 30 April 2027 as the end of support for Amazon Q Developer IDE plugins. Check the current AWS product direction before committing to a long-lived IDE workflow; AWS points readers to Kiro for similar IDE capabilities. AWS IDE documentation

Choose the connection that matches your server

Choice	Use it when	What you configure
STDIO	The MCP server runs on your machine and Q should start it.	Launch command, arguments, environment variables and timeout.
HTTP	The server is available at a remote endpoint.	Initialization URL, optional headers and timeout. The server may require OAuth.
Global scope	You want the server available across projects.	`~/.aws/amazonq/default.json` for IDE configuration.
Workspace scope	The server belongs to one repository or team workspace.	`.amazonq/default.json`; workspace settings take precedence for servers and permissions.

STDIO avoids network reachability issues but requires a working local runtime and dependencies. HTTP centralizes the server and can be shared, but requires network access and server-specific authentication. These are operational differences; the MCP provider determines the exact requirements.

Set up an MCP server in the Amazon Q Developer IDE

Open your IDE and the Amazon Q Developer panel.
Open Chat, then select the tools icon to open MCP configuration.
Select Add server.
Choose Global for all projects or Local for the current workspace.
Choose HTTP or STDIO, enter the server-specific settings, and save.
Review every discovered tool’s permission setting before asking Q to use it.

A global IDE entry is written to ~/.aws/amazonq/default.json. A local entry is written to .amazonq/default.json. AWS documents workspace-level configuration as taking precedence for servers and permissions. Read the AWS IDE MCP configuration reference.

Configure a remote HTTP server

Select HTTP.
Enter the server’s initialization URL.
Add any headers required by that server. Do not commit access tokens or other secrets to a shared workspace file.
Set the timeout required by the provider.
If the endpoint uses authorization, complete the browser authorization flow when Amazon Q opens it.
Save the server and wait for the connection status to clear any alert.

HTTP headers and OAuth behavior are server-dependent. Amazon Q’s documentation establishes that headers can be configured and that OAuth authorization can open in a browser; consult the MCP server’s own instructions for scopes and credentials. HTTP fields and authorization flow

Configure a local STDIO server

Select STDIO.
Enter the executable or launch command.
Add the arguments required by that server.
Add environment variables and set a timeout.
Save, then check that the server reports a healthy connection.

AWS shows this example for its Documentation MCP Server. It is an AWS example, not a universal recipe:

Command: uvx
Arguments: awslabs.aws-documentation-mcp-server@latest
Environment:
  FASTMCP_LOG_LEVEL=ERROR
  AWS_DOCUMENTATION_PARTITION=aws
Timeout: 60 seconds

The 60-second value above is the example shown in AWS documentation. Choose a value that fits the server’s startup and initialization time.

Set tool permissions deliberately

After saving a server, inspect each tool’s permission. The IDE offers:

Ask: Q requests approval before using the tool.
Always allow: Q can invoke the tool without asking each time.
Deny: Q cannot invoke the tool.

Use Ask while evaluating an unfamiliar server, allow only tools whose behavior you understand, and deny tools you do not need. These are the documented controls; the appropriate choice depends on your workflow and the server’s capabilities.

Set up an MCP server with the Q Developer CLI

The CLI manages servers through the q mcp command family. The available operations include add, remove, list, import, status and help. Start with help on the installed version so you use the syntax it exposes:

q mcp help
q mcp list
q mcp status

Add a local server

Use the CLI’s add command with the server type and launch details documented by that server. The exact flags can vary by Q CLI release, so confirm them with q mcp add --help:

q mcp add --help

When passing multiple arguments, AWS documents an --args option that supports escaped commas or a JSON array. Use the form accepted by your installed CLI and quote values that contain spaces, commas or shell characters.

Add a remote HTTP server

Remote servers are configured with a type and URL. For an open endpoint, provide the URL and any required options described by the CLI help and server documentation. For an OAuth-protected endpoint, authentication happens from a running agent session:

Start an agent that includes the remote MCP server.
Enter /mcp in the session.
Open the authorization URL that Q supplies in a browser while leaving the session running.
Complete authorization.
Return to the CLI and retry the tool call.

Do not assume that an IDE JSON file is the active CLI configuration. Follow the CLI guide and the configuration format for the agent you are using. AWS CLI MCP configuration

Remove or inspect a server

q mcp list
q mcp status
q mcp remove --help
q mcp import --help

Use the help output to supply the server name or identifier expected by your version. Removing a server from the CLI does not necessarily remove a separately configured IDE workspace entry.

Verify that Amazon Q loaded the tools

Amazon Q loads MCP servers in the background. In a Q session, run:

/tools

This lists the servers and tools that have loaded. If initialization is slow, inspect or change the MCP initialization timeout:

q settings mcp.initTimeout [value-in-milliseconds]

Use a value appropriate for the server’s startup time. A larger timeout gives slow servers more time to initialize; it also delays feedback when a server is unreachable. AWS MCP overview and timeout setting

Troubleshooting MCP connections

Symptom	Likely cause	Fix
Connection alert in the IDE	Invalid command, URL, arguments, headers, environment or timeout.	Select Fix Configuration, correct the entry, save it, and confirm the alert clears before relying on the tools.
Server is listed but no tools appear	Initialization has not completed or the server returned no tools.	Run `/tools`, check `q mcp status`, increase `mcp.initTimeout` when startup is legitimately slow, and read the server’s logs.
STDIO process exits immediately	Missing executable, package, argument or environment variable.	Run the launch command directly in a terminal, verify its dependencies and copy the server’s documented arguments and variables exactly.
HTTP connection times out	Network, DNS, firewall or an initialization timeout that is too short.	Open the URL from the same machine, check proxy and firewall rules, then adjust the timeout if the server starts slowly.
OAuth browser flow does not finish	The CLI session was closed, the URL expired, or authorization was denied.	Keep the agent session open, run `/mcp` again, open the new URL, and complete the provider’s requested scopes.
Tool is blocked	The tool permission is set to Deny or approval was declined.	Review the tool’s IDE permission and choose Ask or Always allow only when appropriate.
Changes seem ignored	A workspace configuration overrides the global entry, or you edited IDE settings while using the CLI.	Check both `.amazonq/default.json` and `~/.aws/amazonq/default.json`; then inspect the CLI’s own configuration and status output.

Operational guidance: security, reliability and cost

Security

Start with Ask permissions for unfamiliar tools.
Keep secrets out of committed workspace configuration and examples.
For HTTP servers, use only the headers and scopes required by the provider.
Deny tools that are outside the task’s scope.
Remember that a tool can act with the access granted to its server process or credentials.

Reliability

Prefer STDIO when local execution is required and you control the runtime.
Prefer HTTP when a centrally operated service is easier to maintain or must be shared.
Set initialization timeouts based on observed startup behavior, then verify with /tools.
Keep the server’s own logs available; Q can report a connection problem but cannot correct provider-specific failures automatically.

Cost and capacity

Amazon Q’s MCP configuration determines how tools connect; pricing, quotas and rate limits come from your Amazon Q plan and the MCP provider. Check those services’ current terms separately. The AWS documentation in this guide does not establish a universal MCP server cost or performance benchmark.

Or skip the browser setup

If your goal is reliable website screenshots for an agent, ScreenshotNeo provides a website screenshot API and MCP server. Its MCP tools include take_screenshot, get_page_info and capture_pdf, so Amazon Q or another MCP client can use those capabilities once you connect the ScreenshotNeo server according to its documentation.

The API also gives you a direct HTTP option. 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.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://stripe.com'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo removes cookie and consent banners, newsletter popups and chat widgets before capture. Bot checks, blank pages, failed loads, timeouts and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers. Its MCP server works with AI agents such as Claude, Cursor and other MCP clients. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots.

FAQ

Can one MCP server be configured globally and locally?

Yes. The IDE supports global and workspace-local configuration. Workspace configuration takes precedence for servers and permissions.

Does every MCP server use the same command?

No. The transport is standardized, but launch commands, arguments, environment variables, headers and authentication are provider-specific.

How do I know whether Q can use a tool?

Run /tools in a Q session and check the tool’s permission. A connection alert must be resolved first.

Should I use HTTP or STDIO for a team?

Use STDIO when each developer should run a local process. Use HTTP when a centrally managed endpoint is easier to operate and secure for the team.

Will an IDE MCP configuration automatically apply to the CLI?

Do not assume that it will. Follow the CLI’s configuration and agent instructions, then verify with q mcp status.