Using the Cortex MCP

This article explains how to use the Cortex MCP. For information on setting up the Cortex MCP, refer to Configuring the Cortex MCP.

We'd love your feedback! If you're using the Cortex MCP, we'd love to hear your direct feedback on the configuration process, the tools available, and how you've been using it. Your feedback helps us improve and expand Cortex's capabilities. If you're interested in helping guide Cortex's MCP direction, take the survey.

Starting a new chat

In your MCP client, ask a question about your Cortex workspace. The client uses the Cortex API to provide detailed answers based on your data.

Examples

• You might ask what's going on with a specific Scorecard. The MCP client responds with an overview, Scorecard structure information, a progress summary, and suggestions for next steps.

  
• You could ask about an entity's custom data. The MCP client responds with that entity's custom data and information about when it was created.

  
• You could ask about an entity's dependencies. The MCP client responds with a list of incoming and outgoing dependencies.

  

Available MCP tools

The Cortex MCP can use the following Cortex REST API endpoints:

listInitiatives	listAllEntities
getInitiative	listEntityDescriptors
listRelationshipTypes	listDependenciesForEntity
getRelationshipTypeDetails	getDependency
listEntityRelationships	getEntityDetails
listScorecards	getCustomDataForEntity
getScorecard	getCustomDataForEntityByKey
getScorecardNextStepsForEntity	getCurrentOncallForEntity
listScorecardScores	getEntityDescriptor

Additional tools

getMyWorkspace - Enabled by default, this tool supports the "Mine" capabilities that are available in the Cortex UI. Ask questions like, Show me my Cortex entities or Tell me how my entities are performing against the Production Readiness Scorecard.

Enabling and disabling provided tools

Before submitting questions or commands, you may want to limit the number of provided tools being used by the MCP provider. For example, you might want to use the MCP to ask about entities, but you don't want to allow questions about Scorecards.

Example

In the settings of your MCP client, it's possible to limit which Cortex tools are being used. For example, in Claude desktop:

1. Navigate to Settings > Connectors > Cortex > 3 dots icon > Tools and Settings.

2. Below Provided Tools, toggle off the options you don't need.

3. Restart Claude.

4. Navigate to your Claude chat and enter commands.

Eng Intelligence metrics in the Cortex MCP

Eng Intelligence metrics are also available to Cortex MCP. This brings metric data directly into the Cortex MCP, enabling richer AI-assisted insights, not only into engineering performance, but across your entire Cortex ecosystem. It allows you to be a more proactive leader and enables more data-driven planning sessions.

Querying Eng Intelligence metrics in the Cortex MCP

Ensure you have the latest Cortex MCP version configured in your environment. Once enabled, the MCP automatically includes endpoints for Eng Intelligence metrics. You can then query Eng Intelligence metrics alongside ownership, Scorecard, and Initiative information. For example:

• Evaluate my DORA metric performance in Q3. Highlight where the team is performing well and bring areas of improvement to my attention.

• Which services have concerning MTTR trends, and what scorecard gaps are contributing?

• Recommend initiatives and scorecard changes I could consider to address my upward trend in incidents.

• Review last quarter’s performance against our goals, identify the top three bottlenecks, and suggest changes to our scorecards to address them.

• Is there a correlation between my PR size and how fast we ship?

Crafting effective MCP prompts

The Cortex MCP becomes more powerful when using it becomes second nature to your teams. That shift happens when you have developed prompts that fit your specific role, answer your recurring questions, and surface information in the exact moments you need it. Refer to the Cortex MCP Prompt Library for more information.

Troubleshooting and FAQ

See frequently asked questions below.

When I ask a question in my MCP client, why do I see an error that says I hit the max length for this chat?

This can happen if you're on the free plan of your MCP client.

Can I make changes via the Cortex MCP?

No, you cannot make changes or write data via the Cortex MCP. The MCP is strictly read-only—it only handles GET requests and cannot modify or write data.

How do I resolve "unauthorized" errors in the MCP?

Ensure the value of your Cortex API token is valid in your configuration.

How do I resolve "file not found" errors in the MCP?

Ensure your OpenAPI spec path is correct when mounting.

How do I resolve connection issues with the MCP?

Verify your Cortex API endpoint is accessible.

How do I resolve a 403 forbidden error in the remote MCP?

Ensure that you set up the remote MCP with a personal access token generated in Cortex. Remote MCP setup requires a personal access token, not an API key.

Why do I see an SSL certificate error while using the MCP?

This is most likely caused by an issue within your network. It's recommended to contact your organization's infrastructure or security team to troubleshoot.