Getting Started with MCP

What is MCP Integration?

Model Context Protocol (MCP) is an open protocol that allows AI assistants to connect with external tools and data sources. NOFire AI’s MCP integration brings complete production Knowledge directly into your development environment. With MCP, you can: Shift-Left (Before Deployment):

Assess deployment risk before merging code
Analyze blast radius of your changes
Identify critical services affected by your work
Get deployment strategy recommendations

Production Knowledge (Anytime):

Query production environment in natural language
Understand service dependencies and relationships
See what changed recently in any service
Investigate production behavior and incidents
Onboard new engineers by making production knowledge accessible

No dashboard switching. No context loss. All from your IDE.

Supported IDEs

NOFire AI MCP integration works with:

Cursor

Full integration with AI-powered code editor

Claude Desktop

Direct integration with Anthropic’s Claude Desktop app

MCP-Compatible Tools

Any tool supporting Model Context Protocol

Prerequisites

Before setting up MCP integration, ensure you have:

NOFire AI Account

You need a NOFire AI account with connected infrastructure

Data Sources Connected

Connect your observability stack (Grafana, Prometheus, Datadog) OR deploy the NOFire AI Kubernetes agent to build the knowledge graphSetup guide

MCP API Token

Generate an MCP-specific API token from your NOFire AI dashboardAPI token guide

MCP-Compatible IDE

Install Cursor, Claude Desktop, or another MCP-compatible tool

Installation

Cursor Setup

Open Cursor Settings

There are two ways to configure MCP in Cursor:Option 1: Via Cursor Settings UI

Open Cursor Settings (Cmd/Ctrl + ,)
Search for “MCP” in the settings search bar
Look for “Model Context Protocol” section
Click “Edit in mcp.json” or “Configure”

Option 2: Edit Config File DirectlyNavigate to the MCP configuration file:

macOS: ~/.cursor/mcp.json
Linux: ~/.cursor/mcp.json
Windows: %APPDATA%\.cursor\mcp.json

If the file doesn’t exist, create it.

Add NOFire AI Configuration

Add the following configuration to your mcp.json file:

{
  "mcpServers": {
    "NOFireAI": {
      "url": "https://mcp.nofire.ai/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer your-mcp-api-key-here"
      }
    }
  }
}

If you already have other MCP servers configured, add NOFire AI to the existing mcpServers object:

{
  "mcpServers": {
    "existing-server": {
      "url": "...",
      "transport": "..."
    },
    "NOFireAI": {
      "url": "https://mcp.nofire.ai/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer your-mcp-api-key-here"
      }
    }
  }
}

Important: Replace your-mcp-api-key-here with your actual MCP API token from the NOFire AI dashboard.Generate your API token →

Save and Restart Cursor

Save the mcp.json file
Completely quit Cursor (File → Quit or Cmd/Ctrl + Q)
Restart Cursor

A simple window reload is not enough - you must fully quit and restart Cursor for MCP changes to take effect.

Verify NOFire AI is Connected

In Cursor’s AI chat panel, you should see MCP servers listed. Verify NOFire AI appears.Test the connection:Ask Cursor:

Use NOFire AI to discover services in my cluster

Or:

What's the deployment risk for my current changes using NOFire AI?

Expected behavior:

Cursor will call NOFire AI MCP server
You’ll see results about your services or deployment risk
If there’s an error, check the troubleshooting section below

Cursor Settings Tips

Check MCP Status

Look for the MCP icon in Cursor’s status bar (bottom of window)
Click it to see which MCP servers are active
NOFire AI should appear in the list with a green indicator

Enable Detailed Logging To debug connection issues, enable verbose logging in Cursor settings:

Open Settings → Advanced
Enable “Developer Mode” or “Debug Logging”
Check logs in Cursor’s developer console

Claude Desktop Setup

Locate Claude Desktop Config File

Find and open Claude Desktop’s MCP configuration file:macOS:

