Connect Codefresh to Claude: Streamline DevOps and Governance

If you need to connect Codefresh to Claude to automate CI/CD pipelines, troubleshoot Kubernetes deployments, or oversee GitOps governance, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's tool calls and Codefresh's 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 ChatGPT, check out our guide on connecting Codefresh to ChatGPT or explore our broader architectural overview on connecting Codefresh to AI Agents.

Giving a Large Language Model (LLM) read and write access to a sprawling orchestration platform like Codefresh is an engineering challenge. You have to handle API key lifecycles, map massive JSON schemas to MCP tool definitions, and deal with Codefresh's strict infrastructure constraints. Every time Codefresh updates a GitOps endpoint or deprecates a classic pipeline resource, you have to update your server code, redeploy, and test the integration.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Codefresh, connect it natively to Claude Desktop, and execute complex DevOps workflows using natural language.

The Engineering Reality of the Codefresh API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against Codefresh's APIs requires navigating a highly fragmented API surface. Codefresh is not a single domain; it is a CI/CD orchestrator, a GitOps (Argo) controller, and a Kubernetes cluster manager rolled into one.

If you decide to build a custom MCP server for Codefresh, you own the entire API lifecycle. Here are the specific integration challenges you will face:

The GitOps vs Classic Pipeline Dichotomy Codefresh operates two distinct paradigms: classic Pipelines and the newer Environments V2 (GitOps/Argo CD) architecture. The API reflects this split. Managing classic pipelines involves querying /api/pipelines, while managing Argo applications requires interacting with the /api/gitops/applications endpoints. An LLM has no context on which API paradigm your organization uses. You must carefully expose and describe these tools so Claude knows when to use a classic pipeline runner versus an Argo rollout command.

Opaque Proxy Endpoints and Untyped JSON A significant portion of Codefresh's API acts as a proxy to underlying Kubernetes clusters or Git providers. Endpoints like list_all_codefresh_kubernetes_s or list_all_codefresh_clusters_s forward requests to a cluster provider and return completely untyped, opaque JSON objects. The fields depend entirely on the specific cluster or helm chart being queried. When exposing these proxy endpoints to Claude, standard JSON schema generation fails because the upstream documentation does not enumerate the fields. Your MCP implementation must guide the LLM to inspect the keys dynamically rather than relying on a static schema.

Complex ABAC and Execution Contexts Codefresh relies heavily on Attribute-Based Access Control (ABAC) and Execution Contexts to govern who can run what and where. Creating an ABAC rule requires a deeply nested JSON payload defining teams, actions, resources, related resources, and tags. If a single attribute is misaligned with your account's schema, the API rejects the payload. An MCP server must provide Claude with deterministic query tools to fetch valid ABAC resources before attempting any modifications.

Strict Rate Limiting Pass-Through When you hit Codefresh's API rate limits, the API returns an HTTP 429 Too Many Requests response. It is a critical architectural requirement to note that Truto does not retry, throttle, or apply backoff on rate limit errors. When an upstream API returns a 429, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The caller (or the LLM orchestration framework) is entirely responsible for observing these headers and implementing its own retry or backoff logic.

Step 1: Generate the Codefresh MCP Server

Truto dynamically generates MCP tools based on Codefresh's API documentation and your specific configuration. You do not have to write manual tool handlers or JSON schemas.

You can create an MCP server in Truto using either the UI or the Truto API.

Method A: Via the Truto UI

1. Log into your Truto account and connect a Codefresh tenant (via API Key) to create an integrated account.
2. Navigate to the integrated account page for your Codefresh connection.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Configure the server. You can optionally filter the server to only allow read operations or specific tags.
6. Click Save and copy the generated MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4e5f6...).

Method B: Via the Truto API

You can dynamically provision MCP servers programmatically, which is useful for spinning up temporary access for automated CI/CD agents.

Make an authenticated POST request to /integrated-account/:id/mcp:

curl -X POST https://api.truto.one/integrated-account/{codefresh_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Codefresh Read-Only DevOps Agent",
    "config": {
      "methods": ["read"]
    }
  }'

The API returns a secure token URL. The token in the URL is cryptographically hashed in Truto's KV storage, ensuring that the raw URL is the only secret you need to connect the LLM.

Step 2: Connect the MCP Server to Claude

Once you have your Truto MCP URL, you can plug it directly into Claude. This works across the Claude Desktop app, ChatGPT, or custom LangChain/LangGraph applications.

Method A: Via the Claude UI (or ChatGPT)

For enterprise users utilizing Claude's desktop or web interfaces (or ChatGPT's custom connectors):

For Claude Desktop/Web:

1. Go to Settings -> Integrations.
2. Click Add MCP Server.
3. Paste the Truto MCP URL you generated in Step 1.
4. Click Add. Claude will immediately handshake with the server and list the available Codefresh tools.

For ChatGPT:

1. Go to Settings -> Apps -> Advanced settings.
2. Enable Developer mode.
3. Under MCP servers, add a new server, name it (e.g., "Codefresh via Truto"), and paste the URL.

Method B: Via Manual Config File (Claude Desktop)

If you prefer to configure Claude Desktop manually via its configuration file, you can utilize the @modelcontextprotocol/server-sse transport package.

Edit your claude_desktop_config.json file (located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "codefresh_devops": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/YOUR_TRUTO_TOKEN"
      ]
    }
  }
}

Restart Claude Desktop. The app will spawn the SSE bridge and connect to the Truto Codefresh server dynamically.

Codefresh Hero Tools for Claude

Truto automatically derives tools from Codefresh's API schema. Here are 6 high-leverage "hero tools" your AI agent can use to orchestrate Codefresh.

