Merge Unified's CircleCI integration Merge Agent Handler's CircleCI MCP server

Connect your AI Agents to CircleCI in minutes

Merge lets you securely connect your agents to CircleCI and thousands of tools instantly

Start building for free

Read docs

CircleCI

Learn more about Merge Agent Handler

Available tools

get_org_oidc_claims

Get an organization's custom OIDC token claims (audience, ttl). Use listcollaborations for orgid.

update_org_oidc_claims

Set an organization's custom OIDC audience and/or token ttl. Unset fields are kept. Needs org admin. Use listcollaborations for orgid.

delete_org_oidc_claims

Reset an organization's custom OIDC claims (audience, ttl) to CircleCI's defaults. Needs org admin. Use listcollaborations for orgid.

get_project_oidc_claims

Get a project's custom OIDC claims, which override the org's. Use listcollaborations for orgid and getproject for projectid.

update_project_oidc_claims

Set a project's custom OIDC audience and/or ttl, overriding the org's. Unset fields are kept. Use listcollaborations for orgid and getproject for projectid.

delete_project_oidc_claims

Remove a project's custom OIDC claims so the org-level values apply again. Use listcollaborations for orgid and getproject for projectid.

list_groups

List the groups in an organization (used for context restrictions and approvals). Use listcollaborations for orgid.

get_group

Get a group in an organization by UUID. Use list_groups to find group IDs.

create_group

Create a group in an organization. Use listcollaborations for orgid. Returns its id; delete it with delete_group. Needs org admin.

delete_group

Delete a group from an organization. Use list_groups to find group IDs.

create_usage_export

Start an export of an organization's credit and compute usage for up to 31 days. Returns usageexportjobid; poll getusage_export until state is 'completed' for the CSV URLs. Needs org admin.

get_usage_export

Get a usage export's state and, once 'completed', its CSV download URLs. Start one with createusageexport.

list_contexts

List an organization's contexts (shared env var sets). Give ownerslug or ownerid from list_collaborations.

get_context

Get a context by UUID. Use list_contexts to find context IDs.

create_context

Create a context in an organization. Returns its id; add variables with setcontextenvvar. Give ownerslug or ownerid from listcollaborations.

delete_context

Delete a context and all its variables. Jobs that use it will fail. Use list_contexts to find IDs.

list_context_env_vars

List the variable names in a context. Values are never returned. Use list_contexts to find IDs.

set_context_env_var

Add a variable to a context, or overwrite one with the same name. Use list_contexts to find context IDs.

delete_context_env_var

Remove a variable from a context. Use listcontextenv_vars to find names.

list_context_restrictions

List the restrictions that limit which projects, groups or pipelines may use a context. Use list_contexts to find context IDs.

create_context_restriction

Restrict a context to a project (getproject for its UUID), a group (listgroups) or an expression. Returns the restriction id; remove with deletecontextrestriction.

delete_context_restriction

Remove a restriction from a context. Use listcontextrestrictions to find restriction IDs.

list_pipeline_definitions

List a project's pipeline definitions (config and checkout source). Their ids are the definitionid runpipeline and triggers take.

get_pipeline_definition

Get a pipeline definition by UUID. Use listpipelinedefinitions to find it.

create_pipeline_definition

Create a pipeline definition on a GitHub App or standalone project: where config is read from and which repo is checked out. Use getproject for projectid; repo externalid is GitHub's numeric repo id. Returns its id; add triggers with createtrigger.

update_pipeline_definition

Change a pipeline definition's name, description, config file path or checkout source. Unset fields are kept. Use listpipelinedefinitions to find definition IDs.

delete_pipeline_definition

Delete a pipeline definition and its triggers. Use listpipelinedefinitions to find it.

list_triggers

List the triggers on a pipeline definition (repo events, webhooks, cron schedules). Use listpipelinedefinitions first.

get_trigger

Get a trigger by UUID. Use list_triggers to find trigger IDs.

create_trigger

Add a trigger to a pipeline definition: GitHub events, a custom webhook, or a cron schedule. Use listpipelinedefinitions for the definition ID. Returns the trigger id.

update_trigger

Change a trigger's event filter, refs, cron schedule, parameters, or enable/disable it. Unset fields are kept. Use list_triggers to find trigger IDs.

delete_trigger

Delete a trigger from a pipeline definition. Use list_triggers to find trigger IDs.

list_environments

List an organization's deploy environments (e.g. staging, production). Use listcollaborations for orgid.

get_environment

Get a deploy environment by UUID. Use list_environments to find environment IDs.

list_components

List an organization's deploy components (deployable services), optionally for one project.

get_component

Get a deploy component by UUID. Use list_components to find component IDs.

list_component_versions

List a component's deployed versions with which one is live per environment. Use it before rollbackproject to find currentversion and target_version.

rollback_project

Roll a component in an environment back to an earlier version. Find names and versions with listcomponents, listenvironments and listcomponentversions first.

get_project_insights

