# Cortex MCP [Cortex MCP](https://github.com/cortexapps/cortex-mcp) is a Model Context Protocol server that provides access to the [Cortex API](https://app.gitbook.com/o/RD51qiGImxmmq8NjALb1/s/nPgS8L9MAPtoOtdWdeDp/). It uses relevant context from your workspace, ensuring awareness of your system's structure when answering your questions. You can query information in natural language, powering faster decisions and efficient processes. For example: * Who is the right person to handle an incident with backend-server? * Show me the services that belong to the platform engineering team * Show me the currently active Scorecards and how example-entity is performing. Give me ideas on how I can improve them * We're having an incident with backend-server, give me a summary of information to help handle the incident * What's going on with my Git migration Scorecard? * I want to run an initiative to migrate our company to using GitHub actions. Help me figure out how to do this in Cortex * As someone on the security team, is there anything I should be worried about in my org? Learn about [crafting effective prompts](#crafting-effective-mcp-prompts) and see [Cortex's MCP Prompt Library](#mcp-prompt-library) below. {% hint style="success" %} **Use Cortex MCP with Devin**\ Cortex MCP is [available in the Devin marketplace](https://docs.devin.ai/work-with-devin/mcp#cortex). Cortex MCP identifies the work that needs to be done, and Devin autonomously performs the work — creating PRs, updating documentation, and refactoring code — to bring your services into compliance. [Learn more in our blog](https://www.cortex.io/post/cortex-is-now-available-in-the-devin-marketplace). {% endhint %} ## Cortex MCP demonstration video See a demonstration of how you can use Cortex MCP to get quick answers without having to switch tools: {% embed url="" %} ## How to configure Cortex MCP You can host the MCP server locally, or you can use a remote implementation. ### Prerequisites Before getting started: * [Create an access token](https://docs.cortex.io/configure/settings/api-keys/personal-tokens) in Cortex. * You should have an MCP-compatible client installed, such as [Claude Desktop](https://claude.ai/download), [Jetbrains AI Assistant](https://www.jetbrains.com/help/ai-assistant/configure-an-mcp-server.html), or [Visual Studio Code (VSCode)](https://code.visualstudio.com/docs/copilot/chat/mcp-servers). * Paid subscriptions to MCP clients generally give you a larger context window, but the free versions of these clients should suffice. * If hosting the MCP server locally, you should also have [Docker](https://www.docker.com/) installed and running. ### Configure the MCP {% tabs %} {% tab title="Host locally" %} **Step 1: Install Cortex MCP** Run the following command: ```bash docker pull ghcr.io/cortexapps/cortex-mcp:latest ``` **Step 2: Configure your MCP client** {% hint style="info" %} Looking for IDE-specific setup? Our [README](https://github.com/cortexapps/cortex-mcp?tab=readme-ov-file#installation) has detailed configuration steps for Claude Desktop, Cursor, VS Code, and other MCP clients. {% endhint %} Update your MCP client's configuration file. Make sure to include your Cortex access token value for the `CORTEX_API_TOKEN` argument: ```json { "mcpServers": { "cortex": { "command": "docker", "args": [ "run", "--rm", "--pull", "always", "-i", "--env", "CORTEX_API_TOKEN=YOUR_PERSONAL_ACCESS_TOKEN_HERE", "ghcr.io/cortexapps/cortex-mcp:latest" ] } } } ``` **Alternate option: Create and configure the file in terminal** Alternatively, you could enter the following in terminal to create and configure the file: ``` export CORTEX_API_TOKEN=VALUE_OF_YOUR_PERSONAL_ACCESS_TOKEN cat << EOF > ~/Library/Application\ Support/Claude/claude_desktop_config.json { "mcpServers": { "cortex": { "command": "docker", "args": [ "run", "--pull", "always", "--rm", "-i", "--env", "CORTEX_API_TOKEN=${CORTEX_ACCESS_TOKEN}", "ghcr.io/cortexapps/cortex-mcp:latest" ] } } } EOF ``` {% endtab %} {% tab title="Remote MCP server" %} **Benefits of using the remote MCP** The remote Cortex MCP uses the public `cortex-mcp` package as a dependency, installed from GitHub. This configuration of the Cortex MCP enables: * Faster setup: No need to install or maintain local binaries. * Updated context: Cortex automatically keeps the service aligned with the latest MCP specification. * Secure access: Tokens and access are managed in your Cortex workspace with security best practices. * Seamless integration: It works out of the box with popular MCP clients like VSCode, Claude Code, and Cursor. * More tools: * The remote MCP implementation includes more tools, such as the query\_docs tool that allows you to query Cortex's documentation and knowledge base in natural language. Ask questions like “How do I configure PagerDuty for my Cortex services?” or "How can I use Cortex to drive AI maturity at my org?" * It also includes the ability to add private tools and integrations on top of the public functionality. **Step 1: Add the remote MCP server to your MCP client** Follow the instructions below for Claude, VSCode, or Cursor. Make sure to replace `` with the value of the access token you generated in Cortex. **Claude Code** Run the following command to add the Cortex remote MCP server: ``` claude mcp add --transport http cortex-remote https://mcp.cortex.io/mcp --header "Authorization: Bearer " ``` **VSCode** Add the following configuration to your `.vscode/mcp.json` file: ```json { "servers": { "cortex": { "url": "https://mcp.cortex.io/mcp", "type": "http", "headers": { "Authorization": "Bearer " } } } } ``` For more information, see the [VSCode MCP Servers documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers). **Cursor** Add the following configuration to your Cursor settings: ```json { "mcpServers": { "cortex": { "type": "http", "url": "https://mcp.cortex.io/mcp", "headers": { "Authorization": "Bearer " } } } } ``` **Step 2: Validate your remote MCP configuration** Validate that your remote Cortex MCP is working. * **VSCode**: * Open the Command Palette and search for "MCP: List servers." Confirm that `cortex` appears as a connected server. * **Claude**: * Run the command `claude mcp list` and verify that cortex-remote is in the list of servers. * **Cursor**: * Open Settings > MCP Servers and verify that `cortex` is listed and connected. {% endtab %} {% endtabs %} After updating your configuration, restart your MCP client. #### Self-managed additional configuration If you are a [self-managed Cortex customer](https://docs.cortex.io/self-managed), you must also set `CORTEX_API_BASE_URL=https://` alongside the `CORTEX_API_TOKEN` variable.
Self-managed configuration example Set the `CORTEX_API_BASE_URL` to your backend host URL. ```json { "mcpServers": { "cortex": { "command": "docker", "args": [ "run", "--rm", "--pull", "always", "-i", "--env", "CORTEX_API_TOKEN=YOUR_ACCESS_TOKEN_HERE", "--env", "CORTEX_API_BASE_URL=https://api.cortex.company.com", "ghcr.io/cortexapps/cortex-mcp:latest" ] } } } ``` If you are running a self-hosted instance with CA-signed certificates, you may need to mount them to the container as seen in the example below: ```json { "mcpServers": { "cortex": { "command": "docker", "args": [ "run", "--rm", "--pull", "always", "-i", "-v", "/path/to/your//company_certs.ca:/etc/ssl/certs/company-ca.crt:ro", "--env", "REQUESTS_CA_BUNDLE=/etc/ssl/certs/company-ca.crt", "--env", "SSL_CERT_FILE=/etc/ssl/certs/company-ca.crt", "--env", "CURL_CA_BUNDLE=/etc/ssl/certs/company-ca.crt", "--env", "CORTEX_API_TOKEN=YOUR_ACCESS_TOKEN_HERE", "--env", "CORTEX_API_BASE_URL=https://api.cortex.company.com", "ghcr.io/cortexapps/cortex-mcp:latest" ] } } } ```
## Using Cortex MCP ### Start a new chat In your MCP client, ask a question about your Cortex workspace. The client will use the [Cortex API](#available-mcp-tools) to provide detailed answers based on your data. For example: * You might ask what's going on with a specific Scorecard. The MCP client will respond with an overview, Scorecard structure information, a progress summary, and suggestions for next steps.
* You could ask about the custom data that an entity has. The MCP client will respond with that entity's custom data and information about when it was created:
* You could ask about the dependencies an entity has. The MCP client will respond with a list of incoming and outgoing dependencies:
### Available MCP tools Cortex MCP can use the following [Cortex REST API](https://app.gitbook.com/o/RD51qiGImxmmq8NjALb1/s/nPgS8L9MAPtoOtdWdeDp/) endpoints: * [listAllEntities](https://app.gitbook.com/s/nPgS8L9MAPtoOtdWdeDp/readme/catalog-entities#get-api-v1-catalog) * [listEntityDescriptors](https://app.gitbook.com/s/nPgS8L9MAPtoOtdWdeDp/readme/catalog-entities#get-api-v1-catalog-descriptors) * [listDependenciesForEntity](https://app.gitbook.com/s/nPgS8L9MAPtoOtdWdeDp/readme/dependencies#get-api-v1-catalog-callertag-dependencies) * [getDependency](https://app.gitbook.com/s/nPgS8L9MAPtoOtdWdeDp/readme/dependencies#get-api-v1-catalog-callertag-dependencies-calleetag) * [getEntityDetails](https://app.gitbook.com/s/nPgS8L9MAPtoOtdWdeDp/readme/catalog-entities#get-api-v1-catalog-tagorid) * [getCustomDataForEntity](https://app.gitbook.com/s/nPgS8L9MAPtoOtdWdeDp/readme/custom-data#get-api-v1-catalog-tagorid-custom-data) * [getCustomDataForEntityByKey](https://app.gitbook.com/s/nPgS8L9MAPtoOtdWdeDp/readme/custom-data#get-api-v1-catalog-tagorid-custom-data-key) * [getCurrentOncallForEntity](https://app.gitbook.com/s/nPgS8L9MAPtoOtdWdeDp/readme/on-call#get-api-v1-catalog-tagorid-integrations-oncall-current) * [getEntityDescriptor](https://app.gitbook.com/s/nPgS8L9MAPtoOtdWdeDp/readme/catalog-entities#get-api-v1-catalog-tagorid-openapi) * [listInitiatives](https://app.gitbook.com/s/nPgS8L9MAPtoOtdWdeDp/readme/initiatives#get-api-v1-initiatives) * [getInitiative](https://app.gitbook.com/s/nPgS8L9MAPtoOtdWdeDp/readme/initiatives#get-api-v1-initiatives-cid) * [listRelationshipTypes](https://app.gitbook.com/s/nPgS8L9MAPtoOtdWdeDp/readme/entity-relationship-types#get-api-v1-relationship-types) * [getRelationshipTypeDetails](https://app.gitbook.com/s/nPgS8L9MAPtoOtdWdeDp/readme/entity-relationship-types#get-api-v1-relationship-types-relationshiptypetag) * [listEntityRelationships](https://app.gitbook.com/s/nPgS8L9MAPtoOtdWdeDp/readme/entity-relationships#get-api-v1-relationships-relationshiptypetag) * [listScorecards](https://app.gitbook.com/s/nPgS8L9MAPtoOtdWdeDp/readme/scorecards#get-api-v1-scorecards) * [getScorecard](https://app.gitbook.com/s/nPgS8L9MAPtoOtdWdeDp/readme/scorecards#get-api-v1-scorecards-tag) * [getScorecardNextStepsForEntity](https://app.gitbook.com/s/nPgS8L9MAPtoOtdWdeDp/readme/scorecards#get-api-v1-scorecards-tag-next-steps) * [listScorecardScores](https://app.gitbook.com/s/nPgS8L9MAPtoOtdWdeDp/readme/scorecards#get-api-v1-scorecards-tag-scores) Additional tools: * **getMyWorkspace**: this tool supports the "Mine" capabilities that are available in the Cortex UI. With this tool, you can ask questions like, "Show me my Cortex entities" or "Tell me how my entities are performing against the Production Readiness Scorecard." This tool is enabled by default. #### Eng Intelligence metrics in MCP [Eng Intelligence](https://docs.cortex.io/improve/eng-intelligence) metrics are also available to Cortex MCP as part of the AI Chief of Staff feature. 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. **To query Eng Intelligence metrics in MCP**: Ensure you have the latest Cortex MCP version configured in your environment. Once enabled, the MCP will automatically include 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? Learn how the AI Chief of Staff helps leaders move from viewing data to acting on it: {% embed url="" %} ### Enable and disable 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 only want to use the MCP to ask about entities but you do not want to allow questions about Scorecards. In the settings of your MCP client, it is possible to limit which Cortex tools are being used.
Claude example For example, in Claude desktop: 1. Navigate to **Settings > Connectors > Cortex > 3 dots icon > Tools and Settings**. 2. Under **PROVIDED TOOLS**, toggle off the options you don't need. 3. Restart Claude. 4. Navigate to your Claude chat and enter commands.
## Crafting effective MCP prompts ### Best practices 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. Follow these best practices when crafting prompts: * **Be specific**: Instead of "tell me about services," you could say, "Show me all critical services failing the Production Readiness Scorecard." This will give you more actionable information. * **Combine multiple questions when context helps**: The MCP handles complex prompts like "Who owns orders-api, when was it last deployed, and are there any open incidents?" You get richer context in response to one question instead of piecing together three separate queries. * **Reference your organization's specific constructs**: If you've defined custom Scorecards or Initiatives in Cortex, reference them by name. The MCP understands your organization's specific standards and can query against them directly. * **Use follow-up questions to drill down**: Start broad, then go narrow. "Show me services with failing Scorecards" followed by "What specific checks is checkout-service failing?" moves you from landscape view to action items. * **Build a library of your most-used prompts**: If you ask the same question every Monday morning, save it. Some teams maintain shared prompt libraries so everyone can benefit from patterns that work. See the [Cortex MCP Prompt Library](#mcp-prompt-library) below for ideas. ### MCP Prompt Library We've collated the most effective prompt patterns we've seen across different roles and workflows to build out a library of prompts for engineers, engineering leaders, platform engineers, and SREs. See [Cortex MCP Prompt Library ](https://docs.cortex.io/get-started/mcp/library)for the full list of prompts. ## Additional information For more information, see the [Cortex MCP repository in GitHub](https://github.com/cortexapps/cortex-mcp). See the beta pages to learn more about the [Chief of Staff](https://docs.cortex.io/get-started/broken-reference), which enables the use of Engineering Intelligence metrics in MCP (now available in research preview). {% hint style="success" %} **We'd love your feedback!**\ If you've been 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 our capabilities, if you are interested in helping guide our MCP direction, please submit the survey [here](https://forms.gle/yNLgLBrHTjKRJ34y5). {% endhint %} ## Troubleshooting and FAQ #### When I ask a question in my MCP client, why do I see an error that says I hit the maximum length for this chat? This can happen if you are 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 that the value of your Cortex API token is valid in your configuration. #### How do I resolve "file not found" errors in the MCP? Ensure that your OpenAPI spec path is correct when mounting. #### How do I resolve connection issues with the MCP? Verify that your Cortex API endpoint is accessible. #### How do I resolve a 403 forbidden error in the remote MCP? Check that you are setting up the remote MCP with a [personal access token](https://docs.cortex.io/configure/settings/api-keys/personal-tokens) generated in Cortex. Remote MCP setup requires a PAT, not an API key. #### Why might I see an SSL certificate error while using the MCP? This is most likely caused by an issue within your network. We recommend contacting your organization's infrastructure or security team to troubleshoot.