MCP server with Amazon Q Developer

Amazon Q Developer MCP configuration format

Amazon Q Developer uses a mcp.json file format similar to Claude Desktop's configuration. The file can be placed in two locations:

The mcp.json format:

{
  "mcpServers": {
    "project-tools": {
      "command": "node",
      "args": ["/path/to/mcp-server/dist/index.js"],
      "env": {
        "DATABASE_URL": "postgres://localhost:5432/dev",
        "LOG_LEVEL": "info"
      }
    },
    "remote-api-tools": {
      "command": "npx",
      "args": ["-y", "@myorg/api-mcp-server", "--url", "https://api.example.com"],
      "env": {
        "API_KEY": "${MY_API_KEY}"
      }
    },
    "http-server": {
      "url": "https://mcp.myteam.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_TOKEN}"
      }
    }
  }
}

Amazon Q's mcp.json supports both stdio (command + args) and HTTP (url) transports. Environment variable references like ${MY_API_KEY} are resolved from the process environment at the time Amazon Q reads the configuration — set these in your shell profile or use a secrets manager that exports to the environment.

Tool invocation in Q Chat

After Amazon Q connects to configured MCP servers, tools appear in Q Chat's tool panel. In VS Code, open Q Chat from the Amazon Q icon in the activity bar. In JetBrains IDEs, open the Amazon Q panel from the tool window bar (typically on the right side).

Q Chat invokes MCP tools in response to natural language prompts. When Amazon Q determines that a tool call would help answer the user's question, it shows an inline tool call proposal showing the tool name, description, and the exact arguments. The developer can:

• Allow — execute the tool call once
• Always allow in this session — auto-approve this tool for the rest of the session
• Block — prevent this specific tool call
• Always block — never invoke this tool (session-scoped)

Q Chat is particularly good at invoking MCP tools for AWS-related tasks: querying DynamoDB tables, listing S3 objects, describing EC2 instances, or fetching CloudWatch logs. If your MCP server wraps AWS APIs, Amazon Q is a natural environment for it — Q understands AWS contexts deeply and is likely to select the right tool for AWS-related developer questions.

IAM considerations for MCP tools that call AWS APIs

When an MCP server tool calls AWS APIs (S3, DynamoDB, Lambda, etc.), it runs using whatever credentials are available to the MCP server process. For stdio servers launched by Amazon Q, this is typically the developer's default AWS credentials from ~/.aws/credentials or the active SSO session. This creates a security concern: the MCP tool can call any AWS API that the developer is permitted to use — including destructive operations like deleting S3 buckets or terminating EC2 instances.

Least-privilege patterns for MCP tools calling AWS APIs:

Never configure an MCP server with AdministratorAccess IAM permissions. Even if you trust the MCP server code, prompt injection attacks (where a malicious document instructs the LLM to call destructive tools) can exploit broad permissions. The principle of least privilege is doubly important when LLMs are in the decision-making path.

// MCP server tool with explicit read-only IAM scope enforcement
import { S3Client, GetObjectCommand, ListObjectsV2Command } from '@aws-sdk/client-s3';
import { STSClient, AssumeRoleCommand } from '@aws-sdk/client-sts';

// Assume a least-privilege role at startup rather than using developer credentials
async function createScopedS3Client(): Promise<S3Client> {
  const sts = new STSClient({});
  const role = await sts.send(new AssumeRoleCommand({
    RoleArn: process.env.MCP_TOOLS_ROLE_ARN!,
    RoleSessionName: 'mcp-tools-session',
    DurationSeconds: 3600,
  }));

  return new S3Client({
    credentials: {
      accessKeyId: role.Credentials!.AccessKeyId!,
      secretAccessKey: role.Credentials!.SecretAccessKey!,
      sessionToken: role.Credentials!.SessionToken,
    },
  });
}

const s3 = await createScopedS3Client();

server.tool('list_bucket_objects', 'List objects in an S3 bucket', {
  bucket: z.string().describe('S3 bucket name'),
  prefix: z.string().optional().describe('Key prefix to filter by'),
}, async ({ bucket, prefix }) => {
  // This tool can only call ListObjectsV2 — the assumed role limits further
  const result = await s3.send(new ListObjectsV2Command({
    Bucket: bucket,
    Prefix: prefix,
    MaxKeys: 100, // Cap to prevent accidental large listings
  }));
  return {
    content: [{
      type: 'text',
      text: JSON.stringify(result.Contents?.map(o => ({ key: o.Key, size: o.Size })) ?? []),
    }],
  };
});

