Getting started with Amazon Q Developer and CircleCI

AI coding assistants like Amazon Q Developer are transforming how you write software. They can generate entire functions, explain complex code, and help you move faster than ever. But there’s a catch: AI-generated code isn’t always correct. It can introduce subtle bugs, security vulnerabilities, or break existing functionality in ways that aren’t immediately obvious.

That’s where continuous integration comes in. CI acts as your safety net, automatically running tests, validating configurations, and catching problems before they reach production. When you’re moving fast with AI assistance, having an automated system that verifies every change becomes essential, not optional.

The good news? Setting up CI takes just a few minutes, and once it’s in place, you get an extra layer of confidence in every AI-assisted change you make. Even better, you can connect your AI assistant directly to your CI system, so you can check build status, investigate failures, and trigger pipelines without ever leaving your IDE.

That’s what we’re building in this guide. By connecting Amazon Q Developer with CircleCI’s MCP server, you’ll create a workflow where AI helps you write code and CI validates it, all working together seamlessly.

Before you start

You’ll need a few things ready:

• A CircleCI account (the free tier works perfectly for this)
• A GitHub account
• Node.js 18 or newer
• Amazon Q Developer installed in your IDE (VS Code or JetBrains)

What makes Amazon Q Developer different

Amazon Q Developer is AWS’s AI-powered coding assistant, and it goes well beyond simple code completion. It understands your codebase, can explain complex code, generate tests, and help you navigate AWS services. Whether you’re working in VS Code or JetBrains, Q Developer integrates directly into your workflow.

What makes Q Developer particularly interesting for CI/CD workflows is its support for MCP, the Model Context Protocol. MCP lets you extend Q Developer’s capabilities by connecting it to external services. Once connected, Q Developer can interact with those services as naturally as it reads your code. In our case, we’ll connect it to CircleCI so Q Developer can fetch build logs, trigger pipelines, and analyze test failures on your behalf.

Finding your way around Amazon Q Developer

If you’re new to Amazon Q Developer, the next sections provide a quick orientation.

Opening the chat panel

Click the Amazon Q icon in the left sidebar (activity bar) of VS Code. This opens the chat panel where you can have conversations with Q Developer about your code, ask questions, and issue commands.

Note: You can also use the keyboard shortcut Cmd+Option+I (Mac) or Ctrl+Alt+I (Windows/Linux) to quickly open or focus the chat panel.

The tools icon

Inside the chat panel, you’ll notice a tools icon. Click this to manage MCP servers. You’ll use this to add CircleCI in a moment.

Why you need CI with your AI IDE

AI assistants are powerful collaborators, but they don’t have perfect knowledge of your codebase, your team’s conventions, or the downstream effects of their suggestions. A function that looks correct in isolation might break an integration test. A refactor that seems clean might introduce a security flaw. CI catches these issues automatically by running your test suite, linters, and security scans on every change. Think of it as a second pair of eyes that never gets tired and checks everything, every time.

Getting started with CircleCI

If you don’t have CircleCI set up yet, getting started takes just a few minutes. CircleCI connects to your GitHub, GitLab, or Bitbucket repository and automatically runs your pipeline whenever you push changes.

The basic steps are:

1. Sign up for a free CircleCI account at circleci.com
2. Connect your version control provider
3. Select a repository to set up
4. Add a .circleci/config.yml file to define your pipeline

CircleCI provides starter templates for most languages and frameworks, so you don’t need to write configuration from scratch.

For detailed instructions, see the CircleCI Quickstart Guide..

Setting up a CircleCI project

To make this integration useful, you need a project with some CI/CD history: builds that have run, tests that have executed, maybe a failure or two you can investigate. You can either fork a demo repo or use something you’re already working on.

Fork the demo repository

If you want a quick path to follow along, fork this ecommerce project that comes pre-configured with CircleCI:

1. Go to github.com/rogerwintercircleci/smarter-testing-ecommerce and fork it
2. Open CircleCI and go to Projects
3. Find your fork and click Set Up Project
4. Let the initial pipeline run

Bring your own project

If you’ve already got a project connected to CircleCI, that works great. Just make sure:

• You have a .circleci/config.yml in place
• The project appears in your CircleCI dashboard
• There are some pipeline runs in the history

Wiring up the CircleCI MCP server

The CircleCI MCP server is the bridge that lets Amazon Q Developer talk to CircleCI’s APIs. It exposes CircleCI’s functionality in a way that Q Developer can understand and use.

Generate your API token

