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.
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:
- Log into your Truto Dashboard.
- Navigate to the Integrated Accounts page and select your connected Codebeamer instance.
- Click on the MCP Servers tab.
- Click Create MCP Server.
- Select your desired configuration (Name, allowed methods, specific tags, and expiration date).
- 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:
- Go to Settings -> Apps -> Advanced settings.
- Toggle Developer mode on.
- Under MCP servers / Custom connectors, click Add new.
- Name the connector "Codebeamer ALM".
- Paste the Truto MCP URL into the Server URL field and save.
For Claude (Web):
- Go to Settings -> Integrations (or Connectors based on your plan tier).
- Click Add MCP Server.
- 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 allPOST,PUT, andDELETEoperations 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 theAuthorizationheader, adding a critical layer of defense-in-depth. - Time-to-Live (TTL): Set an
expires_atISO 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:
- Claude calls
list_all_codebeamer_items_querywith a cbQL string filtering for test cases with the specific release tag. - Claude extracts the resulting item IDs.
- Claude calls
create_a_codebeamer_trackers_testrun, passing the test run tracker ID and the gathered test case references. - Claude calls
create_a_codebeamer_items_commenton 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:
- Claude calls
list_all_codebeamer_items_queryto fetch the Draft requirements. - Claude analyzes the text content returned in the JSON payload, identifying which items fall short of the 50-word heuristic.
- For each failing item, Claude calls
update_a_codebeamer_item_by_idto alter the status field to the ID representing 'Needs Refinement'. - Claude concurrently calls
create_a_codebeamer_items_commenton 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.