Skip to content

Connect Codebeamer to Claude: Automate Reviews and Testing Cycles

Learn how to connect Codebeamer to Claude using a managed MCP server. Automate requirement reviews, test runs, and ALM workflows without writing integration code.

Yuvraj Muley Yuvraj Muley · · 9 min read
Connect Codebeamer to Claude: Automate Reviews and Testing Cycles

If your engineering or quality assurance team needs to connect Codebeamer to Claude to automate requirement reviews, generate test runs, or sync traceability matrices, you need a Model Context Protocol (MCP) server. This server acts as the critical translation layer between Claude's LLM function calling and Codebeamer's rigid REST APIs. You can either construct and maintain this infrastructure from scratch, or you can use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL in seconds.

If your team uses ChatGPT, check out our guide on /connect-codebeamer-to-chatgpt-manage-requirements-and-dev-workflows/. Or, if you are looking to build headless AI agents outside of standard chat interfaces, explore our broader architectural overview on /connect-codebeamer-to-ai-agents-sync-streams-and-project-data/.

Giving a Large Language Model (LLM) read and write access to a monolithic Application Lifecycle Management (ALM) system like Codebeamer is not a trivial task. Codebeamer's data model is extremely strict. You have to handle dynamic tracker schemas, complex Codebeamer Query Language (cbQL) queries, and rigid item state transitions. Every time Codebeamer updates an endpoint or deprecates a legacy V2 resource, you must update your local MCP server, redeploy, and test the integration.

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

The Engineering Reality of the Codebeamer API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable JSON-RPC 2.0 interface for models to discover tools, the reality of implementing it against Codebeamer's APIs is painful. You are not just integrating a simple task list - you are integrating a highly regulated ALM suite utilized for automotive, medical, and aviation software development.

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

Dynamic Tracker Schemas and Field Mappings Codebeamer does not use a flat, static data model. Everything is built around "Trackers" (e.g., Requirements, Bugs, Test Cases), and every Tracker has a fully customizable schema per project. An LLM has no inherent context on what field ID 10004 means in Project A versus Project B. To expose a create_item tool to Claude, your MCP server must first fetch the Tracker's schema, dynamically generate a JSON schema representing those specific fields, and pass that to the LLM so it knows how to construct the payload. Truto handles this schema dynamicism out of the box, building documentation-driven tool definitions that map directly to the connected instance.

The Nuance of Codebeamer Query Language (cbQL) Retrieving specific items in Codebeamer often requires using cbQL, a specialized SQL-like language. Endpoints like /v3/items/query expect a strictly formatted string. If Claude hallucinates the syntax, the API returns a 400 Bad Request. A well-designed MCP server must provide Claude with explicit prompt instructions within the tool description, detailing exactly how to construct valid cbQL queries for the specific project context.

Strict State Transitions and Item Locks In Codebeamer, you cannot simply update an item's status to "Closed". Items are governed by strict state machines defined in the Tracker configuration. Moving an item requires executing a specific transition, which may require mandatory fields or electronic signatures. Furthermore, items can be softly or strictly locked. An LLM attempting to blindly PUT an update to a locked item will fail. Your integration layer must be intelligent enough to check lock statuses and available transitions before attempting writes.

Generating the Codebeamer MCP Server

Truto's MCP infrastructure transforms any connected Codebeamer account into a live, JSON-RPC 2.0 tool server. Rather than manually mapping Codebeamer's OpenAPI spec to MCP tool formats, Truto dynamically derives the tools from the connected integration's underlying resource definitions and schema records.

Every generated server is securely scoped to a single Codebeamer tenant and authenticated via a cryptographic token baked into the URL. You can create this server through the Truto Dashboard or programmatically via the API.

Method 1: Via the Truto UI

For teams who want to quickly spin up a server for manual testing or ad-hoc Claude usage:

  1. Log into your Truto Dashboard.
  2. Navigate to the Integrated Accounts page and select your connected Codebeamer instance.
  3. Click on the MCP Servers tab.
  4. Click Create MCP Server.
  5. Select your desired configuration (Name, allowed methods, specific tags, and expiration date).
  6. Click Generate and copy the resulting MCP server URL.

Method 2: Via the Truto API

For platform engineers building multi-tenant AI products, you can dynamically provision Codebeamer MCP servers on behalf of your users using the Truto REST API.

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

curl -X POST https://api.truto.one/integrated-account/YOUR_ACCOUNT_ID/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Codebeamer ALM Assistant",
    "config": {
      "methods": ["read", "write", "custom"]
    }
  }'

