Skip to main content

MCP Server Integration

The Causely MCP (Model Context Protocol) server enables developers to access Causely's causal reasoning engine directly from their IDE. It provides a standardized interface for AI assistants and development tools to communicate with Causely’s SaaS backend. The server lets you query service health, investigate incidents, and analyze system behavior without leaving your code editor.

note

The MCP integration is currently an early access feature. Functionality, configuration details, and supported IDEs may change as the feature evolves.

Purpose and Context​

This system bridges the gap between local development tools (IDEs like Cursor) and Causely's cloud-based observability platform, enabling contextual assistance during development and debugging workflows.

What is MCP?​

The Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to AI assistants. By implementing an MCP server, Causely makes it easy for any MCP-compatible IDE or editor to connect to Causely and access your service topology, active root causes, and historical patterns.

Benefits of Using Causely MCP Server​

  • Stay in your workflow: No need to switch between your IDE and the Causely web interface
  • Contextual investigations: Ask questions about services, incidents, and system behavior while you code
  • Faster incident response: Quickly diagnose issues without context switching
  • Natural language queries: Use conversational language to explore your system's health and behavior
  • Real-time insights: Access the same causal reasoning engine that powers the Causely web interface

Supported IDEs​

The Causely MCP server works with any IDE or editor that supports the Model Context Protocol, including:

  • Cursor
  • Visual Studio Code (with MCP extension)
  • Other MCP-compatible editors

Prerequisites​

Before setting up the MCP server connection, ensure you have:

  • Causely SaaS Account: Active account at https://portal.causely.app/
  • Ask Causely Feature: Must be enabled for your tenant
  • MCP-Compatible IDE: An IDE that supports the Model Context Protocol (for example Cursor)

If Ask Causely is not enabled for your account, please contact us.

Setup Guide​

Step 1: Get Your Access Token​

The Causely MCP server uses your existing session token for authentication. To retrieve it:

  1. Login to Causely: Navigate to https://portal.causely.app/ and sign in
  2. Open Browser Developer Tools: Press F12 or right-click and select "Inspect"
  3. Go to Network Tab: Click on the "Network" tab in the developer tools
  4. Make a Request: Perform any action in Causely (for example, navigate to a different page) to trigger a network request
  5. Select a Request: Click on any request to api.causely.app (look for requests named "query")
  6. View Headers: In the request details, click on the "Headers" tab
  7. Find Authorization: Scroll down to "Request Headers" and locate the "Authorization" header
  8. Copy Token: Copy the token value that appears after Bearer (it will start with eyJ...)
Get access token from Network tab Authorization header
note

Access tokens expire every 24 hours. If you encounter authentication errors, repeat this process to get a fresh token. We will improve the authentication method in an upcoming update.

Step 2: Configure Your IDE​

The Causely MCP server is a hosted service at https://api.causely.app/mcp. No installation is required - you simply configure your IDE to connect to it.

Cursor IDE Configuration​

  1. Open MCP Settings: Go to Cursor Settings → Features → Model Context Protocol
  2. Add Server Configuration: 
    {
      "mcpServers": {
        "Causely SaaS": {
          "url": "https://api.causely.app/mcp",
          "transport": "Streamable HTTP",
          "headers": {
            "Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
          }
        }
      }
    }
  3. Replace Token: Replace YOUR_ACCESS_TOKEN_HERE with the token from Step 1
  4. Save Configuration: Save and restart Cursor

Other MCP-Compatible IDEs​

For other IDEs that support the Model Context Protocol, adapt the configuration to your IDE's format, ensuring:

  • URL: https://api.causely.app/mcp
  • Transport: HTTP-based transport (Streamable HTTP)
  • Authorization: Bearer YOUR_ACCESS_TOKEN in request headers

Step 3: Verify Connection​

Test that your connection is working:

  1. Test Query: Ask your AI assistant: "What defects are currently active in Causely?"
  2. Expected Response: You should receive data from your Causely tenant
  3. Troubleshooting: If you don't receive a response, verify:
    • Your access token is valid (not expired)
    • The Copilot feature is enabled for your tenant
    • Your IDE has been restarted after configuration

Using Causely Copilot in Your IDE​

Once configured, you can start asking questions to Causely Copilot directly from your IDE:

  • "What root causes are currently active?"
  • "Why is the checkout service experiencing high latency?"
  • "Show me the dependency graph for the payment service"
  • "What was the root cause of yesterday's outage?"
  • "Are there any services currently breaching their SLOs?"

The MCP server maintains context throughout your conversation, so you can ask follow-up questions and drill deeper into specific issues.

Example Workflows​

Investigating an Active Root Cause​

You: What root causes are active right now?
Copilot: There are 2 active root causes:
1. High latency in checkout service (started 15 minutes ago)
2. Elevated error rate in payment-processor (started 8 minutes ago)

You: Tell me more about the checkout service issue
Copilot: The high latency in checkout service is caused by a database connection pool exhaustion...

Understanding Service Dependencies​

You: What services depend on the user-auth service?
Copilot: The user-auth service has 8 dependent services including:
- checkout-service
- profile-service
- recommendation-engine
...

You: What would be the impact if user-auth goes down?
Copilot: If user-auth becomes unavailable, it would directly impact...

Troubleshooting​

Connection Issues​

If you're unable to connect to the MCP server:

  1. Verify Token Validity: Ensure your access token hasn't expired by extracting a fresh token from the browser
  2. Check Configuration: Verify your IDE's MCP configuration JSON syntax is correct
  3. Restart IDE: Make sure you've restarted your IDE after updating the configuration
  4. Feature Access: Confirm the Copilot feature is enabled for your tenant

Authentication Errors​

If you receive authentication errors:

  1. Refresh Your Token: Extract a new access token from the browser console (Step 1)
  2. Update Configuration: Replace the old token in your IDE's MCP configuration
  3. Restart IDE: Restart your IDE to apply the changes
  4. Check Headers: Ensure the Authorization header format is exactly Bearer YOUR_TOKEN (with a space after "Bearer")

No Response from Queries​

If Causely Copilot doesn't respond to your questions:

  1. Verify Connection: Check that the MCP server appears as connected in your IDE
  2. Test Simple Query: Try a basic question like "What defects are active?"
  3. Check Network: Ensure your network allows connections to https://api.causely.app
  4. Review IDE Logs: Check your IDE's logs for MCP-related errors

Security Considerations​

  • Token Security: Store your access tokens securely and never commit them to version control or share them publicly
  • Token Expiration: Access tokens expire periodically for security; refresh them as needed
  • Session Management: Each token is tied to your user session; logout from the web portal will invalidate the token
  • Network Security: The MCP connection uses HTTPS to ensure encrypted communication

Getting Help​

If you encounter issues or have questions about the MCP server: