Connect Cortex to Claude: Manage Service Catalogs and Dependencies

If your team uses ChatGPT, check out our guide on connecting Cortex to ChatGPT and connecting Cortex to AI Agents.

Platform engineering teams rely on Cortex as their source of truth. It holds your service catalog, deployment histories, ownership mappings, and production readiness scorecards. When an incident occurs or an audit is due, developers waste valuable time cross-referencing Datadog dashboards, Jira tickets, and Cortex scorecards.

Giving an AI agent like Claude direct read and write access to your Internal Developer Portal (IDP) changes this dynamic. Instead of clicking through a UI to find who owns a failing service and what dependencies it has, you can ask Claude to do the investigation, pull the relevant GitOps logs, and request a scorecard exemption on your behalf.

To make this work, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's LLM-native tool calls and the Cortex REST API. Building this infrastructure in-house requires managing authentication lifecycles, maintaining massive OpenAPI-to-JSON-Schema mappings, and writing complex boilerplate to handle pagination.

This guide breaks down how to bypass the custom code and use Truto to dynamically generate a secure, authenticated MCP server for Cortex. We will cover the engineering reality of the Cortex API, exactly how to configure the connection, and run through real-world platform engineering workflows.

The Engineering Reality of the Cortex API

Building a custom MCP server is an exercise in managing technical debt. You are not just building a generic proxy - you must intimately understand the API design patterns of the vendor you are connecting to.

If you build an in-house MCP server for Cortex, here are the specific architectural hurdles you will face:

Polymorphic Identifiers Many Cortex API endpoints accept an identifier that can be either a human-readable tag (like payment-gateway) or an internal UUID (id). If you expose raw endpoints to an LLM, the model will frequently confuse which identifier to use across different method calls, resulting in 404 errors. A managed integration layer normalizes these into a predictable tag_or_id parameter, providing explicit instructions in the schema so the LLM understands how to resolve entities correctly.

Complex YAML Descriptors Cortex configuration is heavily driven by large YAML descriptors (e.g., Scorecards, Custom Data, and OpenAPI specs). If you ask Claude to update a scorecard, passing a raw YAML string directly through an unmanaged REST call is highly error-prone. The LLM might hallucinate indentation or omit required schema fields. A proper MCP layer provides strict JSON Schema validation for the request body, rejecting malformed tool calls before they hit the Cortex upstream.

Nested Pagination Structures Cortex paginates its lists using a nested metadata structure containing page, total, totalPages, and the actual array of objects (e.g., entities). LLMs struggle with nested pagination schemas if they are not explicitly instructed on how to handle the cursor or offset. Truto flattens this complexity by injecting limit and next_cursor parameters into the query schema automatically. The next_cursor description explicitly instructs the LLM to pass cursor values back unchanged, preventing hallucinated offsets.

Strict Rate Limits and Error Handling Cortex enforces strict rate limits to protect its infrastructure. A common mistake engineers make when building custom MCP servers is trying to absorb these errors silently or implementing complex, stateful retry queues in the middle tier.

Truto takes a deterministic approach: it does not retry, throttle, or apply backoff on rate limit errors. When Cortex returns an HTTP 429 Too Many Requests, Truto passes that error directly to the caller. Furthermore, Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. This cleanly shifts the responsibility of retry and exponential backoff to the LLM agent, where it belongs.

How to Generate the Cortex MCP Server

Instead of writing and deploying custom server code, you can generate a fully managed MCP server scoped specifically to your connected Cortex account. Truto handles this dynamically - the tools are derived directly from the integration's resource definitions and human-readable documentation records at runtime.

You can generate the MCP server using either the Truto dashboard or the API.

Method 1: Via the Truto UI

For teams who want a quick, zero-code setup:

1. Navigate to the Integrated Accounts page in your Truto dashboard and select your connected Cortex instance.
2. Click the MCP Servers tab.
3. Click the Create MCP Server button.
4. Define your configuration. You can assign a human-readable name, restrict operations to specific methods (e.g., read-only), or filter by tags (e.g., only expose scorecard and dependency endpoints).
5. Click Save and copy the generated MCP server URL.