The Truto platform will validate that the Codebeamer integration is AI-ready, generate a hashed token, store the configuration in our distributed KV store, and return a ready-to-use URL:

{
  "id": "mcp_abc123",
  "name": "Codebeamer ALM Assistant",
  "config": {
    "methods": ["read", "write", "custom"]
  },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6..."
}

Connecting the MCP Server to Claude

Once you have the Truto MCP URL, connecting it to Claude requires zero additional code. You simply register the endpoint with your client of choice.

Method 1: Via the Claude / ChatGPT UI

If you are using Claude's web interface (Enterprise/Team plans) or ChatGPT Plus:

For ChatGPT:

  1. Go to Settings -> Apps -> Advanced settings.
  2. Toggle Developer mode on.
  3. Under MCP servers / Custom connectors, click Add new.
  4. Name the connector "Codebeamer ALM".
  5. Paste the Truto MCP URL into the Server URL field and save.

For Claude (Web):

  1. Go to Settings -> Integrations (or Connectors based on your plan tier).
  2. Click Add MCP Server.
  3. Paste the Truto MCP URL and connect.

Method 2: Via Manual Config File (Claude Desktop / Cursor)

If you are running Claude Desktop locally or using an AI-native IDE like Cursor, you configure the MCP server using a JSON configuration file. Truto supports the SSE (Server-Sent Events) transport layer via the official @modelcontextprotocol/server-sse package.

Locate your claude_desktop_config.json file (typically in ~/Library/Application Support/Claude/ on macOS) and add the following:

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

Restart Claude Desktop. You will now see the hammer icon indicating that the Codebeamer tools have been successfully loaded via the JSON-RPC handshake.

Security and Access Control

Connecting an LLM to a system of record like Codebeamer carries inherent risk. You do not want a hallucinating agent deleting a critical baseline or altering a medical device requirement. Truto provides strict, server-side access controls to mitigate these risks:

  • Method Filtering: Restrict the MCP server to specific HTTP verbs. Pass config: { methods: ["read"] } to ensure Claude can only retrieve data, effectively disabling all POST, PUT, and DELETE operations at the proxy layer.
  • Tag Filtering: Group tools by functional area. If you only want Claude to manage Test Runs, you can filter by tags: ["qa"], ensuring the LLM cannot even see tools related to Source Code or Baselines.
  • Require API Token Auth: By setting require_api_token_auth: true, the bare MCP URL is no longer sufficient. The connecting client must also pass a valid Truto API token in the Authorization header, adding a critical layer of defense-in-depth.
  • Time-to-Live (TTL): Set an expires_at ISO datetime. Once expired, Truto automatically evicts the token from the KV store and database, immediately revoking the LLM's access.

Hero Tools for Codebeamer

Truto exposes dozens of Codebeamer endpoints as cleanly defined MCP tools. Here are the highest-leverage tools available for automating ALM workflows.

Query Tracker Items via cbQL

Tool: list_all_codebeamer_items_query Executes a Codebeamer Query Language string to find specific items across projects and trackers. This is the primary method for agents to locate records dynamically.

"Find all critical bugs in the 'Mobile App' project that are currently in 'In Progress' status using cbQL."

Get Specific Tracker Item

Tool: get_single_codebeamer_item_by_id Retrieves the complete payload of a single tracker item, including custom fields, description, and status context.

"Get the full details and current status of tracker item ID 150942."

Update Item Fields

Tool: update_a_codebeamer_item_by_id Updates specific fields on a tracker item. This is critical for agents moving items through workflows or appending automated analysis.

"Update tracker item 150942 to change its priority to 'High' and assign it to user ID 450."

Comment on an Item

Tool: create_a_codebeamer_items_comment Appends a new comment to a specific tracker item. Essential for AI agents leaving audit trails or review notes.

"Add a comment to item 150942 stating: 'Automated AI review complete: No security vulnerabilities found in the attached specifications.'"

Create a Test Run

Tool: create_a_codebeamer_trackers_testrun Generates a new test run for a specific set of test cases or test sets within a designated test run tracker.

"Create a new test run in tracker ID 1005 for the upcoming V2 release, pulling from test set ID 5099."

Create an Item Review

Tool: create_a_codebeamer_items_review Initiates a formal review process for specific tracker items, setting up the review name and routing settings.

"Create a formal review named 'Q3 Compliance Audit' for tracker items 1400, 1401, and 1405."

