Integration with AI Agents

While AI Assistant is a great tool for debugging and analyzing existing TeamCity workflows, it is only available in the TeamCity UI. In some cases, though, you may want to work with TeamCity from an external AI-powered tool. For example, when using an agentic IDE such as Air or Cursor, you might want to run CI/CD tasks without leaving your coding environment. To do that, the agent needs access to tools that can work with TeamCity.

There are two main ways to enable this: CLI tools and MCP servers. TeamCity supports both, so let’s start with a quick overview of each approach.

MCP: Model Context Protocol is an open-source standard for connecting AI applications to external systems. Your external AI solution uses an authorized request to the specific endpoint and retrieves a list of ready-to-use tools for working with this resource.
CLI: If a product comes with CLI support, you can "teach" the AI agent to work with supported commands. To do so, an agent needs a skill — a set of instructions, scripts, and resources that the agent can load when relevant to improve its performance in specialized tasks. At its bare minimum, a skill is a simple SKILL.md with detailed instructions that tell an agent how to perform a specific task.

The choice between MCP and CLI integration depends on the nature of your AI tool and its environment.

Environment requirements. Using agent skills demands an environment where you can install the related CLI tool. For example, locally running code agents like Codex, Claude Code, and Junie CLI can use skills to run commands and work with files. Unlike them, chat tools like ChatGPT or Claude cannot use CLI tools directly.
Nature of instructions. When the primary goal is to run specific actions, CLI might be a more natural choice. For example, a code agent can call terminal commands to report the latest build status or run a specific test suite. At the same time, chat agents that rely on MCP excel at smart problem investigation and analytics.
Safety concerns Safety depends heavily on permissions and sandboxing. When compared to an agent using MCP tools, a recklessly used agent armed with CLI tools can do more damage if permissions are too broad.
Implementation costs. If the software already has a good CLI and the vendor gives you a ready-made skill, you can often drop it into the repo and start immediately, without configuring a server connection. TeamCity CLI comes with a ready-to-use skill that allows you to do exactly that.
Scalability. A large number of tools connected upfront may create a significant overhead and drastically reduce the available context window of an LLM. Various solutions designed to mitigate this issue (for example, Anthropic Tool search tool) may deal with MCP tools better than skills.

For TeamCity, the CLI tool provides much broader integration options. An agent can use CLI commands to disable agents or edit project parameters, while the TeamCity MCP tools currently support a much narrower set of developer-focused actions, such as starting personal builds.

The CLI skill also teaches agents how to send REST API requests when no dedicated CLI command exists yet. As a result, agents with this skill can handle a far wider range of TeamCity tasks.

TeamCity MCP

TeamCity servers expose the <server-url>/app/mcp endpoint that exposes the following AI tools:

teamcity_build_log: Retrieves the full build log for the target build. Supports pagination and filtering by message types (all lines or only warnings and errors). Used to investigate failed builds.
teamcity_rest_get: Sends GET requests using TeamCity REST API: return the list of projects and build configurations, find the last successful build, display currently muted problems, and so on. The list of available operations depends on the auth token permissions scope.
teamcity_rest_post: Sends POST requests using TeamCity REST API, including requests that edit build configurations. In safe mode, this is limited to POST requests to the /app/rest/buildQueue endpoint for triggering new builds with default or custom settings; all builds triggered this way are marked with the personal=true attribute.
teamcity_pipeline_get: Allows the AI agent to retrieve pipelines, along with their properties (parameters, optimization settings, attached VCS roots and repositories, and so on).
teamcity_pipeline_post: With this tool, the AI agent can create and update pipelines and their parameters, edit and validate YAML/Kotlin DSL settings, test VCS connections, and more.
teamcity_pipeline_delete: Allows the AI agent to permanently remove pipelines and their parent projects.

To retrieve and use these tools, an AI agent needs to pass token-based authorization in TeamCity. You can issue access tokens on the user profile page. TeamCity allows you to choose whether you want the agent to have same permissions as the user who issued the token, or fine-grained per-project permissions.

OAuth Access

You can add the server without issuing a user token or passing it in the AI agent configuration:

{
  "mcpServers": {
        "TeamCity nightly": {
            "type": "http",
            "url": "<TeamCity-server-URL>/app/mcp",
            // Skip setting up auth settings
            //"headers": { "Authorization": "Bearer $TC_AUTH_TOKEN" }
        }
  }
}

In this case, the server is added, but its MCP tools remain unavailable until you authenticate. For example, click Connect in Air Desktop or run codex mcp login <server-name> in Codex CLI.

After that, your AI client opens the <TeamCity-server-URL>/pkce/authorize.html page, where you can review the permissions granted to the AI agent and click Authorize to issue the access token.

Note that the token inherits your TeamCity permissions. For example, if you cannot view server logs, neither can the AI agent. If you can edit only specific projects, the agent has the same restrictions.