MCP servers vs Amazon Q agents: what's different

Amazon Q Developer has two extensibility mechanisms that are sometimes confused:

For individual developers and small teams, MCP servers are the right choice — they're self-contained, version-controlled alongside project code, and don't require AWS console access to configure. Amazon Q customizations (the managed agents) are the right choice for organization-wide deployment where IT manages the tools and developers consume them without configuration.

Debugging MCP connections in Amazon Q

Amazon Q Developer logs MCP connection activity to the VS Code Output panel. Open it with View → Output and select Amazon Q or AWS Toolkit from the dropdown. Look for lines tagged [MCP]:

[INFO] [MCP] Connecting to server "project-tools" via stdio
[DEBUG] [MCP] → {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","clientInfo":{"name":"Amazon Q","version":"2.16.0"}}}
[DEBUG] [MCP] ← {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","serverInfo":{"name":"project-tools","version":"1.0.0"},"capabilities":{"tools":{}}}}
[DEBUG] [MCP] → {"jsonrpc":"2.0","id":2,"method":"tools/list"}
[INFO] [MCP] Server "project-tools": registered 3 tool(s): list_tables, query_table, describe_table
[WARN] [MCP] Server "http-server": connection failed — ECONNREFUSED http://localhost:4000/mcp

For stdio servers, Amazon Q may not forward stderr output to the Output panel by default. Add an explicit stderr redirect in your stdio MCP server wrapper to capture startup errors:

#!/bin/bash
# mcp-server-wrapper.sh
exec node /path/to/server/dist/index.js 2>>>/tmp/mcp-server-stderr.log

Then tail /tmp/mcp-server-stderr.log to see startup errors that Amazon Q's Output panel doesn't show.

Monitoring MCP servers used by Amazon Q Developer teams

For team deployments where .amazonq/mcp.json is committed to the repository, every developer who clones the repo depends on your MCP server being available. When the server goes down, Amazon Q silently stops offering those tools — developers notice only when a tool call returns an error or tools disappear from the Q Chat panel.

The monitoring challenge is compounded by AWS context: if your MCP server calls AWS APIs, it can fail in ways that are invisible to standard HTTP health checks — IAM credentials expire, STS assume-role calls are throttled, specific API endpoints return errors while others succeed. A production MCP server serving Amazon Q users needs both:

1. Protocol-level monitoring via AliveMCP — probes the initialize + tools/list handshake every 60 seconds
2. AWS API health checks — a /health endpoint that tests a cheap AWS API call (e.g., sts:GetCallerIdentity) to verify the IAM credentials are still valid

// Health endpoint for MCP server with AWS API dependencies
app.get('/health', async (req, res) => {
  const checks = {
    mcp: 'ok',
    iam_credentials: 'unknown',
    dynamodb: 'unknown',
  };

  try {
    // Cheapest IAM check — does not call the actual service
    const sts = new STSClient({});
    await sts.send(new GetCallerIdentityCommand({}));
    checks.iam_credentials = 'ok';
  } catch (e) {
    checks.iam_credentials = `error: ${e.message}`;
  }

  try {
    const dynamo = new DynamoDBClient({});
    await dynamo.send(new ListTablesCommand({ Limit: 1 }));
    checks.dynamodb = 'ok';
  } catch (e) {
    checks.dynamodb = `error: ${e.message}`;
  }

  const allOk = Object.values(checks).every(v => v === 'ok');
  res.status(allOk ? 200 : 503).json(checks);
});

Register this health URL as a custom health check in AliveMCP alongside the protocol probe — this way you get alerted whether the failure is at the MCP protocol layer or at the underlying AWS API layer.

Further reading

• MCP server in VS Code — .vscode/mcp.json configuration and debugging
• MCP server on AWS — deployment patterns for EC2, ECS, and Lambda
• MCP server RBAC — role-based access control for tool invocation
• MCP server audit logging — recording who called what and when
• MCP server secrets management — AWS Secrets Manager, Parameter Store, Vault
• AliveMCP — continuous protocol monitoring for MCP servers