与 AI 代理集成

虽然 AI Assistant 是一个用于调试和分析现有 TeamCity 工作流的优秀工具，但它仅可在 TeamCity UI 中使用。但在某些情况下，可能希望通过外部 AI 驱动的工具与 TeamCity 协作。例如，使用像 Air 或 Cursor 这样的 agent IDE 时，可能希望在不离开编程环境的情况下运行 CI/CD 任务。为实现这一目标，智能体需要访问能够与 TeamCity 协作的工具。

有两种主要方式可以启用此功能：CLI 工具和 MCP 服务器。 TeamCity 均支持这两种方式，下面快速介绍各自方案。

MCP: Model Context Protocol 是一种开源标准，用于将 AI 应用程序连接到外部系统。外部 AI 解决方案使用授权请求访问特定端点，并获取适用于该资源的即用型工具列表。
CLI: 如果产品自带 CLI 支持，可以 "教授" AI 智能体使用已支持的命令。为此，agent 需要一个技能——一套指令、脚本和资源，agent 可在相关时加载，用以提升其在专项任务中的性能。最简单的技能就是一个带详细指令的 SKILL.md ，告诉智能体如何执行某个具体任务。

选择 MCP 还是 CLI 集成，取决于 AI 工具的类型及其运行环境。

环境要求. 使用智能体技能要求能在所在环境内安装相关 CLI 工具。例如，本地运行的代码智能体如 Codex、Claude Code 和 Junie CLI 可用技能运行命令并操作文件。与之不同，ChatGPT 或 Claude 这类聊天工具无法直接调用 CLI 工具。
说明性质. 当主要目标是运行特定操作时，CLI 通常是更合适的选择。例如，代码智能体可调用终端命令来报告最新构建状态或运行特定测试套件。与此同时，依赖 MCP 的聊天 agent 在智能问题调查和分析方面表现出色。
安全问题安全性很大程度上取决于权限管控和沙箱隔离。与使用 MCP 工具的智能体相比，不加限制地赋予 CLI 工具的智能体在权限过大时可能造成更多破坏。
实现成本. 如果软件本身拥有较好的 CLI，且厂商已提供现成的技能，通常可直接放入仓库即刻使用，无需服务器配置。 TeamCity CLI 自带现成技能，可以实现上述操作。
可扩展性. 前期一次性连接大量工具会造成显著开销，并大幅缩小 LLM 的可用上下文窗口。为解决此问题，各类解决方案（如 Anthropic 的 Tool search tool ）或许比技能能更好地处理 MCP 工具。

对 TeamCity 而言， CLI 工具可实现更丰富的集成选项。 agent 可以用 CLI 命令禁用 agent或编辑项目参数，而 TeamCity MCP 工具目前仅支持范围更窄的面向开发者的操作，如启动个人构建。

CLI 技能还可让智能体在无专用 CLI 命令时，发送 REST API 请求。因此，具备此技能的 agent 可以处理更广泛的 TeamCity 任务。

TeamCity MCP

TeamCity 服务器会公开 <server-url>/app/mcp 端点，该端点公开以下 AI 工具：

teamcity_构建_日志: 用于获取目标构建的完整构建日志。支持按消息类型分页和筛选（所有行或仅警告和错误）。用于调查失败的构建。
teamcity_rest_get: 使用 GET 请求配合 TeamCity REST API ：返回项目及构建配置列表、查找最后一次成功构建、显示当前已静音问题等。可用操作列表取决于认证令牌的权限作用域。
teamcity_rest_post: 发送 POST 请求，并使用 TeamCity REST API ，包括编辑构建配置的请求。在安全模式下，这仅限于 POST 请求，这些请求发送到 /app/rest/buildQueue 端点，用于以默认或自定义设置触发新构建；以这种方式触发的所有构建都标记有 personal=true 特性。
TeamCity 管道获取: 允许 AI 代理检索流水线及其属性（参数、优化设置、附加的 VCS 根和仓库等）。
TeamCity 管道发布: 借助此工具，AI 代理可以创建和更新流水线及其参数，编辑和验证 YAML/Kotlin DSL 设置，测试 VCS 连接等。
TeamCity 管道删除: 允许 AI 代理永久移除流水线及其父项目。

agent 需要通过 TeamCity 的令牌授权才能获取和使用这些工具。可在用户个人资料页签发访问令牌。 TeamCity 支持选择让智能体获取与令牌签发人同级权限，或者按项目微调权限。

OAuth 访问