Safety Concerns

The TeamCity MCP toolset includes tools that can edit build configurations, pipelines, and projects. To reduce the risk and avoid any incidents, combine the following techniques according to your setup and needs.

Add the teamcity.ai.mcp.braveMode.enabled internal property and set it to false (default) for safe mode, or true for brave mode.
In safe mode, the teamcity_pipeline_post and teamcity_pipeline_delete tools are unavailable, and teamcity_rest_post can only queue personal builds — it cannot edit or delete anything. Brave mode lifts these restrictions.
Fine-grained or read-only permissions require a manually issued access token passed via Bearer authentication. To issue a read-only token, set its scope to Limit per project and choose the Read-only preset.
An OAuth-issued token always inherits your full TeamCity permissions and cannot be scoped down during sign-in.
Disable specific tools in your client, if it has this functionality. For example, if working in Cursor, you can click individual tools in Settings | Tools and MCPs to toggle them on and off.
Choose your prompt and skill wording carefully to set boundaries for what an AI agent can do. Treat this as a supplementary precaution, not a substitute for the technical controls above: an agent can still misread or disregard instructions.

Finally, consider limiting the access token's request rate. Beyond preventing accidental request spikes from a misbehaving agent, its dry-run mode lets you review an agent's request pattern in the audit log without blocking it outright.

Examples

This section illustrates how to connect most popular AI tools with TeamCity using the MCP server. For better security, we recommend exporting your TeamCity access token into an environment variable:

export TC_AUTH_TOKEN="your token here"

Then, you will be able to use the $TC_AUTH_TOKEN reference instead of a raw value.

To use the PKCE OAuth authentication, omit setting up authorization settings.

Air, Cursor

Open IDE settings and paste the following JSON snippet to add a global/project/workspace server:

{
  "mcpServers": {
        "TeamCity nightly": {
            "type": "http",
            "url": "<TeamCity-server-URL>/app/mcp",
            "headers": {
                "Authorization": "Bearer $TC_AUTH_TOKEN"
            }
        }
  }
}

Claude

Modify the Settings | Developer | Edit config file as follows:

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "<TeamCity-server-URL>/app/mcp",
        "--header",
        "Authorization: Bearer ${TC_AUTH_TOKEN}"
      ]
    }
  }
}

Codex

Add the following snippet to the ~/.codex/config.toml file...

[mcp_servers.buildserver]
url = "<TeamCity-server-URL>/app/mcp"
[mcp_servers.buildserver.http_headers]
Authorization = "Bearer $TC_AUTH_TOKEN"

...or run the following terminal command.

codex mcp add buildserver --url <TeamCity-server-URL>/app/mcp --bearer-token-env-var $TC_AUTH_TOKEN

Claude Code

Run the following terminal command:

claude mcp add --transport http buildserver <TeamCity-server-URL>/app/mcp --header "Authorization: Bearer $TC_AUTH_TOKEN"

TeamCity CLI

TeamCity CLI is a standalone tool that you can install on any machine to run builds, inspect build logs, manage agents, and perform other operations via terminal commands.

Homebrew (recommended):

brew install jetbrains/utils/teamcity

Install script:

curl -fsSL https://jb.gg/tc/install | bash

Winget (recommended):

winget install JetBrains.TeamCityCLI

PowerShell (install script):

irm https://jb.gg/tc/install.ps1 | iex

To enable an AI agent to work with this tool, run teamcity skill install. You can optionally specify the target agent and project.

teamcity skill install
teamcity skill install --project
teamcity skill install --agent claude-code --agent cursor

This command installs agent-specific skills into the default locations, so supported agents can discover and use them automatically — no extra setup needed.

Once the skill is installed, you can ask an agent to perform TeamCity-related tasks such as:

“Start a new build in TeamCity configuration related to this project.”

“Find the latest failed build in the 'My Awesome App' TeamCity project 
and investigate it: why it failed and how to resolve this issue.”

“Find all TeamCity investigations assigned to me and reassign them to
user 'johndoe'.”

See the following article for more information: TeamCity CLI AI Agent Skill.

Access token rate limits

TeamCity is a CI/CD solution designed to handle parallel access from hundreds of users across multiple server nodes. In rare cases, integrations with external tools can cause sudden request spikes that degrade UI performance. This usually happens because of a misconfiguration, when an external tool such as an AI agent sends dozens of requests at the same time.

To prevent or resolve this issue, use the teamcity.http.limiter.maxParralelRequestPerUser internal property to limit the number of simultaneous HTTP requests allowed per access token. For example, the following setting limits token-based tools to 20 concurrent requests:

teamcity.http.limiter.maxParralelRequestPerUser=20

For troubleshooting, set the limit to a desired value and enable the teamcity.http.limiter.dryRun=true property. In this mode, TeamCity does not block excessive requests, but it records them in the audit log.

26 August 2026