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. 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 or explore our broader architectural overview on connecting CircleCI to AI Agents.

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.

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 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/<token>.

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:

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:

{
  "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/<token>) 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:

{
  "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.

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."

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 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.