Get a project's Insights summary: runs, success rate, duration and credits per workflow and branch, with trends, for a time window. Use for 'how healthy is this project's CI'.

get_org_insights

Get an organization's Insights summary across projects: runs, success rate, duration and credits, with trends.

list_insights_branches

List the branches that have Insights data for a project, optionally for one workflow.

list_flaky_tests

List a project's flaky tests (tests that both passed and failed on the same commit), with how often they flaked.

list_workflow_metrics

List summary metrics per workflow in a project (runs, success rate, mttr, durations, credits) for a branch or all branches over a time window.

list_workflow_runs

List recent runs of one workflow with status, duration and credits, filtered by branch and date range.

list_workflow_job_metrics

List summary metrics per job in one workflow (runs, success rate, durations, credits), optionally for one job.

get_workflow_insights

Get one workflow's metrics and trends (runs, success rate, mttr, p95 duration, credits) for a branch or all branches.

get_workflow_test_metrics

Get test metrics for a workflow: most-failed and slowest tests and per-run test counts.

get_job_timeseries

Get per-job run and duration metrics for a workflow bucketed hourly or daily over a date range.

get_job

Get a job by UUID: status, number and its project, pipeline and workflow IDs. For executor and timing use getjobdetails.

get_job_details

Get a job's details by project slug and job number: status, duration, executor, parallel runs, messages and web URL. Use listworkflowjobs to find job_number.

list_job_artifacts

List the artifacts a job stored (path and download URL). Use listworkflowjobs to find job_number.

list_job_tests

List a job's test results (name, class, result, failure message, run time) from storetestresults. Use it to see which tests failed. Use listworkflowjobs to find job_number.

cancel_job

Cancel a running job by UUID. Use listworkflowjobs to find the job id; rerun with rerun_workflow.

create_organization

Create a CircleCI organization. vcs_type 'circleci' makes a standalone org; 'github' or 'bitbucket' connects an existing VCS org you can access. Returns the new org's id and slug.

get_organization

Get a CircleCI organization by slug ('gh/acme') or UUID. Use list_collaborations to find orgs.

delete_organization

Permanently delete a CircleCI organization and all of its projects, contexts and settings. Needs org admin. Use list_collaborations to find the org slug or UUID.

list_url_orb_allow_list

List an organization's URL orb allow-list: the URL prefixes config may import orbs from.

create_url_orb_allow_entry

Add a URL prefix to an organization's URL orb allow-list so config can import orbs from it. Needs org admin. Remove it with deleteurlorballowentry.

delete_url_orb_allow_entry

Remove an entry from an organization's URL orb allow-list. Use listurlorballowlist to find entry IDs.

list_pipelines

List recent pipelines in an organization, newest first, across the most recently built projects you follow (CircleCI caps it at 250). Set mine=true for only yours. For one project use listprojectpipelines. Use listcollaborations for orgslug.

list_project_pipelines

List a project's pipelines, newest first, optionally for one branch. The first item for a branch is its latest pipeline; get its workflow status with listpipelineworkflows.

list_my_pipelines

List the pipelines you triggered in one project, newest first. For everyone's use listprojectpipelines.

get_pipeline

Get a pipeline by UUID: state, trigger, branch and commit. Use listprojectpipelines to find IDs.

get_pipeline_by_number

Get a pipeline by its project-scoped number, the one shown in the CircleCI UI (e.g. 8200).

get_pipeline_config

Get a pipeline's config: the source config.yml and the compiled config. Large; read only when debugging config. Use listprojectpipelines for pipeline IDs.

get_pipeline_values

Get the pipeline.* values CircleCI resolved for a pipeline (git branch, revision, trigger source). Use listprojectpipelines for pipeline IDs.

list_pipeline_workflows

List a pipeline's workflows with their status (success, failed, running, onhold). Use this for 'did the latest build pass'. Then listworkflow_jobs for the jobs.

run_pipeline

Trigger a new pipeline on a project, for a branch or tag, with optional parameters. Returns the pipeline id and number. Use listpipelinedefinitions for definition_id when a project has more than one.

continue_pipeline

Continue a dynamic-config pipeline from its setup workflow with generated config. Only valid while the setup job runs, with the key from CIRCLECONTINUATIONKEY.

create_project

Create a project in a GitHub App or standalone (circleci) organization. Returns the new project's id and slug. Then add a pipeline with createpipelinedefinition. Use list_collaborations for the org.

get_project

Get a project by slug ('gh/acme/api'): its UUID, org and repository. The UUID is the project_id other tools take.

delete_project

Permanently delete a project with its settings, env vars and history. Needs org admin. Use get_project to confirm the slug.

get_project_settings

Get a project's advanced settings (auto-cancel, fork PR builds, PR-only builds, OSS, SSH reruns). Needs project admin.

update_project_settings

Change a project's advanced settings. Only the fields you set are sent; the rest keep their value. Read them first with getprojectsettings. Needs project admin.

list_project_env_vars

List a project's environment variables. Values come back masked (last 4 characters only).

get_project_env_var

