TeamCity On-Premises 2026.1 Help

与 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。 目前仅支持向 /app/rest/buildQueue 端点发送 POST 请求，以默认或自定义方式触发新构建。 所有由 AI agent 触发的构建都会标记有 personal=true特性。

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

示例

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

export TC_AUTH_TOKEN="your token here"

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

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

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

          在 Cursor 设置中 TeamCity CLI 技能

          技能安装后，可让智能体执行 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年 8月 6日
          AI Assistant配置测试报告和代码覆盖率