# Open in default text editor
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Or edit with nano
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows:

# Open in Notepad
notepad %APPDATA%\Claude\claude_desktop_config.json

Linux:

# Open with your preferred editor
nano ~/.config/Claude/claude_desktop_config.json

If the file doesn’t exist, create it with an empty JSON object:

{
  "mcpServers": {}
}

Add NOFire AI Configuration

Add NOFire AI to the mcpServers section:If starting fresh:

{
  "mcpServers": {
    "NOFireAI": {
      "url": "https://mcp.nofire.ai/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer your-mcp-api-key-here"
      }
    }
  }
}

If you have existing servers:

{
  "mcpServers": {
    "existing-server": {
      "command": "...",
      "args": [...]
    },
    "NOFireAI": {
      "url": "https://mcp.nofire.ai/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer your-mcp-api-key-here"
      }
    }
  }
}

Important: Replace your-mcp-api-key-here with your actual MCP API token.Generate your API token →

Validate JSON Syntax

Before saving, ensure your JSON is valid:

Check that all brackets {} and braces [] are closed
Ensure commas between properties (but not after the last one)
All strings must be in double quotes ""

Use a JSON validator if needed:

# On macOS/Linux, validate with Python
python3 -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json

Save and Restart Claude Desktop

Save the configuration file
Completely quit Claude Desktop:
- macOS: Claude → Quit Claude (or Cmd + Q)
- Windows: File → Exit
- Linux: File → Quit
Restart Claude Desktop

Claude Desktop only reads the config file on startup. A full restart is required.

Verify NOFire AI is Available

In a new conversation with Claude, you should see MCP tools available.Test the connection:Ask Claude:

Can you use NOFire AI to discover services in my cluster?

Or:

Using NOFire AI, what's the deployment risk for changes to payment-service?

Expected behavior:

Claude will indicate it’s using NOFire AI tools
You’ll see results from your production environment
If there’s an error, see troubleshooting below

Claude Desktop Settings Tips

Check MCP Status

Claude shows available tools at the bottom of the chat interface
Look for indicators that NOFire AI tools are loaded
If not visible, check the developer console for errors

Enable Developer Tools To debug issues:

Open Claude Desktop Settings
Look for “Developer” or “Advanced” options
Enable developer tools/console
Check for any MCP-related errors

File Permissions Ensure the config file has proper permissions:

# macOS/Linux - make sure you own the file
chmod 644 ~/Library/Application\ Support/Claude/claude_desktop_config.json

Available Tools

Once configured, these tools are available to your AI assistant:

Tool	Use when
`nofire_search_entities`	Discovering what infrastructure exists or verifying entity names
`nofire_get_entity_dependencies`	Understanding upstream/downstream service topology
`nofire_get_entity_changes`	Checking what changed recently (infra changes + VCS activity)
`nofire_get_entity_metrics`	Finding available Prometheus metrics and PromQL queries
`nofire_assess_deployment_risk`	Scoring risk before deploying changes
`nofire_analyze_blast_radius`	Understanding cascading failure impact
`nofire_find_related_incidents`	Checking incident history and root cause patterns
`nofire_get_cluster_summary`	Getting cluster-wide health overview
`nofire_get_recent_deploys`	Seeing cluster-wide deploy + VCS timeline

Shift-Left / Proactive Reliability

Assess Deployment Risk

Score deployment risk for a service before merging:Example:

What's the deployment risk for payment-service in prod?

Uses nofire_assess_deployment_risk to calculate a weighted risk score (0-100) based on blast radius, dependency depth, incident history, and recent change velocity.Risk levels: LOW (0-39), MEDIUM (40-59), HIGH (60-79), CRITICAL (80-100).

Analyze Blast Radius

Understand cascading impact of service failures:Example:

What's the blast radius if payment-service fails?

Uses nofire_analyze_blast_radius to traverse the dependency graph and show direct + transitive impact.

