MCP Server Setup

CheckUpstream provides an MCP (Model Context Protocol) server that lets AI coding assistants query your upstream health, active incidents, and service status directly from your editor.

Prerequisites

Create an API Key: Go to Settings > API Keys and generate a new key.
Install the MCP server: The server is published as @checkupstream/mcp-server.

npm install -g @checkupstream/mcp-server

Claude Desktop

Add the following to your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "checkupstream": {
      "command": "npx",
      "args": ["-y", "@checkupstream/mcp-server"],
      "env": {
        "CHECKUPSTREAM_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Code

Add CheckUpstream as an MCP server in your project's .mcp.json:

{
  "mcpServers": {
    "checkupstream": {
      "command": "npx",
      "args": ["-y", "@checkupstream/mcp-server"],
      "env": {
        "CHECKUPSTREAM_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursor

In Cursor settings, add a new MCP server:

Name: checkupstream
Command: npx -y @checkupstream/mcp-server
Environment Variables: CHECKUPSTREAM_API_KEY=your-api-key-here

Available Tools

The MCP server exposes these tools to your AI assistant:

Tool	Parameters	Description
`list_projects`	—	List all projects in your organization
`get_dependency_health`	`project?`, `status_filter?`	Get health status of all dependencies
`get_active_incidents`	`project?`, `severity?`	Get currently active incidents affecting your deps
`check_service`	`service` (required)	Check status of a specific service (e.g., "stripe")
`diagnose_error`	`error_message` (required), `service_hint?`, `project?`	Correlate an error message with known outages
`audit_dependencies`	`lockfile_content?`, `project?`	Audit dependencies for known issues
`get_upgrade_path`	`package_name` (required), `current_version?`, `ecosystem?`	Get upgrade path for a package
`get_sla_status`	—	Get SLA compliance scorecard (uptime, compliance rate, downtime)
`get_risk_scores`	—	Get risk scores for all tracked upstream services
`get_incident_trends`	`period?` (`weekly` or `monthly`)	Get incident trend data over the last 6 months
`list_runbooks`	—	List all runbooks with trigger conditions and actions
`get_blast_radius`	`service_id` (required)	Analyze cascade impact of a service outage

Resources

The MCP server also exposes resources that AI tools can fetch by URI:

URI Pattern	Description
`checkupstream://services/{id}`	Detailed service status with components and recent incidents
`checkupstream://incidents/{id}`	Incident details with status updates and affected service

Prompts

Structured prompt templates are available for AI-assisted workflows:

Prompt	Arguments	Description
`triage_incident`	`incident_id` (required)	Structured triage guide with incident context, updates, and recommended tools

Example Usage

Once configured, you can ask your AI assistant questions like:

"Is Stripe having any issues right now?"
"Check the health of my dependencies"
"I'm getting a 503 from api.stripe.com, is there a known outage?"
"List all active incidents affecting the frontend project"
"Show me the SLA compliance scorecard"
"Which services have the highest risk scores?"
"What are the incident trends for the last 6 months?"
"Triage incident inc_abc123"

Self-Hosted

If you're running CheckUpstream self-hosted, set the CHECKUPSTREAM_URL environment variable:

{
  "env": {
    "CHECKUPSTREAM_API_KEY": "your-api-key-here",
    "CHECKUPSTREAM_URL": "https://your-instance.example.com"
  }
}

Troubleshooting

"CHECKUPSTREAM_API_KEY environment variable is required" Make sure the API key is set in the env section of your MCP config.

"Invalid API key" The key may have been revoked. Generate a new one at Settings > API Keys.

Connection timeout Verify your network can reach checkupstream.com (or your self-hosted URL). The MCP server communicates over HTTPS.

Tool not found Restart your AI tool after updating the MCP configuration. Some tools cache the server's tool list on startup.