Amazon Q Developer MCP: Setup, Servers, Permissions, and Governance

Amazon Q Developer supports the Model Context Protocol (MCP), an open standard that lets an AI assistant discover and invoke tools exposed by external servers. You can connect local process servers or remote HTTP servers, then control each tool with approval settings.

The practical choices are:

Amazon Q Developer CLI: local MCP processes and remote HTTP servers.
Amazon Q Developer IDE plugins: STDIO and HTTP server setup from the Q panel.
Scope: global configuration for all projects or workspace configuration for one repository.
Permissions: ask, always allow, or deny in the IDE; the CLI also classifies tools by approval and risk.

Available actions depend entirely on the server and permissions you configure. Review every tool before allowing it to run.

How MCP works in Amazon Q Developer

Amazon Q is the host. Its MCP client maintains a connection to an MCP server. The server publishes tools with names, descriptions, input schemas, and optional annotations. A tool can process data, call an API, execute a command, or perform another action exposed by that server. Servers can also publish prompts and resources.

This architecture means MCP is an integration mechanism, not a fixed set of built-in capabilities. Adding a server changes what Q can discover and invoke. A server that appears read-only may still expose other tools, so inspect its declarations and permission prompts.

See the Amazon Q Developer MCP documentation for the current protocol and client behavior.

Choose a transport and configuration scope

Decision	Use this when	Trade-off
Local process (STDIO)	The server package runs on your machine	Simple local access; requires a runtime, command, and environment
Remote HTTP	A service is hosted elsewhere	Easier central hosting; configure URL, headers, timeout, and possibly OAuth
Global configuration	You want the server in every project	Convenient, but broadens access across repositories
Workspace configuration	Only one repository needs the server	More isolated; each workspace needs its own configuration

For the IDE, workspace configuration takes precedence over global configuration. AWS documents ~/.aws/amazonq/default.json as the global file and .amazonq/default.json as the workspace file. Legacy global and workspace mcp.json files remain supported when the global useLegacyMcpJson setting is enabled; the IDE guide says that setting is enabled by default.

Configure MCP in Amazon Q Developer CLI

1. Prepare the server

For a local server, install its required runtime and package, then identify the command, arguments, and environment variables it needs. For a remote server, obtain its HTTPS URL and authentication details. Remote servers may be open or use OAuth.

2. Add it to the CLI agent configuration

The CLI stores custom-agent configuration under ~/.aws/amazonq/cli-agents. Use the current AWS custom-agent and remote-server guides for the exact schema because fields can change between releases. Keep secrets in environment variables or the CLI’s supported secret mechanism rather than committing them to a repository.

3. Confirm initialization

Servers initialize in the background. Run /tools in the Q CLI to see connected servers, available tools, and tools that are still loading.

If a large server needs more time, change the initialization timeout in milliseconds:

q settings mcp.initTimeout <milliseconds>

Use a value appropriate for the server’s startup work and network conditions, then restart or reconnect as required by your CLI version.

4. Review tool approval and risk

The CLI can classify tools as auto-approved, approval-required, or dangerous. Treat command execution, file mutation, credential use, and external writes as high-risk until you have read the tool description and input schema.

Configure MCP in the Amazon Q Developer IDE plugin

AWS documents MCP support in the Visual Studio Code and JetBrains IDE plugins. Open the Q Developer panel, open Chat, and select the tools icon to manage servers.

HTTP server

Choose the configuration scope.
Enter a server name and HTTP URL.
Add request headers if the endpoint requires them.
Set a connection timeout appropriate for the service.
If authorization is required, complete the browser-based OAuth flow that Q opens.
Save the server and watch the panel for the connection result.

STDIO server

Choose the scope and create a server entry.
Enter the executable command.
Add command-line arguments.
Add required environment variables.
Save and wait for Q to connect.

AWS’s example uses uvx with the AWS Documentation MCP Server package identifier. Copy the package identifier and arguments from the current IDE guide rather than relying on an old example.

Set permissions for every MCP tool

The IDE offers three choices per tool:

Choice	Behavior	Recommended use
Ask	Prompts before each invocation	New or unfamiliar servers
Always allow	Runs without an approval prompt	Well-understood, low-risk tools
Deny	Prevents invocation	Tools outside the project’s purpose

Read the human-readable description, input schema, and annotations before changing a tool from Ask to Always allow. Approval controls reduce accidental actions but do not make an untrusted server safe.

Organization governance with an allow-list

For Amazon Q Developer Pro customers using IAM Identity Center, administrators can disable MCP or specify an allow-list registry served over HTTPS. The registry endpoint needs a certificate from a trusted certificate authority; self-signed certificates are not supported.