Cluster Summary

Get a cluster-wide health overview when you don’t know where to start:Example:

Give me a summary of the prod cluster in the last 6 hours

Uses nofire_get_cluster_summary to show entity counts, top problematic services, and recent alert investigations.

Incident Response & RCA

Discover Entities

Find services, pods, deployments in your cluster:Example:

Show me all services with "payment" in the name

Uses nofire_search_entities with partial name matching.

Get Entity Changes + VCS Activity

View recent infrastructure changes and correlated VCS activity (commits, PRs):Example:

What changed in payment-service in the last 6 hours?

Uses nofire_get_entity_changes which returns deployments, config updates, scaling events, plus merged PRs and pushes in the same time window.

Recent Deploys Timeline

See cluster-wide deploy and change timeline:Example:

Show me all deploys in prod in the last 24 hours

Uses nofire_get_recent_deploys to show a chronological timeline of infra changes + VCS events across the cluster.

Check incident history and root cause patterns:Example:

Has payment-service had incidents in the last 30 days?

Uses nofire_find_related_incidents with confidence filtering (only high-confidence root causes).

Get Dependencies

Explore service dependencies:Example:

What services does payment-service depend on?

Uses nofire_get_entity_dependencies to show upstream and downstream connections.

Usage Examples

Pre-Merge Risk Assessment

Scenario: You’ve modified payment processing code and want to assess risk before creating a PR. In Cursor:

I've modified these files:
- src/services/payment/stripe-client.ts
- src/services/payment/processor.ts
- src/api/payment-routes.ts

Can you assess the deployment risk using NOFire AI?

Cursor Response:

I've analyzed your changes using NOFire AI:

Affected Services: 1 (payment-service)

Risk Assessment:
  Overall Risk: 0.82 (HIGH)
  
  Risk Breakdown:
    - Blast Radius: 0.85 (15 services affected)
    - Payment processing is on critical path
    - Dependency depth: 2 (mid-level service)
    - Recent stability: 0.70
  
  Deployment Strategy:
    ⚠️  HIGH RISK - Staged deployment mandatory
    
    1. Deploy to staging environment first
    2. Run full payment test suite
    3. Deploy to production with canary (5% traffic)
    4. Monitor for 2 hours before full rollout
    5. Notify #payments and #platform teams
    
  Critical Services in Blast Radius:
    - api-gateway (entry point)
    - billing-service (financial impact)
    - refund-service (payment flow)
    
  Recommendation: Schedule deployment during low-traffic window
  with team available for monitoring.

Onboarding New Engineers

Scenario: New team member needs to understand the production architecture. In Cursor:

I'm new to this codebase. Can you use NOFire AI to show me:
1. What services we have in production
2. How the payment flow works (service dependencies)

Cursor Response:

I've queried NOFire AI about your production environment:

Services in Production (showing payment-related):
  - api-gateway (entry point for all traffic)
  - payment-service (core payment processing)
  - billing-service (invoicing and subscriptions)
  - stripe-integration-service (payment provider)
  - notification-service (payment confirmations)
  - audit-service (transaction logging)

Payment Flow Dependencies:
  
  api-gateway
    ↓ calls
  payment-service
    ↓ depends on
    ├─ stripe-integration-service (payment processing)
    ├─ billing-service (invoice creation)
    ├─ notification-service (customer emails)
    └─ audit-service (compliance logging)

Critical Services to be careful with:
  - payment-service: 15 services depend on this
  - api-gateway: Entry point, affects all traffic
  
Would you like me to explain what each service does or show
recent changes to any of them?

Investigating Production Behavior

Scenario: A service has been flaky, you want to understand what changed. In Claude Desktop:

Using NOFire AI, what changes happened to user-service 
in the last 24 hours?

Claude Response:

I've queried NOFire AI for recent changes to user-service:

