--- title: "Connect CircleCI to ChatGPT: Manage Pipelines, Workflows, and Jobs" slug: connect-circleci-to-chatgpt-manage-pipelines-workflows-and-jobs date: 2026-10-31 author: Riya Sethi categories: ["AI & Agents"] excerpt: "Learn how to connect CircleCI to ChatGPT using Truto's MCP servers. Automate CI/CD pipelines, triage failed builds, and orchestrate jobs using natural language." tldr: "Connect CircleCI to ChatGPT via Truto's managed MCP servers to orchestrate pipelines, jobs, and workflows. This guide covers setup, tool schemas, rate limits, and security filters." canonical: https://truto.one/blog/connect-circleci-to-chatgpt-manage-pipelines-workflows-and-jobs/ --- # Connect CircleCI to ChatGPT: Manage Pipelines, Workflows, and Jobs If you need to connect CircleCI to ChatGPT to automate CI/CD workflows, triage failed pipelines, or orchestrate deployments using natural language, you need a [Model Context Protocol (MCP) server](https://truto.one/blog/what-is-mcp-and-mcp-servers-and-how-do-they-work/). This server acts as the translation layer between ChatGPT's tool calls and CircleCI's complex REST APIs. You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL. If your team uses Claude, check out our guide on [connecting CircleCI to Claude](https://truto.one/blog/connect-circleci-to-claude-monitor-build-health-insights-and-trends/) or explore our broader architectural overview on [connecting CircleCI to AI Agents](https://truto.one/blog/connect-circleci-to-ai-agents-automate-releases-and-configurations/). Giving a Large Language Model (LLM) read and write access to your core build infrastructure is a massive engineering challenge. You have to handle deeply nested JSON responses for insight metrics, map composite routing keys like project slugs to MCP tool arguments, and ensure that the agent operates securely within scoped environments. Every time CircleCI updates its API schema or adds new endpoints for environments and flaky tests, your custom server code must be updated, redeployed, and tested. This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for CircleCI, connect it natively to ChatGPT, and execute complex pipeline workflows using natural language. > Stop writing boilerplate API integration code. Let Truto generate secure, managed MCP servers for your AI agents in seconds. > > [Talk to us](https://truto.one/book-a-demo/) ## The Engineering Reality of the CircleCI API A custom MCP server is essentially a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover and execute tools via JSON-RPC 2.0, implementing it against CircleCI's specific API surface is exceptionally painful. If you decide to build a custom MCP server for CircleCI, you own the entire API lifecycle. Here are the specific integration challenges that break standard CRUD assumptions when working with CircleCI: ### Composite Identifiers and Project Slugs Unlike standard SaaS APIs that rely heavily on global UUIDs for routing, CircleCI's API requires a composite routing structure for most of its critical operations. You often need the `project_slug` (which combines the VCS provider, organization name, and repository name, such as `gh/my-org/my-repo`) paired with a sequential integer like a `job_number` or `pipeline_number`. Building static MCP schemas for this means your LLM must accurately parse and format these composite slugs before it can call the tool. If the LLM hallucinates the slug format, the API call fails with a generic 404, confusing the agent. ### Deeply Nested Insights and Analytics When an LLM asks "Which tests are flaky in the main branch?", fetching that data requires calling the CircleCI Insights API. The response payloads for timeseries data, summary metrics, and flaky tests are deeply nested arrays of objects. Passing raw, unmapped JSON from these endpoints directly into the LLM's context window will instantly consume tens of thousands of tokens. Your custom MCP server must implement intelligent schema trimming and cursor-based pagination normalization just to keep the payload size manageable for ChatGPT. ### Pagination Quirks and Cursor Enforcement CircleCI relies heavily on page tokens for listing pipelines, workflows, and jobs. An LLM cannot naturally handle cursor-based pagination state across multiple tool calls without strict schema enforcement. If you build this yourself, you have to inject explicit instructions into your tool descriptions forcing the LLM to pass the exact `page_token` back in the next request, unmodified. If the LLM URL-encodes or strips the token, the pagination loop breaks. ## Step 1: Generate the CircleCI MCP Server Truto abstracts away the complexity of schema mapping, cursor enforcement, and tool derivation. It [dynamically generates MCP tools](https://truto.one/blog/auto-generated-mcp-tools-for-ai-agents-a-2026-architecture-guide/) from the CircleCI API documentation and integration configurations. You can generate an MCP server for your connected CircleCI account using either the Truto dashboard or the Truto API. ### Method 1: Via the Truto UI If you prefer a visual interface, you can generate a server in a few clicks: 1. Log into your Truto dashboard and navigate to **Integrated Accounts**. 2. Select your connected CircleCI integrated account. 3. Click the **MCP Servers** tab. 4. Click **Create MCP Server**. 5. Select your desired configuration (e.g., restrict to `read` methods only, or filter by specific tags like `pipelines` and `jobs`). 6. Copy the generated MCP server URL. It will look like `https://api.truto.one/mcp/`. ### Method 2: Via the Truto API For teams building automated agent provisioning pipelines, you can generate the MCP server programmatically. Truto validates the configuration, creates a secure, hashed token stored in a distributed key-value store, and returns the endpoint. Run the following `curl` command, replacing `$INTEGRATED_ACCOUNT_ID` with your CircleCI account ID and `$TRUTO_API_TOKEN` with your Truto API key: ```bash curl -X POST https://api.truto.one/integrated-account/$INTEGRATED_ACCOUNT_ID/mcp \ -H "Authorization: Bearer $TRUTO_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "CircleCI DevOps Agent Server", "config": { "methods": ["read", "write"], "tags": ["pipelines", "workflows", "jobs", "insights"] } }' ``` The API will return a JSON payload containing your ready-to-use MCP server URL: ```json { "id": "mcp_srv_8f9a2b3c", "name": "CircleCI DevOps Agent Server", "config": { "methods": ["read", "write"], "tags": ["pipelines", "workflows", "jobs", "insights"] }, "expires_at": null, "url": "https://api.truto.one/mcp/a1b2c3d4e5f6..." } ``` Treat this URL as a sensitive credential. It encodes the routing and authentication for this specific CircleCI tenant. ## Step 2: Connect the MCP Server to ChatGPT Once you have your Truto MCP URL, connecting it to ChatGPT is straightforward. You can configure this directly in the ChatGPT user interface or via a manual configuration file if you are running a custom MCP client setup. ### Method A: Via the ChatGPT UI If you are using a ChatGPT Pro, Plus, Business, Enterprise, or Education account, you can add custom connectors directly via the UI: 1. Open ChatGPT and navigate to **Settings -> Apps -> Advanced settings**. 2. Toggle **Developer mode** on (custom MCP connectors are behind this flag). 3. Under the **MCP servers / Custom connectors** section, click **Add new**. 4. Enter a descriptive name, such as `CircleCI via Truto`. 5. Paste the Truto MCP URL (`https://api.truto.one/mcp/`) into the Server URL field. 6. Save the configuration. ChatGPT will immediately perform a handshake with the Truto server, exchange capabilities, and list the available CircleCI tools. You can now prompt ChatGPT to manage your CI/CD pipelines natively. ### Method B: Via Manual Config File (SSE Client) If you are orchestrating an internal agent framework or using an MCP client that requires a JSON configuration file to establish a Server-Sent Events (SSE) connection, you can define the Truto endpoint using the standard `@modelcontextprotocol/server-sse` package. Create or update your `mcp_config.json` file: ```json { "mcpServers": { "circleci": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-sse", "--url", "https://api.truto.one/mcp/a1b2c3d4e5f6..." ] } } } ``` When your client initializes, it will send an `initialize` JSON-RPC request to the Truto URL, and Truto will dynamically return the schemas for your integration. ## Hero Tools for CircleCI Truto automatically generates a comprehensive suite of tools based on the CircleCI API schema. Instead of overwhelming the LLM context window with hundreds of generic CRUD endpoints, here are the highest-leverage hero tools that unlock agentic DevOps workflows. ### get_single_circle_ci_pipeline_by_id This tool retrieves the exact state, trigger parameters, and routing metadata for a specific pipeline. It is critical for agents needing to determine why a pipeline was triggered (e.g., webhook, scheduled, or manual) before inspecting its underlying workflows. *Usage notes:* Requires the `id` of the pipeline. Agents should use this tool to gather the `project_slug` if they plan to investigate downstream jobs. > "Check the status of pipeline ID 3fa85f64-5717-4562-b3fc-2c963f66afa6 and tell me what branch triggered it." ### create_a_circle_ci_pipeline Allows ChatGPT to trigger a new pipeline run programmatically. This is essential for workflows where the agent remediates a code issue or configuration drift and needs to manually kick off a deployment or test suite. *Usage notes:* Requires the `project_slug`. You can optionally pass `parameters` in the body schema to inject specific environment variables or trigger parameters for the run. > "Trigger a new deployment pipeline for the project gh/my-org/backend-service and pass the parameter 'deploy_env' as 'staging'." ### list_all_circle_ci_workflows Retrieves all workflows associated with a specific pipeline. Because a single pipeline can spawn multiple workflows (e.g., build, test, deploy), the agent uses this tool to map the execution tree and find which specific workflow failed. *Usage notes:* Requires the `pipeline_id`. The response includes the `status` and `name` of each workflow. > "List all the workflows for pipeline 3fa85f64-5717-4562-b3fc-2c963f66afa6 and identify any that are currently in a failed state." ### get_single_circle_ci_job_by_id Fetches granular details about a specific job, including execution duration, executor type (Docker, machine, macOS), queued time, and exit status. This is the ultimate debugging tool for agents trying to isolate a build failure. *Usage notes:* Requires the `project_slug` and the sequential `id` (which represents the job number, not the UUID). > "Get the details for job number 4052 in the project gh/my-org/frontend-app and tell me how long it took before failing." ### list_all_circle_ci_insights_flaky_tests Queries the CircleCI Insights API to extract historical data on flaky tests for a specific project. This empowers ChatGPT to act as a proactive QA agent, identifying tests that fail intermittently without requiring a full code inspection. *Usage notes:* Requires the `project_slug`. This tool returns aggregated metrics over a specific time window. > "Pull the flaky tests for the project gh/my-org/auth-service over the last 14 days. Are there any specific test files failing more than 10% of the time?" ### create_a_circle_ci_project_env_var Enables the LLM to securely inject or rotate environment variables at the project level. This is highly useful for automated security remediation workflows where a compromised token needs to be replaced immediately. *Usage notes:* Requires the `project_slug`, along with the `name` and `value` of the environment variable. > "Create a new environment variable called STRIPE_API_KEY for the project gh/my-org/billing-api using the value I just provided." For a complete list of all available tools, parameters, and schemas, visit the [CircleCI integration page](https://truto.one/integrations/detail/circleci). ## Workflows in Action Connecting ChatGPT to CircleCI unlocks autonomous DevOps capabilities. Instead of forcing engineers to click through the CircleCI dashboard to triage failures or trigger builds, you can orchestrate multi-step operations using natural language. Here are two concrete scenarios showing exactly how ChatGPT routes tool calls through the Truto MCP server. ### Scenario 1: Triaging a Failed Build and Extracting Flaky Tests When a developer notices a red build in their repository, they can ask ChatGPT to investigate the root cause and check if the failure is legitimate or just a known flaky test. > "My latest pipeline (ID: 8a9b2c3d...) failed. Figure out which job caused the failure, get the job details, and check if the project has a history of flaky tests that might explain this." **Step-by-step execution:** 1. **Call `list_all_circle_ci_workflows`**: ChatGPT queries the pipeline ID to list all workflows and identify which one has a `status` of `failed`. 2. **Call `list_all_circle_ci_jobs`**: Using the failed workflow ID, ChatGPT fetches the list of jobs to isolate the specific job number that crashed. 3. **Call `get_single_circle_ci_job_by_id`**: ChatGPT fetches the granular metadata for the failed job (e.g., job number 8492) to see the execution context and exact error state. 4. **Call `list_all_circle_ci_insights_flaky_tests`**: Finally, ChatGPT queries the Insights API for the project slug to compare the failed job's context against historically flaky tests. **The result**: ChatGPT synthesizes the data and replies: *"Workflow 'build-and-test' failed at job 8492 (integration-tests). Looking at the Insights API, the test suite `auth.spec.ts` has a 12% flakiness rate over the last 14 days, which is the exact test that crashed your job. I recommend re-running the workflow."* ### Scenario 2: Rotating an Environment Variable and Triggering a Deployment If a security alert dictates that an API key must be rotated, an IT admin or DevOps engineer can instruct ChatGPT to update the variable in CircleCI and immediately trigger a deployment to propagate the change. > "We need to rotate the production API key for the billing-service project (gh/acme-corp/billing). Delete the old STRIPE_KEY, create a new one with the value 'sk_live_9999', and trigger a new pipeline run so the service picks up the new key." **Step-by-step execution:** 1. **Call `delete_a_circle_ci_project_env_var_by_id`**: ChatGPT targets the project slug and the specific environment variable name to remove the compromised key. 2. **Call `create_a_circle_ci_project_env_var`**: ChatGPT executes a POST request via the MCP server to securely inject the new `STRIPE_KEY` and its value into the project settings. 3. **Call `create_a_circle_ci_pipeline`**: ChatGPT triggers a fresh build for the `gh/acme-corp/billing` project. 4. **Call `get_single_circle_ci_pipeline_by_id`**: ChatGPT immediately checks the newly created pipeline ID to confirm its state is `running`. **The result**: ChatGPT updates the project configuration seamlessly and replies: *"The old STRIPE_KEY has been deleted and the new one is saved. I triggered a new pipeline (ID: 1a2b3c4d...) to deploy the changes. The pipeline is currently in the 'created' state."* ```mermaid sequenceDiagram participant User as DevOps Engineer participant ChatGPT as ChatGPT participant Truto as Truto MCP Server participant CircleCI as CircleCI API User->>ChatGPT: "Rotate STRIPE_KEY and trigger deploy." ChatGPT->>Truto: call delete_a_circle_ci_project_env_var_by_id Truto->>CircleCI: DELETE /api/v2/project/gh/acme-corp/billing/envvar/STRIPE_KEY CircleCI-->>Truto: 200 OK Truto-->>ChatGPT: MCP tool result (success) ChatGPT->>Truto: call create_a_circle_ci_project_env_var Truto->>CircleCI: POST /api/v2/project/.../envvar CircleCI-->>Truto: 201 Created Truto-->>ChatGPT: MCP tool result (success) ChatGPT->>Truto: call create_a_circle_ci_pipeline Truto->>CircleCI: POST /api/v2/project/.../pipeline CircleCI-->>Truto: JSON (pipeline_id: 1a2b...) Truto-->>ChatGPT: MCP tool result (pipeline details) ``` ## Security and Access Control Giving an AI agent access to your CI/CD infrastructure requires strict governance. Truto provides multiple layers of access control at the MCP server level to ensure your LLMs operate safely. * **Method Filtering**: You can strictly limit an MCP server to read-only operations. By setting `"methods": ["read"]` in your configuration, Truto will dynamically strip out all `create`, `update`, and `delete` tools. The LLM simply won't know those endpoints exist, making accidental destructive actions impossible. * **Tag Filtering**: CircleCI has a massive API surface. You can use tag filtering (`"tags": ["pipelines", "insights"]`) to restrict the LLM's focus. If an agent is built strictly for observability, it doesn't need access to environment variable management tools. * **Require API Token Authentication**: By default, possessing the Truto MCP URL is sufficient to connect. If you enable `require_api_token_auth: true`, the MCP client must also pass a valid Truto API token in the `Authorization` header. This prevents unauthorized users from leveraging the MCP server even if the URL leaks. * **Automatic Expiration**: If you are spinning up an AI agent for a temporary incident response session, you can set an `expires_at` timestamp. Truto schedules an alarm in its infrastructure that automatically destroys the MCP token and purges it from the key-value store exactly when the TTL expires. ## Handling Rate Limits When automating API requests with AI agents, rate limits become a critical architectural concern. LLMs operate quickly and can easily exhaust an API quota if they enter a reasoning loop or attempt to paginate through thousands of workflow runs. It is important to note that **Truto does not retry, throttle, or apply backoff on rate limit errors.** When the upstream CircleCI API returns an HTTP 429 Too Many Requests error, Truto passes that error directly back to the caller. To help your MCP client manage this gracefully, Truto normalizes the upstream rate limit information into standardized HTTP headers per the IETF specification: `ratelimit-limit`, `ratelimit-remaining`, and `ratelimit-reset`. The caller - whether that is a custom LangChain agent or ChatGPT - is solely responsible for reading these headers and executing the appropriate retry and backoff logic. ## Wrap Up Connecting CircleCI to ChatGPT transforms static CI/CD infrastructure into an interactive, agentic workspace. By generating a dynamic MCP server through Truto, you bypass the massive engineering overhead of maintaining schema mappings, dealing with composite project slugs, and building cursor-based pagination logic from scratch. Truto's [documentation-driven architecture](https://truto.one/blog/auto-generated-mcp-tools-for-ai-agents-a-2026-architecture-guide/) ensures that as CircleCI evolves its API, your AI tools update automatically. Stop maintaining fragile API wrappers and let your engineering team focus on shipping product. Use Truto to securely connect your AI agents to the tools they need.