First, create an API token that will authenticate Q Developer with CircleCI:

1. Log into CircleCI
2. Click your avatar in the lower-left corner
3. Navigate to User Settings
4. Go to Personal API Tokens
5. Hit Create New Token
6. Name it something you’ll recognize, like “Amazon Q Developer”
7. Copy the token right away (Note: CircleCI won’t show it again)

Add the MCP configuration

Amazon Q Developer stores MCP configurations in a JSON file. The most reliable way to set up the CircleCI server is to edit this file directly.

Global configuration (available across all projects):

• macOS/Linux: ~/.aws/amazonq/mcp.json
• Windows: %USERPROFILE%\.aws\amazonq\mcp.json

Local configuration (specific to current project):

• Path: .amazonq/mcp.json in your project root

If both files exist, Amazon Q combines them (with local taking precedence for conflicts).

To add the CircleCI server, create or edit the configuration file. Enter this content:

{
  "mcpServers": {
    "circleci": {
      "command": "npx",
      "args": [
        "-y",
        "@circleci/mcp-server-circleci@latest"
      ],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token-here"
      },
      "timeout": 120000
    }
  }
}

Here’s what you need to know:

• The timeout value is in milliseconds—120000 means 2 minutes, which gives the server enough time to initialize
• The args array must have -y and the package name as separate entries
• Replace your-circleci-token-here with your actual CircleCI API token

Alternatively, you can configure through the UI. To add servers through the Q Developer interface:

1. Open the Amazon Q Developer panel in your IDE
2. Open the Chat panel
3. Click the tools icon
4. Click the plus (+) symbol to add a new server
5. Choose your scope (Global or Local)
6. Enter the server details:
   • Name: circleci
   • Transport: stdio
   • Command: npx
   • Arguments: Add -y as one argument, then @circleci/mcp-server-circleci@latest as another
7. Add an environment variable:
   • Name: CIRCLECI_TOKEN
   • Value: Your CircleCI API token
8. Set Timeout to at least 120000 (2 minutes)
9. Click Save

Note: If you encounter timeout errors through the UI, try the config file method instead—it’s more reliable for servers that need longer initialization times.

Confirm the connection

After configuring the server, verify it’s connected:

1. Open the Amazon Q Developer chat panel
2. Click the tools icon
3. You should see “circleci” listed as a configured server
4. If it shows a green indicator or “enabled” status, you’re connected

If there’s an error, click on the server to see details and use the Fix Configuration option if prompted.

Test with a real query

Now you can confirm Q Developer can actually talk to CircleCI. In the chat panel, ask:

What CircleCI projects am I following?

If Q Developer returns a list of your projects with their slugs (formatted like gh/your-username/your-repo), the integration is live and ready to use.

Checking your configuration before you push

One of the most immediately practical things you can do with this integration is validate your CircleCI config without leaving your IDE. No more discovering YAML errors after you’ve already pushed.

Ask Q Developer:

Is my CircleCI configuration valid?

Q Developer reads your .circleci/config.yml and checks it against CircleCI’s validation rules. You’ll get back specific feedback: whether it passes, what errors exist (with line numbers), and suggestions for improvement.

This saves real time when you’re working on complex pipelines or experimenting with new orbs.

Starting pipelines from your IDE

This is one of those quality-of-life improvements that adds up fast. Rather than switching to your browser to trigger a build, just ask Q Developer:

Kick off a pipeline for my current branch

Q Developer reads your Git context and triggers the appropriate build. You’ll get confirmation along with a link if you want to monitor progress in the dashboard.

You can get more specific too:

Run the pipeline on the smarter-testing-demo branch

The build runs in the CircleCI dashboard.

Or target another project entirely:

Start a build for gh/my-org/api-service on main

When you’re in the middle of debugging something and running the pipeline repeatedly, being able to trigger builds without context-switching can keep you focused.

Figuring out why builds fail

Here’s where this integration really earns its keep. When something goes wrong, you no longer have to leave your IDE to investigate.

Ask Q Developer:

What went wrong with my last build?

Q Developer pulls the failure logs and breaks down what happened: which job failed, which step caused the problem, the error output, and context from surrounding steps.

The real value is that Q Developer doesn’t just dump logs on you. It analyzes the failure and suggests what to fix. And since you’re already in your IDE with your code open, you can make the change immediately.

Keep iterating until it passes

You can take this further. Ask Q Developer to handle the whole loop:

Fix that problem and run the pipeline again. Tell me when it's green.

Q Developer will update the code, trigger a new build, watch for results, and report back. If something else breaks, keep going until everything passes. All without leaving your editor.

Inspect a specific pipeline

Sometimes you need to look at a particular build, maybe one from earlier today or one a colleague mentioned:

Show me what happened in this pipeline: https://app.circleci.com/pipelines/github/my-org/my-repo/789

Digging into test results

When tests fail, a simple count like “5 failures” rarely tells you what you need to know. You want specifics: which tests, what assertions failed, where in the code.

Ask Q Developer:

Give me the test results from my last build

You’ll see test names with file locations, pass/fail status, error messages with stack traces, and timing information.

To focus on what’s broken:

Just show me the failing tests

Identifying flaky tests

Flaky tests, the tests that pass sometimes and fail other times, erode trust in your test suite and waste time on unnecessary reruns.

Are there flaky tests in this project?

Q Developer uses the CircleCI MCP sever’s built-in functionality to analyze test history to find tests with inconsistent behavior, giving you a prioritized list to tackle.

Using the CircleCI CLI through Q Developer

The MCP server connects to CircleCI’s cloud APIs, but Q Developer can also run the CircleCI CLI for local operations.

Quick local validation

Validate my config with the CircleCI CLI

This runs validation locally without API calls—fast and works offline.

Execute jobs locally

Run the test job locally using the CircleCI CLI

This spins up Docker containers that mirror CircleCI’s environment, letting you debug jobs without pushing commits.

Choosing the right tool

Method	When to use
MCP server	Fetching real build logs, checking actual pipeline status, triggering remote builds, analyzing test results
CircleCI CLI	Fast local validation, running jobs in containers, iterating on config without remote round trips

Both are available, so use whatever fits the task.

Troubleshooting

Here are some common issues and how to resolve them:

• MCP server isn’t loading
• Server times out during initialization
• Can’t find your project
• Authentication problems
• Tool permissions

MCP server isn’t loading

If Q Developer doesn’t seem to have access to CircleCI tools:

1. Check the tools panel: Click the tools icon in the chat panel. If CircleCI isn’t listed or shows an error, there’s a configuration problem.

2. Validate your configuration: Open ~/.aws/amazonq/mcp.json and check for JSON syntax errors. Common issues include missing commas, unclosed brackets, or trailing commas after the last item.

3. Check server status: Use the tools panel to see if the server shows any error indicators. Click on it for details.

4. Confirm Node.js is installed: Open a terminal and run node --version. You need version 18 or newer.

5. Test the server manually: Run this in your terminal to see if the MCP server starts correctly:

CIRCLECI_TOKEN=your-token npx @circleci/mcp-server-circleci@latest

1. Restart the IDE: Close and reopen VS Code or your JetBrains IDE entirely. Some configuration changes require a full restart.

Server times out during initialization

For “Operation timed out” errors:

1. Increase the timeout: Edit your mcp.json and set "timeout": 180000 (3 minutes) to give the server more time to initialize

2. Check your network: The first run downloads the package from npm, which can be slow on some connections

3. Pre-install the package: Run npx -y @circleci/mcp-server-circleci@latest in your terminal first to cache the package, then restart Q Developer

4. Check the logs: Set Q_LOG_LEVEL=trace environment variable and check logs in $TMPDIR/qlog for detailed error messages

Can’t find your project

If Q Developer doesn’t recognize your project:

1. Make sure the project is followed in your CircleCI dashboard
2. Verify your Git remote: git remote -v
3. Check that your API token has the right permissions
4. Try naming the project explicitly: Get the status of gh/my-org/my-repo

Authentication problems

If you’re hitting token errors:

1. Verify the token is still valid in CircleCI’s User Settings
2. Create a fresh token and update your configuration
3. Watch for accidental whitespace or newlines in the token value

Tool permissions

If Q Developer asks for permission every time you use a CircleCI tool:

1. Open the tools panel
2. Click on the CircleCI server
3. For each tool, change the permission from “Ask” to “Always allow”

Pulling it all together

With Amazon Q Developer connected to CircleCI, you’ve added a powerful capability to your development workflow. You can catch configuration problems before pushing, start and monitor pipelines without leaving your IDE, investigate failures through conversation instead of log-hunting, and track down test issues and flaky tests quickly.

Every browser tab you don’t have to open, every context switch you avoid, preserves a little bit of the focus that makes coding productive. Those small savings compound over a day or a week into noticeably better work.

Ready to streamline your workflow? Sign up for a free CircleCI account and give it a try.