Recent Changes (last 24 hours):
  
  1. Deployment (14 hours ago)
     - Image: user-service:v2.1.4 → v2.1.5
     - Type: Rolling update
     - Status: Completed
  
  2. Configuration Change (8 hours ago)
     - ConfigMap updated: database connection pool
     - MAX_POOL_SIZE: 20 → 50
  
  3. Pod Restart (3 hours ago)
     - 2 pods restarted due to OOMKilled
     - Memory limit hit
  
  4. Scaling Event (1 hour ago)
     - Replicas: 3 → 5
     - Reason: High CPU usage

Potential Issues:
  - Memory limit may be too low after config change
  - Connection pool increase might be causing memory pressure
  - Recent scaling event suggests ongoing performance issues

Would you like me to analyze these changes for root cause?

Best Practices

Check Risk Before Every Merge

Make it a habit to check deployment risk before creating or approving PRs. Takes 10 seconds, prevents hours of incident response.

Use NOFire AI for Onboarding

New team members can ask NOFire AI about production:

“What services do we have in production?”
“How does auth-service connect to user-service?”
“What changed in payment-service this week?”

Makes production knowledge accessible without tribal knowledge bottlenecks.

Include Context in Queries

Provide context about what you’re doing:❌ “Check risk” ✅ “I’m updating payment API error handling. What’s the deployment risk?”❌ “What changed?” ✅ “What changed in auth-service in the last 24 hours?”

Use for Incident Investigation

When something breaks, ask NOFire AI:

“What changed in [service] before the incident?”
“Analyze [service] changes from 2 hours ago”
“What services depend on [broken-service]?”

Speeds up incident response by making telemetry data queryable.

Troubleshooting

MCP Server Not Responding

Symptoms: Commands timeout or show connection errorsFor Cursor:

Check the MCP status icon in the bottom status bar
Verify JSON syntax in ~/.cursor/mcp.json is valid
Ensure you fully quit and restarted Cursor (not just reload)
Check API token is correct and active in NOFire AI dashboard
Test connectivity: curl https://mcp.nofire.ai/mcp/health
Look for errors in Cursor’s developer console (Help → Toggle Developer Tools)

For Claude Desktop:

Validate JSON syntax in claude_desktop_config.json
Ensure file path is correct for your OS
Check file permissions (should be readable)
Verify API token is active in dashboard
Check Claude’s developer console for error messages
Try removing and re-adding the configuration

JSON Syntax Errors

Symptoms: MCP servers not loading, IDE shows config errorsCommon mistakes:❌ Missing comma between servers:

{
  "mcpServers": {
    "server1": {...}  // Missing comma here!
    "NOFireAI": {...}
  }
}

✅ Correct:

{
  "mcpServers": {
    "server1": {...},
    "NOFireAI": {...}
  }
}

Validate your JSON:

Use an online JSON validator
Use command line: python3 -m json.tool yourfile.json
Most code editors have built-in JSON validation

API Token Issues

Symptoms: “Invalid API token” or “Unauthorized” errorsChecklist:

Copy the API token correctly (no extra spaces or line breaks)
Ensure you copied the MCP key (not agent key)
Verify key is active in NOFire AI dashboard
Check key hasn’t been deleted or deactivated
Make sure quotes are proper JSON double quotes ""

Test connectivity (no auth needed):

curl https://mcp.nofire.ai/mcp/health

Test your API token:

curl -X POST https://mcp.nofire.ai/mcp \
  -H "Authorization: Bearer your-key-here" \
  -H "Content-Type: application/json"

If the health check works but auth fails, regenerate your API token in the dashboard.

Configuration File Not Found

Symptoms: Can’t find mcp.json or claude_desktop_config.jsonSolutions:For Cursor: Create the directory and file if they don’t exist:

# macOS/Linux
mkdir -p ~/.cursor
touch ~/.cursor/mcp.json
echo '{"mcpServers":{}}' > ~/.cursor/mcp.json