Q fetches the registry at startup and every 24 hours. During synchronization it can stop a locally installed server removed from the registry and relaunch a server to match the registry version.

AWS explicitly warns that the MCP toggle and registry settings are enforced client-side and that end users could circumvent them. Treat the registry as a configuration control, not a tamper-proof security boundary. Pair it with operating-system permissions, network controls, repository policy, and normal identity and secret-management practices.

Example: Amazon Business Integrations MCP Server

Amazon Business describes its MCP server as a preview for testing and evaluation. It can search Amazon Business API documentation with natural-language queries and read documentation by reference, returning API details, sample code, and troubleshooting information. Amazon Q Developer is listed as a compatible agent.

Prerequisites include an MCP-capable IDE or agent, Node.js, npm, and an account ID in the Solution Provider Portal. Documentation-only use requires the initial onboarding step. Generating code that supports production API calls requires additional onboarding plus access and refresh tokens. Follow the Amazon Business documentation for the current package and onboarding sequence.

Connect an MCP server safely: a checklist

Confirm the server publisher and inspect its source or package provenance.
List every tool, prompt, and resource it exposes.
Identify tools that execute commands, write files, send requests, or handle credentials.
Start with Ask permissions and a test workspace.
Use workspace scope unless the server is needed everywhere.
Keep tokens in environment variables or an approved secret store.
Set an explicit HTTP timeout and verify TLS certificates.
Record the server version and configuration so teammates can reproduce it.
For organizations, maintain an allow-list and separately enforce endpoint and identity controls.

Troubleshooting

The server does not appear in `/tools`

It may still be initializing, the command may be missing, or the configuration schema may be invalid. Wait for background initialization, confirm the executable is on PATH, validate arguments and environment variables, then increase mcp.initTimeout if startup is slow.

The IDE reports a connection error

Open the Q panel’s connection alert and check the URL, TLS certificate, timeout, request headers, and OAuth session. For STDIO, run the command manually with the same arguments and environment to expose missing runtimes or packages.

A tool is visible but Q will not run it

Check its permission state. Change Deny to Ask only after reviewing the tool. If the tool is approval-required or dangerous in the CLI, approve the invocation explicitly.

OAuth keeps opening or fails

Complete the browser flow with the intended account, verify the remote server’s redirect and scope configuration, and remove stale credentials before retrying. Do not paste access tokens into repository files or chat prompts.

Tools work globally but not in a repository

The workspace file may override the global file. Inspect .amazonq/default.json and remove or correct the overriding entry.

An administrator’s registry does not seem enforced

AWS documents client-side enforcement and warns that users could circumvent it. Verify the registry certificate, endpoint availability, 24-hour refresh timing, and local client configuration, then add server-side controls for actions that must be restricted.

Performance, reliability, and cost considerations

MCP startup adds a connection and tool-discovery phase. Local STDIO avoids a network hop but depends on process startup and package availability. Remote HTTP centralizes hosting but adds DNS, TLS, authentication, and network latency. Keep tool schemas focused, avoid loading unnecessary servers in every workspace, and set timeouts that match the slowest expected operation.

Background initialization lets you begin chatting while tools load, but a tool cannot be used until its server is ready. For reliability, pin compatible package versions where possible, monitor remote endpoint availability, and provide a fallback workflow when a server is offline.

Amazon Q MCP itself does not define a single service price for third-party servers. Account for the server’s hosting, API, identity, and data-transfer costs separately, along with any Amazon Q Developer subscription or organizational charges.

Or skip the browser setup

If your goal is reliable website screenshots for an agent or development workflow, ScreenshotNeo provides an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. It also has a direct API, so you can use it from an Amazon Q workflow without managing a browser locally.

Cookie and consent banners, newsletter popups, and chat widgets are removed before capture. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing result.

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}`);

See the ScreenshotNeo API documentation for the 63 capture options, authentication, PDFs, CSS and JavaScript, device presets, caching, async jobs, bulk capture, signed links, and usage reporting. One thousand screenshots per month are free with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.

FAQ

Does Amazon Q Developer support remote MCP servers?

Yes. AWS documents remote servers that communicate over HTTP in the CLI and HTTP setup in the IDE.

Can one MCP server expose more than tools?

Yes. MCP servers may also expose predefined prompts and resources.

Should I use global or workspace configuration?

Use workspace scope when only one repository needs the server. The IDE gives workspace configuration precedence over global configuration.

Is the administrator registry a complete security boundary?

No. AWS says the toggle and registry settings are enforced client-side and could be circumvented by end users.

Is the Amazon Business MCP server production-ready?

Its documentation labels it a preview intended for testing and evaluation. Production API code generation also requires additional onboarding and tokens.