可以添加服务器，而无需签发用户令牌或在 AI 代理配置中传递该令牌：

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

   

在这种情况下，服务器已添加，但其 MCP 工具在完成认证前仍不可用。例如，在 Air Desktop 中点击连接，或在 Codex CLI 中运行 codex mcp login <server-name>。

之后，AI 客户端会打开 <TeamCity-server-URL>/pkce/authorize.html 页面，可在其中查看授予 AI 代理的权限，并点击授权以签发访问令牌。

请注意，该令牌会继承 TeamCity 权限。例如，如果无法查看服务器日志，AI 代理也无法查看。如果只能编辑特定项目，该代理也会受到相同限制。

安全注意事项

TeamCity MCP 工具包包含可编辑构建配置、流水线和项目的工具。为降低风险并避免任何事故，请根据设置和需求结合使用以下方法。

添加 teamcity.ai.mcp.braveMode.enabled 内部属性，并将其设置为 false （默认）以使用安全模式，或设置为 true 以使用勇敢模式。
在安全模式下， TeamCity 管道发布 和 TeamCity 管道删除 工具不可用， teamcity_rest_post 只能将个人构建加入队列 — 它无法编辑或删除任何内容。勇敢模式会解除这些限制。
细粒度或只读权限需要通过 Bearer 认证传递的手动签发访问令牌。要签发只读令牌，请将其作用域设置为每个项目的限制，并选择只读预设。
通过 OAuth 签发的令牌始终会继承完整的 TeamCity 权限，并且无法在登录期间缩小作用域。
如果客户端支持此功能，可以在其中禁用特定工具。例如，如果使用光标，可以在设置 | 工具和 MCP 中点击各个工具来开启或关闭它们。
请谨慎选择提示和技能措辞，为 AI 代理可以执行的操作设置边界。将其视为补充预防措施，而不是上述技术控制的替代方案：代理仍可能误读或无视指令。

最后，请考虑限制访问令牌的请求速率。除了防止行为异常的代理意外造成请求激增之外，其试运行模式还可以让你在审计日志中查看代理的请求模式，而无需直接阻止它。

示例

本节介绍如何通过 MCP 服务器将主流 AI 工具与 TeamCity 连接。为提升安全性，推荐将 TeamCity 访问令牌导出为环境变量：

export TC_AUTH_TOKEN="your token here"

随后，即可直接用 $TC_AUTH_TOKEN 引用，无需明文值。

要使用 PKCE OAuth 认证，请不要配置授权设置。

Air，Cursor

打开 IDE 设置，将以下 JSON 代码段粘贴添加全局/项目/工作区服务器：

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

    

Claude

如下修改设置 | 开发者 | 编辑配置文件：

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

    

Codex

将以下代码段添加到 ~/.codex/config.toml 文件……

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

    

……或运行以下终端命令。

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

    

Claude Code

运行以下终端命令：

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

    

TeamCity CLI

TeamCity CLI 是一款独立工具，可安装至任意主机以运行构建、查看构建日志、管理智能体，并通过终端命令执行其它操作。

Homebrew（推荐）：

brew install jetbrains/utils/teamcity

安装脚本：

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

Winget（推荐）：

winget install JetBrains.TeamCityCLI

PowerShell（安装脚本）：

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

为启用 AI agent 使用该工具，请运行 teamcity skill install。可选地指定目标智能体和项目。

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

  

该命令会将特定于智能体的技能安装至默认位置，使支持的智能体可自动发现并使用，无需额外配置。

技能安装后，可让智能体执行 TeamCity 相关任务，例如：

“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'.”

更多信息请参阅以下文章： TeamCity CLI AI Agent Skill。

访问令牌速率限制

TeamCity 是一款 CI/CD 解决方案，旨在处理跨多个服务器节点上数百名用户的并行访问。在极少数情况下，与外部工具的集成可能会导致突然的请求激增，从而降低 UI 性能。这种情况通常是由于配置错误导致的，比如外部工具（如 AI 代理）会同时发送数十个请求。

为防止或解决该问题，请使用 teamcity.http.limiter.maxParralelRequestPerUser 内部属性来限制每个访问令牌允许的并发 HTTP 请求数。例如，以下设置将基于令牌的工具并发请求数限制为 20：

teamcity.http.limiter.maxParralelRequestPerUser=20

如需故障排除，请将限制设置为所需值并启用 teamcity.http.limiter.dryRun=true 属性。在此模式下，TeamCity 不会阻止超量请求，而是将其记录在审核日志中。

2026年 9月 11日