# Windows (PowerShell)
New-Item -Path "$env:APPDATA\.cursor" -ItemType Directory -Force
'{"mcpServers":{}}' | Out-File "$env:APPDATA\.cursor\mcp.json"

For Claude Desktop:

# macOS
mkdir -p ~/Library/Application\ Support/Claude
echo '{"mcpServers":{}}' > ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Linux
mkdir -p ~/.config/Claude
echo '{"mcpServers":{}}' > ~/.config/Claude/claude_desktop_config.json

# Windows (PowerShell)
New-Item -Path "$env:APPDATA\Claude" -ItemType Directory -Force
'{"mcpServers":{}}' | Out-File "$env:APPDATA\Claude\claude_desktop_config.json"

No Services Found

Symptoms: “No entities found” or empty resultsSolutions:

Ensure your data sources are connected:
- If using observability stack: Verify Grafana/Prometheus/Loki connections are active
- If using Kubernetes agent: Ensure agent is deployed and running
Wait 5-10 minutes for initial data collection and knowledge graph building
If using agent: Verify it has correct cluster access
Check connection logs for errors in the NOFire AI dashboard

Inaccurate File Mapping

Symptoms: Files mapped to wrong services or not mapped at allSolutions:

Use repository-qualified paths (include repo name)
Ensure service names match deployment labels
Check if service was recently deployed (< 1 hour)
Fuzzy matching requires similar naming between files and services

API Token Permission Denied

Symptoms: “MCP keys are read-only” errorIssue: You’re trying to perform a write operation with an MCP keySolution: MCP keys are intentionally read-only for security. Write operations (like creating new services) require agent keys through the dashboard.

Security Considerations

MCP keys are read-only by designMCP API tokens can only query and analyze data from NOFire AI. They cannot:

Modify your production infrastructure
Trigger deployments or rollbacks
Create or delete Kubernetes resources
Change system configurations
Execute commands in your clusters

This ensures your production environment remains completely safe even if an MCP key is compromised. The Kubernetes agent that observes your infrastructure state runs separately with its own authentication.

Learn more about API token types and permissions.

Bonus: Automate with AGENTS.md

Make NOFire AI checks automatic by adding them to your AGENTS.md file. This ensures AI coding agents always use NOFire AI for deployment risk and operational knowledge. Create or update AGENTS.md in your repository root:

# AGENTS.md

## NOFire AI MCP Integration

This project uses NOFire AI for deployment risk assessment and production knowledge.
NOFire AI MCP server is available in your IDE.

## When to use NOFire AI

**Automatically use NOFire AI in these scenarios:**

### Before Deployment (Shift-Left)
1. **Before completing any task** - Always assess deployment risk
2. **When modifying services** - Understand which production services are affected
3. **Before suggesting a merge** - Verify it's safe to deploy
4. **On refactoring** - Check blast radius and dependency impact

### Production Knowledge (Anytime)
5. **When user asks about production** - Answer with real production data
6. **During incident investigation** - Find what changed recently
7. **For onboarding new engineers** - Help understand production architecture
8. **When debugging** - Query service dependencies and recent changes

## Required Pre-Merge Workflow

Before marking any task complete or suggesting a merge:

1. Run tests
2. **Discover affected entities:**
   ```
   nofire_search_entities(name="payment", cluster="prod")
   ```
3. **Assess deployment risk:**
   ```
   nofire_assess_deployment_risk(entity_name="payment-service", cluster="prod")
   ```
4. **Show the user** the risk score and recommendations
5. **For HIGH/CRITICAL risk**, check blast radius:
   ```
   nofire_analyze_blast_radius(entity_name="payment-service", cluster="prod")
   ```

## Risk Score Interpretation

- **CRITICAL (80-100)**: Peer review + feature flags required. Never deploy Fridays.
- **HIGH (60-79)**: Staged rollout, deploy during business hours with team available.
- **MEDIUM (40-59)**: Consider canary rollout (10% → 50% → 100%).
- **LOW (0-39)**: Standard deployment is safe.

## Available NOFire AI MCP Tools

| Tool | Use when |
|------|----------|
| `nofire_search_entities` | Discovering what infrastructure exists or verifying entity names |
| `nofire_get_entity_dependencies` | Understanding upstream/downstream service topology |
| `nofire_get_entity_changes` | Checking what changed recently (infra + VCS activity) |
| `nofire_get_entity_metrics` | Finding available Prometheus metrics and PromQL queries |
| `nofire_assess_deployment_risk` | Scoring risk before deploying changes |
| `nofire_analyze_blast_radius` | Understanding cascading failure impact |
| `nofire_find_related_incidents` | Checking incident history and root cause patterns |
| `nofire_get_cluster_summary` | Getting cluster-wide health overview (start here if unsure) |
| `nofire_get_recent_deploys` | Seeing cluster-wide deploy + VCS timeline |

## Connecting Code to Production

1. Use `nofire_get_entity_changes` or `nofire_get_recent_deploys` to find commit SHAs and PR references
2. Search the codebase for those commits to understand the code diff
3. Cross-reference with `nofire_find_related_incidents` to check if similar changes caused issues before

## When NOT to Use NOFire AI

Skip NOFire AI for:
- Documentation-only changes (*.md files)
- Test-only changes (no production code modified)
- Local development config (non-production)
- README updates, comment changes

## Critical Rule

**Always call NOFire AI before suggesting a merge that modifies production code.**

Why this works:

Works with Cursor, GitHub Copilot, Jules, Aider, and most AI coding agents
Makes shift-left and operational knowledge automatic
Entire team follows same safety checks and has access to production knowledge

What’s Next?

API Tokens Management

Learn how to generate and manage MCP API tokens

Proactive Reliability

Deep dive into shift-left reliability features

Security

Understand our security-first approach

AGENTS.md Guide

Learn more about the AGENTS.md format

Get Started

Skills

Platform Features

Setup & Integrations

Security

Getting Started with MCP

What is MCP Integration?

Supported IDEs

Cursor

Claude Desktop

MCP-Compatible Tools

Prerequisites

Installation

Cursor Setup

Cursor Settings Tips

Claude Desktop Setup

Claude Desktop Settings Tips

Available Tools

Shift-Left / Proactive Reliability

Incident Response & RCA

Usage Examples

Pre-Merge Risk Assessment

Onboarding New Engineers

Investigating Production Behavior

Best Practices

Troubleshooting

Security Considerations

Bonus: Automate with AGENTS.md

What’s Next?

API Tokens Management

Proactive Reliability

Security

AGENTS.md Guide

​What is MCP Integration?

​Supported IDEs

Cursor

Claude Desktop

MCP-Compatible Tools

​Prerequisites

​Installation

​Cursor Setup

​Cursor Settings Tips

​Claude Desktop Setup

​Claude Desktop Settings Tips

​Available Tools

​Shift-Left / Proactive Reliability

​Incident Response & RCA

​Usage Examples

​Pre-Merge Risk Assessment

​Onboarding New Engineers

​Investigating Production Behavior

​Best Practices

​Troubleshooting

​Security Considerations

​Bonus: Automate with AGENTS.md

​What’s Next?

API Tokens Management

Proactive Reliability

Security

AGENTS.md Guide

What is MCP Integration?

Supported IDEs

Prerequisites

Installation

Cursor Setup

Cursor Settings Tips

Claude Desktop Setup

Claude Desktop Settings Tips

Available Tools

Shift-Left / Proactive Reliability

Incident Response & RCA

Usage Examples

Pre-Merge Risk Assessment

Onboarding New Engineers

Investigating Production Behavior

Best Practices

Troubleshooting

Security Considerations

Bonus: Automate with AGENTS.md

What’s Next?