Connect your AI Agents to TeamCity in minutes
Available tools
list_agents
List build agents with their connection and enabled state. Returns agent IDs for triggerbuild's agentid and setagentenabled. NOTE: TeamCity returns only connected, authorized agents unless you set connected or authorized explicitly.
get_agent
Get one build agent by ID, including version, IP, pool and enabled state. Use list_agents to find valid IDs.
set_agent_enabled
Enable or disable a build agent. A disabled agent stays connected but takes no new builds, which is how you drain an agent for maintenance. Use list_agents to find valid IDs.
list_agent_pools
List agent pools, which group build agents and scope them to projects. Returns pool IDs to pass as list_agents' pool filter.
list_builds
List builds with server-side filtering by configuration, project, branch, status, state, agent, user, tag or date. Use listbuildtypes for build_type IDs. IMPORTANT: TeamCity returns only default-branch builds unless you pass branch (use '<any>' for all branches).
get_build
Get one build by ID, including status, timings, agent and what triggered it. Use list_builds to find valid IDs. Pass fields='$long' for the full object, though that is roughly 15x larger.
get_build_log
Get a bounded slice of a build's log as plain text. Defaults to the LAST 200 lines, where failures appear. Build logs are routinely hundreds of kilobytes, so output is always truncated. Use list_builds to find build IDs.
get_build_statistics
Get a build's recorded statistics as name/value pairs, such as BuildDuration, ArtifactsSize, AllTestsDuration and SuccessRate. Use list_builds to find build IDs.
list_build_artifacts
List files and directories in a build's artifacts. Omit path for the artifact root, then pass a directory name to descend. Use list_builds to find build IDs.
list_build_tags
List the tags on a build. Use list_builds to find build IDs.
add_build_tags
Add one or more tags to a build. Existing tags are kept — this appends rather than replaces. Use listbuildtags to see current tags and list_builds to find build IDs.
set_build_pin
Pin or unpin a build. A pinned build is exempt from TeamCity's cleanup rules, so it is how you preserve a release build. Use list_builds to find build IDs.
set_build_comment
Set or replace the comment on a build, for example to record why it was kept or what it shipped. Use list_builds to find build IDs.
cancel_build
Cancel a RUNNING build, optionally re-queueing an identical one. For a build still waiting in the queue use cancelqueuedbuild instead. Use list_builds with state='running' to find build IDs.
list_build_types
List build configurations with server-side filtering by project, name, or paused state. This is how you find the buildtypeid that triggerbuild, listbuilds and getbuildtype require. Use affected_project to include subprojects.
get_build_type
Get a single build configuration by ID. Use listbuildtypes to find valid IDs. Pass fields='$long' for the full object including steps, triggers and parameters.
create_build_type
Create a build configuration in a project. name and projectid are both required — use listprojects to find a valid projectid. Returns the new configuration's ID for use with triggerbuild.
delete_build_type
Permanently delete a build configuration and its build history. Use listbuildtypes to confirm the ID first. To stop builds without deleting, use setbuildtype_paused instead.
set_build_type_paused
Pause or resume a build configuration. A paused configuration starts no new builds from triggers, but can still be started manually. Use listbuildtypes to find valid IDs.
list_build_type_parameters
List a build configuration's build parameters, including those inherited from its project or template. Use these names as the properties keys for triggerbuild. Use listbuild_types to find valid IDs.
set_build_type_parameter
Create or update a single build parameter on a build configuration. Use listbuildtypeparameters to see existing names, and listbuild_types for configuration IDs.
list_build_type_steps
List a build configuration's build steps, with each step's runner type and whether it is disabled. Use listbuildtypes to find valid IDs. Requires permission to view build configuration settings.
list_build_type_triggers
List a build configuration's build triggers (VCS, schedule, dependency) and whether each is disabled. Use listbuildtypes to find valid IDs. Requires permission to view build configuration settings.
list_build_type_branches
List branches known to a build configuration, flagging the default and which are active. This is how you find a valid branchname for triggerbuild or a branch filter for list_builds.
list_build_type_vcs_roots
List the VCS roots attached to a build configuration, with their checkout rules. Returns VCS root IDs for getvcsroot and list_changes. Requires permission to view build configuration settings.
list_changes
List VCS changes (commits) with their messages and authors. Pass build to see what went into a specific build, or pending=true for commits not yet built. Use listbuilds for build IDs and listvcs_roots for VCS root IDs.
get_change
Get one VCS change by ID, including the list of files it touched. Use list_changes to find valid IDs.
list_investigations
List investigations — who has taken ownership of which failures. Filter by assignee, build configuration, project, test, problem or state. Use listusers for usernames (pass as 'username:jsmith') and listbuild_types for configuration IDs.
create_investigation
Assign an investigation so a named user owns a failure. Requires assigneeusername plus a scope (buildtypeid or projectid) and a target (testid, problemid, or anyproblem). Use listusers, listbuildtypes, and listtests or listproblems to get valid values.
delete_investigation
Delete an investigation, releasing ownership of the failure. Pass the investigation id from listinvestigations verbatim — it is itself a locator such as 'buildType:(id:MyProjectBuild)'.
list_mutes
List muted tests and build problems — failures deliberately hidden from build status. Filter by project, reporter, test, problem or type. Use list_users for usernames (pass as 'username:jsmith').
create_mute
Mute failing tests or build problems so they stop failing builds. Requires a scope (projectid or buildtypeid) and a target (testids or problemids). Use listtests or list_problems to get IDs. Set resolution='whenFixed' to unmute automatically once it passes.
delete_mute
Unmute a test or build problem so its failures count again. Use list_mutes to find the mute ID.
list_problem_occurrences
List non-test build failures (compilation errors, exit codes, dependency failures) with their failure messages. Pass build to see why a specific build failed. Use listbuilds to find build IDs. For failing tests use listtest_occurrences instead.
list_problems
Look up build problems by their server-wide identity, to answer 'what is failing or muted in this project'. Requires a selector: problemid, or identity, or affectedproject plus currentlyfailing/currentlymuted. Returns problem IDs for createmute and createinvestigation.
list_projects
List TeamCity projects with server-side filtering by name, archived state, or parent. Use parentproject for direct children only, affectedproject for all descendants. Returns project IDs to pass to listbuildtypes and get_project.
get_project
Get a single TeamCity project by ID. Use list_projects to find valid IDs. Pass fields='$long' for the full object including nested build configurations.
create_project
Create a TeamCity project. Only name is required. Use listprojects to find a parentprojectid, or omit it to create under the root project. Set sourceproject_locator to clone an existing project instead.
delete_project
Permanently delete a TeamCity project along with all of its build configurations and build history. Use list_projects to confirm the ID first.
list_project_parameters
List a project's build parameters, which its build configurations inherit. Use list_projects to find valid project IDs. Password-typed parameters return a null value.
set_project_parameter
Create or update a single build parameter on a project. Use listprojectparameters to see existing names, and list_projects for project IDs. Names are typically prefixed 'env.' or 'system.'.
delete_project_parameter
Delete a single build parameter from a project. Use listprojectparameters to see existing names.
trigger_build
Queue a new build. buildtypeid is required — get it from listbuildtypes. For branchname use listbuildtypebranches; for agentid use listagents; for properties keys use listbuildtypeparameters. Returns the queued build's ID for getqueuedbuild or cancelqueued_build.
list_queued_builds
List builds waiting in the build queue, with each one's queue position and why it has not started. Filter by build configuration, project, agent or user. Use listbuildtypes for build_type IDs.
get_queued_build
Get one queued build by ID, including its queue position, wait reason and estimated start. Use the ID returned by triggerbuild, or listqueued_builds.
cancel_queued_build
Remove a build from the queue before it starts. For a build already running use cancelbuild instead. Use listqueued_builds to find build IDs.
set_queue_paused
Pause or resume the entire TeamCity build queue server-wide. While paused no queued build starts, though builds can still be added. This affects every project on the server.
get_server_info
Get TeamCity server version, build number, start time and web URL. Use to confirm connectivity or check the server version before relying on a version-specific feature.
list_test_occurrences
List individual test runs, filtered by build, configuration, status, or branch. This is the main way to see which tests failed in a build — pass build with status='FAILURE'. Failure stack traces are excluded by default; use gettestoccurrence for those.
get_test_occurrence
Get one test run including its failure details and stack trace. Pass the compound id from listtestoccurrences verbatim, e.g. 'build:(id:6430945),id:2000000000'.
list_tests
Look up tests by their server-wide identity, to answer 'what is failing or muted in this project'. Requires a selector: testid, or name, or affectedproject plus currentlyfailing/currentlymuted. Returns test IDs for createmute and createinvestigation.
list_users
List TeamCity users filtered by username, name, email or group. Returns the usernames needed by createinvestigation's assigneeusername and by the assignee/reporter filters on listinvestigations and listmutes.
get_user
Get one TeamCity user by ID or username, including role assignments and group memberships. Provide userid or username. Use listusers to find valid values.
validate_credential
Validate the TeamCity server URL and access token by fetching the current user.
list_vcs_roots
List VCS roots (configured repository connections) filtered by name, provider type or project. Use repositoryidstring to find which root serves a given repository. Returns IDs for getvcsroot and list_changes.
get_vcs_root
Get one VCS root by ID. Use listvcsroots to find valid IDs. Add 'properties(property(name,value))' to fields to include the connection settings such as the repository URL and branch spec.
trigger_vcs_check
Ask TeamCity to check a VCS root for new commits now, instead of waiting for its polling interval. Use this after pushing so VCS triggers fire promptly. Omit vcsrootid to check every root on the server.
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}
11Open 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}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 }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}FAQs on using Merge's TeamCity MCP server
FAQs on using Merge's TeamCity MCP server
Ready to try it out?
Whether you're an engineer experimenting with agents or a product manager looking to add tools, you can get started for free now
