--- title: "Connect Cortex to Claude: Manage Service Catalogs and Dependencies" slug: connect-cortex-to-claude-manage-service-catalogs-and-dependencies date: 2026-07-08 author: Sidharth Verma categories: ["AI & Agents"] excerpt: "Learn how to connect Cortex to Claude using a managed MCP server. Automate your Internal Developer Portal, manage scorecards, and traverse service dependencies via AI." tldr: "Connect Cortex to Claude using a managed Model Context Protocol (MCP) server. This guide covers how to bypass custom integration code, handle complex Cortex schemas, and securely expose your service catalog to AI agents." canonical: https://truto.one/blog/connect-cortex-to-claude-manage-service-catalogs-and-dependencies/ --- # Connect Cortex to Claude: Manage Service Catalogs and Dependencies If your team uses ChatGPT, check out our guide on [connecting Cortex to ChatGPT](https://truto.one/connect-cortex-to-chatgpt-automate-governance-and-scorecarding/) and [connecting Cortex to AI Agents](https://truto.one/connect-cortex-to-ai-agents-orchestrate-integrated-workflows/). 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](https://truto.one/what-is-mcp-and-mcp-servers-and-how-do-they-work/). This server acts as the translation layer between Claude's LLM-native tool calls and the Cortex REST API. [Building this infrastructure in-house](https://truto.one/the-hands-on-guide-to-building-mcp-servers-for-ai-agents-2026/) 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: ```bash curl -X POST https://api.truto.one/integrated-account//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: ```json { "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: ```json { "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](https://truto.one/auto-generated-mcp-tools-for-ai-agents-a-2026-architecture-guide/) 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." > Want to see the full list of Cortex endpoints? Check out the [Cortex Integration Page](https://truto.one/integrations/detail/cortex) for complete schema details. > > [Talk to us](https://cal.com/truto/partner-with-truto) ## 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. ```mermaid 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](https://truto.one/managed-mcp-for-claude-full-saas-api-access-without-security-headaches/). 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. > Stop writing integration boilerplate. Generate secure, fully managed MCP servers for Cortex and 100+ other enterprise APIs using Truto. > > [Talk to us](https://cal.com/truto/partner-with-truto)