To view the complete inventory of available tools, including detailed JSON schema requirements for complex operations like delta merges and baselines, visit the Codebeamer integration page.

Workflows in Action

By chaining these tools together, Claude can execute multi-step ALM processes that typically require tedious manual labor.

Scenario 1: Automating Test Run Creation and Traceability

A QA Lead needs to generate a new test run for a release and immediately notify the team of the pending execution.

"Find all test cases tagged 'V2.5 Release', create a new test run for them in the QA Tracker, and leave a comment on the epic that testing has begun."

Execution Steps:

  1. Claude calls list_all_codebeamer_items_query with a cbQL string filtering for test cases with the specific release tag.
  2. Claude extracts the resulting item IDs.
  3. Claude calls create_a_codebeamer_trackers_testrun, passing the test run tracker ID and the gathered test case references.
  4. Claude calls create_a_codebeamer_items_comment on the parent Epic item, confirming the creation of the test run.
sequenceDiagram
    participant User as User
    participant Claude as Claude Desktop
    participant MCP as Truto MCP Server
    participant CB as Codebeamer API

    User->>Claude: "Create test run for V2.5..."
    Claude->>MCP: Call list_all_codebeamer_items_query<br>{"queryString": "project='Mobile' AND tag='V2.5'"}
    MCP->>CB: GET /v3/items/query
    CB-->>MCP: Returns Test Case IDs
    MCP-->>Claude: JSON Array of IDs
    Claude->>MCP: Call create_a_codebeamer_trackers_testrun
    MCP->>CB: POST /v3/trackers/{id}/testruns
    CB-->>MCP: Test Run created
    MCP-->>Claude: Success
    Claude->>MCP: Call create_a_codebeamer_items_comment
    MCP->>CB: POST /v3/items/{id}/comments
    CB-->>MCP: Comment posted
    MCP-->>Claude: Success
    Claude-->>User: "Test run #1044 created and Epic updated."

Scenario 2: Code Review and Requirements Update

A Systems Engineer wants to conduct a bulk review of newly submitted requirements and flag any that lack sufficient detail.

"Find all requirements in 'Draft' status for the Aviation project. For any requirement under 50 words, change the status back to 'Needs Refinement' and leave a comment explaining why."

Execution Steps:

  1. Claude calls list_all_codebeamer_items_query to fetch the Draft requirements.
  2. Claude analyzes the text content returned in the JSON payload, identifying which items fall short of the 50-word heuristic.
  3. For each failing item, Claude calls update_a_codebeamer_item_by_id to alter the status field to the ID representing 'Needs Refinement'.
  4. Claude concurrently calls create_a_codebeamer_items_comment on those specific items with the rejection reason.

Handling Codebeamer Rate Limits

When writing automated scripts against ALM platforms, you will inevitably hit rate limits. Codebeamer enforces strict quotas on API consumption.

Factual note on rate limits: Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Codebeamer API returns an HTTP 429 (Too Many Requests), Truto passes that error directly back to the caller.

Truto normalizes upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The caller - whether that is your LangGraph agent architecture, Claude Desktop, or a custom application - is entirely responsible for detecting the 429, reading the reset header, and applying appropriate exponential backoff. Do not design your AI agents assuming the integration layer will silently absorb rate limit failures.

Wrap-up

Connecting Codebeamer to AI agents transforms static requirements management into dynamic, autonomous workflows. By utilizing Truto's managed MCP servers, you bypass the friction of reverse-engineering cbQL schemas, managing OAuth token lifecycles, and hand-coding tool definitions.

You simply connect the account, generate the URL, and let Claude handle the orchestration. Your engineers can stop writing basic API glue code and get back to building actual software.

FAQ

How does Claude authenticate with Codebeamer?
Claude authenticates using an MCP server URL generated by Truto. This single URL contains a cryptographically secure token tied to a specific Codebeamer integrated account. You can also enforce a secondary API token requirement for added security.
Does this integration support Codebeamer custom fields?
Yes. Truto dynamically generates MCP tools based on the specific Codebeamer instance's schema. Custom fields mapped in the API documentation are exposed to Claude via standard JSON schema parameters.
How are Codebeamer API rate limits handled?
Truto normalizes Codebeamer rate limit data into standard IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). Truto passes HTTP 429 errors directly to Claude. The client is responsible for implementing retry and backoff logic.
Can I restrict Claude to read-only Codebeamer access?
Yes. When generating the MCP server, you can apply method filters like 'read' to ensure the AI agent can only execute GET and LIST operations, preventing any modifications to trackers or test runs.

More from our Blog