Get one project environment variable by name, value masked. Use listprojectenv_vars to find names.

create_project_env_var

Create a project environment variable, or overwrite one with the same name. Jobs in the project read it at runtime. Value comes back masked.

delete_project_env_var

Delete a project environment variable. Jobs that read it will no longer see it. Use listprojectenv_vars to find names.

list_checkout_keys

List the SSH checkout keys CircleCI uses to clone a project's repository, with fingerprints.

get_checkout_key

Get one checkout key by fingerprint. Use listcheckoutkeys to find fingerprints.

create_checkout_key

Create an SSH checkout key for a project (a deploy key, or a user key on GitHub OAuth orgs). Returns its fingerprint and public key; delete it with deletecheckoutkey.

delete_checkout_key

Delete a project's checkout key; builds that clone with it will fail. Use listcheckoutkeys to find fingerprints.

list_schedules

List a project's scheduled pipelines with their timetables. GitHub App projects use list_triggers instead.

get_schedule

Get a scheduled pipeline by UUID. Use list_schedules to find schedule IDs.

create_schedule

Create a scheduled pipeline that runs on a UTC timetable. parameters must include 'branch' or 'tag'. Returns the schedule id; remove it with delete_schedule.

update_schedule

Change a scheduled pipeline's name, description, timetable, actor or parameters. Unset fields are kept. Use list_schedules for IDs.

delete_schedule

Delete a scheduled pipeline; it stops firing. Use list_schedules to find schedule IDs.

get_current_user

Get the CircleCI user the API token belongs to: id, login and name.

list_collaborations

List the organizations the token's user belongs to, with each org's id and slug. Call this first to find the orgid or orgslug other tools need (contexts, groups, pipelines, deploys, insights).

get_user

Get a CircleCI user by UUID, e.g. the startedby of a workflow. Use getcurrent_user for yourself.

validate_credential

Validate the CircleCI personal API token by reading the user it belongs to (GET /me).

list_webhooks

List a project's outbound webhooks, optionally only enabled or disabled ones. Use getproject for projectid.

get_webhook

Get an outbound webhook by UUID. Use list_webhooks to find webhook IDs.

create_webhook

Create an outbound webhook that posts workflow-completed and/or job-completed events for a project to a URL. Use getproject for projectid. Returns its id; remove it with delete_webhook.

update_webhook

Change a webhook's name, URL, events, secret, TLS check, or enable/disable it. Unset fields are kept. Use list_webhooks to find webhook IDs.

delete_webhook

Delete an outbound webhook; CircleCI stops posting to its URL. Use list_webhooks to find IDs.

get_workflow

Get a workflow by UUID: name, status, pipeline and timing. Use listpipelineworkflows to find IDs.

list_workflow_jobs

List a workflow's jobs with status, jobnumber and id. Use jobnumber with getjobdetails, listjobtests or listjobartifacts; approval jobs carry the approvalrequestid approveworkflowjob needs.

approve_workflow_job

Approve an on-hold approval job so the workflow continues. Use listworkflowjobs to find the approval job's approvalrequestid. This cannot be undone.

cancel_workflow

Cancel a running workflow and its jobs. Rerun it with rerunworkflow. Use listpipeline_workflows to find IDs.

rerun_workflow

Rerun a workflow from the start, from its failed jobs (fromfailed=true), or for chosen job IDs. Returns the new workflowid. Use listworkflowjobs for job IDs.

View all tools by creating a free account See more tools

How to set up Merge Agent Handler

In an mcp.json file, add the configuration below, and restart Cursor.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5      "headers": {
6        "Authorization": "Bearer yMt*****"
7      }
8    }
9  }
10}
11

Copy Code

Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.

Make sure Claude is using the Node v20+.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "command": "npx",
5      "args": [
6        "-y",
7        "mcp-remote@latest",
8        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9        "--header",
10        "Authorization: Bearer ${AUTH_TOKEN}"
11      ],
12      "env": {
13        "AUTH_TOKEN": "yMt*****"
14      }
15    }
16  }
17}

Copy Code

Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.

Learn more in the official documentation ↗

1{
2    "mcpServers": {
3      "agent-handler": {
4        "command": "npx",
5        "args": [
6          "-y",
7          "mcp-remote@latest",
8          "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9          "--header",
10          "Authorization: Bearer ${AUTH_TOKEN}"
11        ],
12        "env": {
13          "AUTH_TOKEN": "<ah-production-access-key>"
14        }
15      }
16    }
17  }

Copy Code

In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".

You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.

Learn more in the official documentation ↗

1{
2  "inputs": [
3    {
4      "type": "promptString",
5      "id": "agent-handler-auth",
6      "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7      "password": true
8    }
9  ],
10  "servers": {
11    "agent-handler": {
12      "type": "stdio",
13      "command": "npx",
14      "args": [
15        "-y",
16        "mcp-remote@latest",
17        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18        "--header",
19        "Authorization: Bearer ${input:agent-handler-auth}"
20      ]
21    }
22  }
23}