list_all_codefresh_pipelines

This tool allows Claude to discover all classic CI/CD pipelines in the account. It returns pipeline metadata including triggers, variables, and the last executed timestamps.

"Claude, pull a list of all pipelines in Codefresh and find the one responsible for the 'backend-auth' service. Tell me when it was last executed."

create_a_codefresh_pipelines_run

Triggers a new build for a specific pipeline. The LLM can pass required branch variables or restart a previous build by providing the previousWorkflow ID.

"Trigger a run for the 'frontend-release' pipeline on the 'main' branch. Set the debug flag to true so we can trace any build errors."

list_all_codefresh_workflows

Retrieves a pageable list of Codefresh workflow builds. This is critical for investigating failed runs, checking statuses, and finding the exact commit or committer responsible for a build.

"Check the recent workflow builds in Codefresh. Find the last 3 failed builds across all pipelines and tell me which committers triggered them."

list_all_codefresh_gitops_applications

For organizations using Codefresh Environments V2, this tool lists GitOps (Argo CD) applications. It returns the application manifest including kind, metadata, and spec.

"List all the GitOps applications running in our Codefresh environment. Check their sync status and identify any apps that are currently degraded or out of sync."

list_all_codefresh_kubernetes_releases

Lists the Helm releases deployed on a specific cluster. Claude can use this to verify what exact version of a chart is currently live in an environment.

"Query the production Kubernetes cluster in Codefresh and list all Helm releases. What chart version is currently deployed for the 'payment-gateway' release?"

list_all_codefresh_audit_downloads

Downloads Codefresh audit log records. The LLM can filter by user, entity, action, or date range to perform automated security and governance reviews.

"Download the Codefresh audit logs for the last 48 hours. Look for any 'delete' actions performed on ABAC access-control rules and tell me which user executed them."

To view the complete inventory of available Codefresh tools, required schemas, and data structures, visit the Codefresh integration page.

Workflows in Action

Connecting an LLM to Codefresh unlocks autonomous operations. By chaining tool calls, Claude can execute complex diagnostic and remediation workflows.

Use Case 1: Autonomous Build Triage and Re-Execution

When a developer reports a broken build, Claude can investigate the failure, check the logs, and trigger a debug run automatically.

"A developer reported that the 'billing-service-deploy' pipeline just failed. Find the failed workflow, check who committed the code, and trigger a new debug run for that exact pipeline."

Execution Steps:

1. Claude calls list_all_codefresh_pipelines to find the internal ID for 'billing-service-deploy'.
2. Claude calls list_all_codefresh_workflows filtered by that pipeline ID to find the most recent failed execution and extracts the committer information.
3. Claude calls create_a_codefresh_pipelines_debug (or create_a_codefresh_pipelines_run with the debug parameter) using the pipeline ID to restart the process in debug mode.

sequenceDiagram
    participant User as User
    participant Claude as Claude Desktop
    participant MCP as Truto MCP Server
    participant Codefresh as Codefresh API

    User->>Claude: "Find the failed pipeline and trigger a debug run."
    Claude->>MCP: Call list_all_codefresh_workflows
    MCP->>Codefresh: GET /workflows
    Codefresh-->>MCP: Returns failed build data
    MCP-->>Claude: Parses committer & pipeline ID
    Claude->>MCP: Call create_a_codefresh_pipelines_debug
    MCP->>Codefresh: POST /pipelines/run
    Codefresh-->>MCP: Returns new build ID
    MCP-->>Claude: Confirms pipeline started

Use Case 2: GitOps Application Governance Review

Platform engineering teams must ensure no manual overrides are active on GitOps applications. Claude can perform this audit programmatically.

"Run an audit on all our Codefresh GitOps applications. List all Argo apps, check their specs to see if auto-sync is disabled on any of them, and summarize the risk."

Execution Steps:

1. Claude calls list_all_codefresh_gitops_applications to retrieve the active applications.
2. Claude parses the returned JSON manifests, inspecting the spec.syncPolicy.automated block for each app.
3. Claude identifies applications where automation is missing or degraded, compiles the list, and writes an audit summary back to the user.

Security and Access Control

Providing an LLM with access to your CI/CD infrastructure requires strict governance. Truto's MCP servers enforce zero-trust security principles at the integration layer.

• Method Filtering: You can restrict a Codefresh MCP server to only allow specific operation types. Setting methods: ["read"] ensures the LLM can query pipelines and GitOps apps but cannot trigger builds or alter environments.
• Tag Filtering: Limit the LLM's scope by functional area. You can restrict the MCP server to only expose tools tagged for gitops or abac, hiding standard pipeline execution endpoints entirely.
• Secondary Authentication (require_api_token_auth): For shared MCP URLs, enable this flag to force the calling client to provide a valid Truto API token in the header. Possession of the URL alone will not grant access.
• Time-to-Live (expires_at): Grant temporary access to Claude for a specific incident response window. The MCP server will automatically self-destruct at the ISO datetime you provide, cleaning up both the database and KV storage.

Wrap-Up

Deploying an MCP server for Codefresh bridges the gap between conversational AI and strict CI/CD infrastructure. Instead of writing custom API middleware, managing OAuth or API key states, and dealing with opaque Kubernetes proxy endpoints, you can use Truto to generate a secure, LLM-ready interface in seconds.

Whether you are automating failed build triage, enforcing ABAC governance, or giving your DevOps team a natural language interface to Argo CD, managed MCP servers remove the integration bottleneck. Your engineers can focus on building resilient infrastructure, while Claude handles the day-to-day operations.