Cortex MCP

Cortex MCP is a Model Context Protocol server that provides access to the Cortex API. 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?

Research Preview

Not seeing the results you expect? This is an early version of the Cortex MCP. Please send feedback and bug reports to Cortex Customer Engineering.

How to configure Cortex MCP

Prerequisites

Before getting started:

• Create an access token in Cortex.

• You should have an MCP-compatible client installed, such as Claude Desktop, Jetbrains AI Assistant, or Visual Studio Code (VSCode).

  • Paid subscriptions to MCP clients generally give you a larger context window, but the free versions of these clients should suffice.

• You should have Docker installed and running.

  • It is currently only supported to host the MCP server locally.

Step 1: Install Cortex MCP

Run the following command:

docker pull ghcr.io/cortexapps/cortex-mcp:latest

Step 2: Configure your MCP client

Configure your MCP client's settings. Make sure to include your Cortex API key value for the CORTEX_API_TOKEN argument:

{
  "mcpServers": {
    "cortex": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env",
        "CORTEX_API_TOKEN=YOUR_API_TOKEN_HERE",
        "ghcr.io/cortexapps/cortex-mcp:latest"
      ]
    }
  }
}

After updating your configuration, restart your MCP client.

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 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 endpoints:

• listAllEntities

• listEntityDescriptors

• listDependenciesForEntity

• getDependency

• getEntityDetails

• getCustomDataForEntity

• getCustomDataForEntityByKey

• getCurrentOncallForEntity

• getEntityDescriptor

• listInitiatives

• getInitiative

• listScorecards

• getScorecard

• getScorecardNextStepsForEntity

• listScorecardScores

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.

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.

Additional information

For more information, see the Cortex MCP repository in GitHub.

Troubleshooting and FAQ

When I ask a question, 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.

How do I resolve "unauthorized" errors?

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

How do I resolve "file not found" errors?

Ensure that your OpenAPI spec path is correct when mounting.

How do I resolve connection issues?

Verify that your Cortex API endpoint is accessible.