This URL contains a cryptographically hashed token that securely identifies the exact tenant and configuration to use.

Method 2: Via the Truto API

For platform teams looking to automate infrastructure provisioning, you can generate the server programmatically. Make an authenticated POST request to the Truto API:

curl -X POST https://api.truto.one/integrated-account/<CORTEX_INTEGRATED_ACCOUNT_ID>/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cortex Platform Ops Server",
    "config": {
      "methods": ["read", "write"],
      "tags": ["catalog", "scorecards", "dependencies"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The API provisions the secure token in distributed key-value storage and returns a ready-to-use URL:

{
  "id": "mcp_abc123",
  "name": "Cortex Platform Ops Server",
  "config": {
    "methods": ["read", "write"],
    "tags": ["catalog", "scorecards", "dependencies"]
  },
  "expires_at": "2026-12-31T23:59:59.000Z",
  "url": "https://api.truto.one/mcp/t_xyz987..."
}

Connecting the MCP Server to Claude

Once you have your secure URL, you simply point your LLM client at it. All communication happens over HTTP POST using JSON-RPC 2.0 messages.

Method A: Via the Claude Desktop UI

If you are using Claude Desktop (or configuring a custom connector in ChatGPT):

1. Open your Claude Desktop settings and navigate to Integrations (or Settings -> Connectors -> Add custom connector in ChatGPT).
2. Click Add MCP Server.
3. Paste the URL you generated from Truto (https://api.truto.one/mcp/t_xyz987...).
4. Click Add.

The model will immediately send an initialize handshake to the server and execute a tools/list request to discover the available Cortex operations.

Method B: Via Manual Configuration File

If you are managing your Claude Desktop configuration via file (or deploying a headless AI agent), you can use the standard Server-Sent Events (SSE) transport adapter.

Add the following to your claude_desktop_config.json file:

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

Restart Claude. The agent is now fully equipped to read and modify your Cortex environment.

Hero Tools for Cortex Automation

When Claude connects to the server, Truto dynamically compiles the available API endpoints into flattened, LLM-optimized tools. Here are the most powerful tools available for Cortex platform automation.

Get Single Catalog Entity

get_single_cortex_catalog_entity_by_id Retrieves the complete definition of a service, resource, or domain in Cortex. This is the starting point for almost every diagnostic workflow, as it returns ownership data, git links, on-call schedules, and metadata.

"Find the catalog entity for the 'payment-gateway' service and tell me who the listed owners and Slack channels are."

List Dependencies for Entity

cortex_dependency_list_for_entity Traverses the dependency graph. Returns a list of upstream and downstream services that rely on or are relied upon by the target entity.

"What other services depend on the 'user-auth-service'? List their tags and the specific methods they call if available."

List Scorecard Next Steps

cortex_scorecard_get_next_steps_for_entity Evaluates a service against a specific scorecard and returns the exact rules that are currently failing, showing what needs to be done to reach the next tier.

"Check the 'production-readiness' scorecard for the 'checkout-api' service. What are the next steps required to achieve the Gold tier?"

Request Scorecard Exemption

cortex_scorecard_request_exemption Programmatically requests a rule exemption for an entity in a scorecard. This is essential for automated governance workflows where a service might temporarily bypass a rule due to an incident or pending migration.

"Request an exemption for the 'checkout-api' service on the 'has-runbook' rule in the production-readiness scorecard. Set the reason to 'Runbook is currently being drafted in Confluence, ETA 3 days'."

List Recent Deployments

cortex_deploy_list_for_entity Fetches the deployment history for a specific catalog entity, including the environment, SHA, timestamp, and deployer details.

"List the deployments for the 'inventory-worker' service over the last 24 hours. Let me know if there was a deployment to the 'production' environment."

Create Custom Event

create_a_cortex_custom_event Injects a custom event into the timeline of a Cortex entity. Highly useful for AI agents to log automated actions, audit events, or mark the beginning and end of an incident response procedure.

"Create a custom event for the 'billing-service' titled 'AI Automated Audit Completed'. Set the type to 'audit' and the timestamp to now."

Workflows in Action

Exposing these tools to an LLM allows you to orchestrate complex, multi-step Platform Engineering tasks using natural language. Here is how Claude executes real-world scenarios.

Scenario 1: The Incident Response Triager

During an active outage, responders need immediate context on blast radius and recent changes.

"The 'payment-gateway' service is throwing 500s. Who owns it, what are its dependencies, and was it recently deployed?"

How the agent executes this:

1. Look up the entity: Claude calls get_single_cortex_catalog_entity_by_id passing tag_or_id: "payment-gateway". It parses the response to identify the owning team (FinOps) and their Slack channel (#incidents-finops).
2. Check the blast radius: Claude calls cortex_dependency_list_for_entity using the tag to see which upstream services rely on the payment gateway (e.g., checkout-ui, subscription-worker).
3. Audit recent changes: Claude calls cortex_deploy_list_for_entity to fetch the deployment array. It filters the timeline to check if a new SHA was pushed to production in the last hour.
4. Synthesize the report: Claude replies with a structured summary, notifying the user of the owners, the services that are likely impacted, and whether a recent deployment might be the root cause.

sequenceDiagram
    participant User as Developer
    participant Claude as Claude Agent
    participant MCP as Truto MCP Server
    participant Cortex as Cortex API
    
    User->>Claude: "payment-gateway is failing. Who owns it and what depends on it?"
    Claude->>MCP: Call get_single_cortex_catalog_entity_by_id
    MCP->>Cortex: GET /api/v1/catalog/payment-gateway
    Cortex-->>MCP: Returns ownership & metadata
    MCP-->>Claude: JSON Tool Result
    
    Claude->>MCP: Call cortex_dependency_list_for_entity
    MCP->>Cortex: GET /api/v1/catalog/payment-gateway/dependencies
    Cortex-->>MCP: Returns dependency graph edges
    MCP-->>Claude: JSON Tool Result
    
    Claude-->>User: "Owned by FinOps. Checkout-UI and Subscription-worker depend on it."

Scenario 2: The Scorecard Governance Enforcer

Platform teams spend hours chasing down developers to fix failing scorecard rules. You can delegate this workflow entirely to an AI agent.

"Why is the 'auth-service' failing the Production Readiness scorecard? If it is just missing the on-call definition, request an exemption for 7 days citing 'Migration to new PagerDuty instance'."

How the agent executes this:

1. Evaluate the scorecard: Claude calls cortex_scorecard_get_next_steps_for_entity with tag: "production-readiness" and entityTag: "auth-service".
2. Analyze the rules: Claude reviews the returned nextSteps array. It sees that the only failing rule is has-valid-oncall-schedule.
3. Request the exemption: Because the condition matches the user's prompt, Claude calls cortex_scorecard_request_exemption passing the rule identifier, the entity tag, and the reason provided.
4. Confirm action: Claude informs the user that the exemption has been submitted to the platform team for approval.

Security and Access Control

When connecting an AI agent to a mission-critical system like Cortex, security cannot be an afterthought. The Truto MCP architecture provides strict, multi-layered access controls.

• Method Filtering: You can enforce read-only access. By setting config.methods to ["read"] during server creation, Truto will mathematically strip all create, update, and delete operations from the tool generation step. The LLM simply cannot see or execute write operations.
• Tag Filtering: If your integration configures tags (e.g., grouping custom data vs catalog definitions), you can pass config.tags to restrict the server to specific domains. Tools outside those tags are dropped entirely.
• Time-to-Live (TTL): By passing an expires_at ISO datetime during creation, the server becomes ephemeral. Once the clock hits the expiration time, durable scheduling primitives automatically clean up the database records and edge storage, instantly revoking access.
• Required API Authentication: For enterprise zero-trust environments, the token URL alone doesn't have to be enough. Setting require_api_token_auth to true forces the calling client to also pass a valid Truto API token in the Authorization header, ensuring only authenticated personnel can utilize the server.

Giving AI agents secure, normalized access to your Internal Developer Portal unlocks autonomous incident response and governance workflows. By relying on a dynamically generated MCP server, you avoid the technical debt of custom integration code, letting your team focus on building instead of maintaining boilerplate.