ScreenshotNeo
Sign in Get a free key

BlogAI agents

How to Connect an AWS MCP Server to Amazon Q

Connect Amazon Q to local STDIO or remote HTTP MCP servers, authenticate safely, verify tools, and fix common setup errors.

By the ScreenshotNeo team1 October 20265 min read

Direct answer: Amazon Q Developer connects to an AWS MCP server through either a local STDIO process or a remote HTTP endpoint. Install Q and the server runtime, configure the server with qchat mcp add or the Q IDE tools panel, authenticate it, then verify with /tools or qchat mcp status.

The Model Context Protocol (MCP) standardizes communication between AI assistants and external tools. Amazon Q acts as the MCP host and discovers a server’s tools, prompts, and resources.

Prerequisites

  • Install Amazon Q Developer CLI, or the Q Developer extension for VS Code, JetBrains, Visual Studio, or Eclipse, and sign in.
  • Install the MCP server’s runtime and package. AWS’s documentation example uses Python 3.10+, uv, and uvx.
  • Configure AWS credentials, region, and profile. Grant only the IAM actions required by the server.
  • Choose STDIO for a local process or HTTP for a hosted service.

Choose STDIO or HTTP

Decision STDIO HTTP
Where it runs Q starts a local child process Q calls a network endpoint
Authentication Local environment, AWS profile, or injected variables OAuth or documented headers
Operations Depends on local executable and package cache Requires DNS, TLS, firewall, endpoint health, and timeout management
Best fit Individual developer or workstation Shared or centrally hosted service

Connect a local AWS MCP server over STDIO

Install and test the server

python --version
uv --version
uvx awslabs.aws-documentation-mcp-server@latest

Test the command outside Q first. Use the package name and executable required by your server if they differ.

Add the server in Q CLI

qchat mcp add
qchat mcp list
qchat mcp status

Select stdio, set the executable to uvx, and add the package as an argument. A representative configuration is:

{
  "mcpServers": {
    "aws-docs": {
      "type": "stdio",
      "command": "uvx",
      "args": ["awslabs.aws-documentation-mcp-server@latest"],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR",
        "AWS_DOCUMENTATION_PARTITION": "aws"
      },
      "timeout": 60
    }
  }
}

Environment variables are passed to the child process. Keep secrets out of committed files.

Configure AWS credentials

export AWS_PROFILE=developer
export AWS_REGION=us-east-1
qchat

An AWS MCP server receives the credentials available to its process, but each API call still requires the corresponding IAM permissions. For example, an Amazon Connect observability server may require Amazon Connect, CloudWatch, and CloudTrail permissions. Grant only the actions its tools need.

Connect a remote MCP server over HTTP

Configure the HTTPS endpoint with this structure:

{
  "mcpServers": {
    "find-a-domain": {
      "type": "http",
      "url": "https://api.findadomain.dev/mcp"
    }
  }
}

Use qchat mcp add, choose http, enter the endpoint, and provide headers only when the service documents them. Use HTTPS and a timeout longer than the server’s slowest legitimate operation.

OAuth authentication

If the endpoint requires OAuth, Q may initially mark it as not loaded. Run /mcp, open the supplied browser URL, complete authorization, and return to Q. The IDE opens the authorization page automatically. Repeat the flow when the authorization grant expires.

Configure MCP in an Amazon Q IDE

  1. Open the Amazon Q panel, open Chat, and select the tools icon.
  2. Choose global scope for ~/.aws/amazonq/default.json or workspace scope for .amazonq/default.json.
  3. Select stdio or http.
  4. For STDIO, enter command, arguments, environment variables, and timeout. For HTTP, enter endpoint, optional headers, and timeout.
  5. Save and inspect the MCP tools panel.

AWS’s Documentation MCP example uses uvx, awslabs.aws-documentation-mcp-server@latest, FASTMCP_LOG_LEVEL=ERROR, AWS_DOCUMENTATION_PARTITION=aws, and a 60-second example timeout. Legacy ~/.aws/amazonq/mcp.json and .amazonq/mcp.json files may work when legacy support is enabled.

Verify that Q can see the tools

CLI

qchat mcp list
qchat mcp status
qchat

Inside a Q session, run:

/tools

Confirm the server and expected tool names appear after loading finishes. Call a harmless read-only tool, then set permissions deliberately: Ask, Always allow, or Deny. Keep write-capable tools at Ask or Deny until reviewed.

IDE

Open the tools icon in Chat. Connection alerts identify failures; choose Fix Configuration to reopen setup. Reload the window or restart Q after changing credentials or configuration.

Common errors and fixes

Symptom Cause Fix
Server is missing Wrong scope or malformed JSON Check the global/workspace path, validate JSON, and run qchat mcp list.
command not found Runtime is not on Q’s PATH Install it, test it in the same shell, or use an absolute path.
Package/import failure Wrong package or incompatible runtime Use the server’s documented package and runtime; test outside Q.
HTTP server not loaded DNS, TLS, firewall, proxy, or outage Open the URL from the same machine and check network and certificates.
OAuth loop Expired grant or blocked browser Run /mcp and complete authorization again.
Tool calls fail Wrong profile, region, credentials, or IAM permissions Verify environment and grant the minimum documented actions.
Tools vanish after updates Q or package changed Inspect status, pin a known package version where supported, and restart Q.
Policy blocks setup Organization disabled or restricted MCP Ask the Q administrator to review the policy.

Reliability, performance, and security

  • Startup: STDIO pays process startup time once per Q session. Keep packages cached and logs quiet.
  • Latency: HTTP adds network and TLS latency. Set a bounded timeout and fix endpoint slowness rather than using an unlimited timeout.
  • Availability: Local servers depend on the workstation and credentials; remote servers depend on endpoint health, DNS, network policy, and OAuth validity.
  • Least privilege: Separate read and write tools where possible. Review schemas before choosing Always allow.
  • Secrets: Prefer the AWS credential chain or an approved secret store. Do not commit tokens or private headers.
  • Governance: AWS administrative controls announced on August 28, 2025 can enable, disable, or restrict MCP servers for Q clients.

Or skip the browser setup

If you need website images in an agent workflow, ScreenshotNeo provides an MCP server with take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and any MCP client. Its direct API call is:

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 options. Cookie and consent banners, newsletter popups, and chat widgets are removed before capture. Bot checks, blank pages, failed loads, timeouts, and cache hits are never billed, and responses identify the result with X-Page-Verdict and X-Billed. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

FAQ

Where does Amazon Q store MCP configuration?

Global IDE configuration is ~/.aws/amazonq/default.json; workspace configuration is .amazonq/default.json. Legacy mcp.json paths may work when enabled.

Can one session use STDIO and HTTP?

Yes. Add each server with its own transport and credentials, then verify both in /tools or the IDE tools panel.

Does an AWS MCP server automatically get all my AWS permissions?

It receives the credentials available to its process, but IAM still authorizes every service operation. Use the correct profile, region, and least-privilege policy.

What if my company forbids MCP?

Amazon Q administrators can centrally control MCP functionality and installed servers. Local JSON cannot override an organizational restriction.

Keep reading