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 supports the Model Context Protocol (MCP) in its CLI and in the Visual Studio Code and JetBrains IDE plugins. MCP lets Q act as a host for an MCP client that connects to a configured server, discovers that server’s tools, prompts and resources, and invokes only the capabilities you permit. The practical choice is between a local process (usually STDIO) and a remote HTTP endpoint, followed by careful per-tool permission review.
This guide covers the CLI and IDE setup paths, workspace versus global configuration, remote-server authentication, troubleshooting, and organization controls. Availability and interface labels can change, so use the current Amazon Q documentation when a screen differs from the descriptions below.
How MCP works in Amazon Q Developer
MCP is an open protocol for connecting an AI assistant to external capabilities. In Amazon Q’s architecture, Q is the host, an MCP client maintains the connection, and an MCP server exposes the functionality. A server can connect to local data or an external service. Each tool has a name, a human-readable description and an input schema; optional annotations provide additional context. Servers can also expose predefined prompts and resources.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
MCP is an integration mechanism, not a catalog of built-in Amazon services. What Q can do depends on the server you install or configure and the permissions you grant. A tool may process data, call an API, execute a command or perform another action, so treat every server as code with access to the environments in which it runs.
#1 Best Overall
- Your favorite music and content – Play music, audiobooks, and podcasts from Amazon Music, Apple Music, Spotify and others or via Bluetooth throughout your home.
- Alexa is happy to help – Ask Alexa for weather updates and to set hands-free timers, get answers to your questions and even hear jokes. Need a few extra minutes in the morning? Just tap your Echo Dot to snooze your alarm.
- Keep your home comfortable – Control compatible smart home devices with your voice and routines triggered by built-in motion or indoor temperature sensors. Create routines to automatically turn on lights when you walk into a room, or start a fan if the inside temperature goes above your comfort zone.
- Do more with device pairing – Fill your home with music using compatible Echo devices in different rooms, or create a home theatre system with Fire TV.
- Say goodbye to drop-offs and buffering - With eero Built-in, Echo Dot doubles as a mesh wifi extender, adding up to 1,000 sq. ft. of wifi coverage to your existing eero network.
Choose the transport and client
| Decision | Local process / STDIO | Remote HTTP |
|---|---|---|
| Where the server runs | On your computer as a process started by Q | On a remote service reached over HTTP |
| Typical fit | Local files, development utilities and packages installed on your machine | Shared services, hosted APIs or a server managed by another team |
| Authentication | Usually local process environment and credentials | Can be open or use OAuth; the IDE also supports request headers |
| Amazon Q CLI | Supported | Supported |
| Amazon Q IDE plugins | Configured through the STDIO flow | Configured through the HTTP flow |
The CLI and IDE are separate configuration surfaces. A server configured in one is not automatically configured in the other.
Set up an MCP server in Amazon Q Developer CLI
1. Confirm the CLI and server requirements
Install the Amazon Q Developer CLI and the MCP server’s own prerequisites. For a local server, you need the command and any package or runtime it requires. For a remote server, obtain its URL and determine whether it expects OAuth or another form of authentication.
2. Add the server to the CLI agent configuration
Amazon Q stores CLI agent configuration under ~/.aws/amazonq/cli-agents. Add the server using the current custom-agent and remote-server configuration format documented by AWS. The exact keys vary with the transport, so copy the current schema rather than guessing property names.
Free tools Windows power users keep installed
One-click scans. No signup required.
For a local server, configure the executable command, arguments and required environment variables. For an HTTP server, configure the endpoint and authentication details. Remote servers may be unauthenticated or may use OAuth.
3. Start Q and inspect tool status
Servers initialize in the background. You can begin chatting while they load. Run /tools to see each server, its tools and whether initialization is still in progress. If a server remains unavailable, use the status information to distinguish a startup problem from a permission decision.
4. Adjust initialization time when necessary
Slow packages or cold remote services may need more time to initialize. Set the CLI option with:
Rank #2
- Your favorite music and content – Play music, audiobooks, and podcasts from Amazon Music, Apple Music, Spotify and others or via Bluetooth throughout your home.
- Alexa is happy to help – Ask Alexa for weather updates and to set hands-free timers, get answers to your questions and even hear jokes. Need a few extra minutes in the morning? Just tap your Echo Dot to snooze your alarm.
- Keep your home comfortable – Control compatible smart home devices with your voice and routines triggered by built-in motion or indoor temperature sensors. Create routines to automatically turn on lights when you walk into a room, or start a fan if the inside temperature goes above your comfort zone.
- Do more with device pairing – Fill your home with music using compatible Echo devices in different rooms, or create a home theatre system with Fire TV.
- Say goodbye to drop-offs and buffering - With eero Built-in, Echo Dot doubles as a mesh wifi extender, adding up to 1,000 sq. ft. of wifi coverage to your existing eero network.
q settings mcp.initTimeout [value]Use a value in milliseconds appropriate for your environment. Increase it only when startup is otherwise healthy; a longer timeout does not fix an invalid command, unreachable URL or failed authentication.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →5. Review tool approval and risk
CLI documentation classifies tools as auto-approved, approval-required or dangerous. Read the server’s tool descriptions and approve only actions suitable for the current project. Do not assume a tool is read-only because its name sounds informational.
Set up MCP in the Amazon Q IDE plugins
AWS’s June 13, 2025 announcement stated that MCP support was available in the Visual Studio Code and JetBrains IDE plugins and the Amazon Q Developer CLI. The live interface can change, so use the current plugin documentation if labels differ.
Configuration files and scope
The IDE supports a global file at ~/.aws/amazonq/default.json and a workspace file at .amazonq/default.json. Workspace configuration takes precedence over global configuration. This lets you keep personal defaults while giving a repository its own server set.
Legacy global and workspace mcp.json files are also supported when the global useLegacyMcpJson setting is enabled; the guide says that setting is enabled by default. Prefer the current default.json format for new configuration unless you have a reason to retain a legacy file.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsAdd a server from the Q panel
- Open the Amazon Q Developer panel and its Chat panel.
- Select the tools icon to open MCP tool management.
- Choose the scope (global or workspace), then choose the transport.
- For HTTP, enter a server name and URL. Add request headers and a timeout when the service requires them. If authorization is needed, Q opens a browser-based flow.
- For STDIO, enter the command, arguments and any environment variables required by the server.
- Save the entry and wait for Q to connect. Connection problems are reported in the panel.
Example: STDIO server fields
AWS’s example uses uvx with the AWS Documentation MCP Server package identifier. The important pattern is command, arguments and environment variables; use the package identifier and options from that server’s current documentation rather than copying an outdated value.
Rank #3
- MEET ECHO SPOT - A sleek smart alarm clock with Alexa and big vibrant sound. Ready to help you wake up, wind down, and so much more.
- CUSTOMIZABLE SMART CLOCK - See time, weather, and song titles at a glance, control smart home devices, and more. Personalize your display with your favorite clock face and fun colors.
- BIG VIBRANT SOUND - Enjoy rich sound with clear vocals and deep bass. Just ask Alexa to play music, podcasts, and audiobooks. See song titles and touch to control your music.
- EASE INTO THE DAY - Set up an Alexa routine that gently wakes you with music and gradual light. Glance at the time, check reminders, or ask Alexa for weather updates.
- KEEP YOUR HOME COMFORTABLE - Control compatible smart home devices. Just ask Alexa to turn on lights or touch the screen to dim. Create routines that use motion detection to turn down the thermostat as you head out or open the blinds when you walk into a room.
Set permissions for every tool
The IDE presents three choices per tool:
- Ask: prompt for approval on every invocation.
- Always allow: permit the tool without another prompt.
- Deny: prevent Q from using it.
Start with Ask while you learn a server. Move a narrowly scoped, understood read-only tool to Always allow only when repeated prompts impede your workflow. Keep tools that write files, call production APIs, execute commands or handle sensitive data on Ask or Deny unless your operating procedure explicitly requires otherwise.
Personal setup versus organization governance
For an individual, configuration is local: you choose the servers, transports and permissions in your CLI or IDE. Organizations can add a centrally managed layer through Amazon Q Developer profiles for Pro-tier customers using IAM Identity Center.
Registry allow-list
An administrator can turn MCP off or specify an allow-list registry served over HTTPS. The registry endpoint must have a certificate issued by 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.
Important security limitation
AWS warns that both the MCP toggle and registry settings are enforced on the client side and that end users could circumvent them. Treat the registry as a configuration and governance control, not a tamper-proof security boundary. Enforce sensitive access with the identity, network and operating-system controls appropriate to your environment.
Example: Amazon Business Integrations MCP Server
Amazon Business describes its Integrations 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 one of the compatible agents named by Amazon Business.
Prerequisites and limits
- An MCP-capable IDE or agent.
- Node.js and npm.
- An account ID in the Solution Provider Portal.
Documentation-only use requires the initial onboarding step described by Amazon Business. Generating code that supports production API calls requires additional onboarding plus access and refresh tokens. Because the service is explicitly a preview, validate its current onboarding steps and do not treat it as a production availability guarantee.
Rank #4
- Your favorite music and content – Play music, audiobooks, and podcasts from Amazon Music, Apple Music, Spotify and others or via Bluetooth throughout your home.
- Alexa is happy to help – Ask Alexa for weather updates and to set hands-free timers, get answers to your questions and even hear jokes. Need a few extra minutes in the morning? Just tap your Echo Dot to snooze your alarm.
- Keep your home comfortable – Control compatible smart home devices with your voice and routines triggered by built-in motion or indoor temperature sensors. Create routines to automatically turn on lights when you walk into a room, or start a fan if the inside temperature goes above your comfort zone.
- Do more with device pairing – Fill your home with music using compatible Echo devices in different rooms, or create a home theatre system with Fire TV.
- Say goodbye to drop-offs and buffering - With eero Built-in, Echo Dot doubles as a mesh wifi extender, adding up to 1,000 sq. ft. of wifi coverage to your existing eero network.
Troubleshoot common MCP failures
The server never appears
Check that the entry is in the client you are actually using: CLI configuration under ~/.aws/amazonq/cli-agents, or IDE configuration in default.json. In the IDE, workspace configuration overrides global settings and may hide a global server for that project.
The CLI shows “loading” indefinitely
Run /tools and inspect the server status. Verify the executable exists on PATH, arguments are valid and required environment variables are present. Increase mcp.initTimeout only after confirming the command can start independently.
The IDE reports a connection error
Reopen the tools panel and correct the URL, command, arguments, headers or timeout. For HTTP, test DNS and network reachability and complete the browser authorization flow if prompted. For STDIO, run the command manually with the same environment to expose missing runtimes or packages.
The server connects but a tool is unavailable
Inspect that tool’s permission state. A Deny decision blocks use, and Ask requires an approval at invocation time. The server may also expose tools conditionally or fail to initialize all capabilities.
A remote server works for one user but not another
Compare OAuth identity, request headers, network access and organization policy. A registry allow-list may stop an unapproved server, while a client-side policy can still be changed by an end user; investigate both the intended policy and the effective local configuration.
Or skip the browser setup
If your workflow also needs reliable website screenshots for documentation, tests or agent context, ScreenshotNeo provides a single HTTP request instead of maintaining a browser automation stack. Before capture it accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups and chat widgets; each cleanup step can be disabled. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads and cache hits cost nothing, and response headers identify the page verdict and billing result. Its MCP server exposes take_screenshot, get_page_info and capture_pdf for Claude, Cursor and other MCP clients.
Use the API documentation at https://screenshotneo.com/docs/. The following calls are runnable; replace the key and target URL.
Best Value
- Alexa can show you more - Echo Show 5 includes a 5.5” display so you can see news and weather at a glance, make video calls, view compatible cameras, stream music and shows, and more.
- Small size, bigger sound – Stream your favorite music, shows, podcasts, and more from providers like Amazon Music, Spotify, and Prime Video—now with deeper bass and clearer vocals. Includes a 5.5" display so you can view shows, song titles, and more at a glance.
- Keep your home comfortable – Control compatible smart devices like lights and thermostats, even while you're away.
- See more with the built-in camera – Check in on your family, pets, and more using the built-in camera. Drop in on your home when you're out or view the front door from your Echo Show 5 with compatible video doorbells.
- See your photos on display – When not in use, set the background to a rotating slideshow of your favorite photos. Invite family and friends to share photos to your Echo Show. Prime members also get unlimited cloud photo storage.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport 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}`);Every plan includes the capture options, and the Free plan provides 1,000 screenshots each month with no card. Paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.
Frequently Asked Questions
Can I use both local and remote MCP servers in Amazon Q?
Yes. The CLI supports local process servers and remote HTTP servers; the IDE provides separate STDIO and HTTP setup flows. Configure and permission each server independently.
Recommended Free Tools
Does workspace configuration override my global IDE servers?
Yes. The workspace file at .amazonq/default.json takes precedence over ~/.aws/amazonq/default.json.
Is the organization registry a complete security boundary?
No. AWS states that MCP toggle and registry settings are enforced client-side and could be circumvented by end users.
The Bottom Line
Use STDIO for a locally managed process and HTTP for a hosted service, then verify every tool’s permissions. Keep CLI and IDE configuration separate, prefer workspace scope when a project needs its own servers, and treat organization registries as client-side governance rather than tamper-proof enforcement.
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.
