# 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](/get-started/mcp/configuring-cortex-mcp.md).
{% hint style="success" %}
**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](https://forms.gle/yNLgLBrHTjKRJ34y5).
{% endhint %}
## 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](https://docs.cortex.io/api/) endpoints:
| [listInitiatives](/api/readme/initiatives.md#get-api-v1-initiatives) | [listAllEntities](/api/readme/catalog-entities.md#get-api-v1-catalog) |
| ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| [getInitiative](/api/readme/initiatives.md#get-api-v1-initiatives-cid) | [listEntityDescriptors](/api/readme/catalog-entities.md#get-api-v1-catalog-descriptors) |
| [listRelationshipTypes](/api/readme/entity-relationship-types.md#get-api-v1-relationship-types) | [listDependenciesForEntity](/api/readme/dependencies.md#get-api-v1-catalog-callertag-dependencies) |
| [getRelationshipTypeDetails](/api/readme/entity-relationship-types.md#get-api-v1-relationship-types-relationshiptypetag) | [getDependency](/api/readme/dependencies.md#get-api-v1-catalog-callertag-dependencies-calleetag) |
| [listEntityRelationships](/api/readme/entity-relationships.md#get-api-v1-relationships-relationshiptypetag) | [getEntityDetails](/api/readme/catalog-entities.md#get-api-v1-catalog-tagorid) |
| [listScorecards](/api/readme/scorecards.md#get-api-v1-scorecards) | [getCustomDataForEntity](/api/readme/custom-data.md#get-api-v1-catalog-tagorid-custom-data) |
| [getScorecard](/api/readme/scorecards.md#get-api-v1-scorecards-tag) | [getCustomDataForEntityByKey](/api/readme/custom-data.md#get-api-v1-catalog-tagorid-custom-data-key) |
| [getScorecardNextStepsForEntity](/api/readme/scorecards.md#get-api-v1-scorecards-tag-next-steps) | [getCurrentOncallForEntity](/api/readme/on-call.md#get-api-v1-catalog-tagorid-integrations-oncall-current) |
| [listScorecardScores](/api/readme/scorecards.md#get-api-v1-scorecards-tag-scores) | [getEntityDescriptor](/api/readme/catalog-entities.md#get-api-v1-catalog-tagorid-openapi) |
**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](/improve/eng-intelligence.md) 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](/get-started/library.md) 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](/configure/settings/api-keys/personal-tokens.md) 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.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.cortex.io/get-started/mcp/using-cortex-mcp.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.