@neubirdai/mcp-server-neubird

v3.1.0

Published

10 days ago

MCP Server for NeuBird AI-powered production operations

0High
0Medium
0Low

mcp model-context-protocol neubird-falcon neubird incident-investigation rca root-cause-analysis cloud-monitoring observability cursor claude ai-agent

NeuBird MCP Server

Model Context Protocol (MCP) server that brings NeuBird's AI-powered incident investigation and root cause analysis directly into your AI coding environment.

What is NeuBird MCP?

NeuBird MCP Server enables AI assistants (like Claude, Cursor, GitHub Copilot) to interact with NeuBird's AI SRE platform for autonomous incident investigation and root cause analysis.

Stop context-switching. Investigate incidents without leaving your IDE.

✨ Key Features

🌊 Real-Time Progress — Stream live investigation progress with phase tracking and timing
🔍 AI-Powered RCA — Automated root cause analysis with corrective actions (including bash scripts)
🎯 43 Tools — Complete API for projects, connections, investigations, instructions, and analytics
📊 Time Savings — Track MTTR and time saved vs manual investigation
🧪 Test Instructions — Unique workflow to test investigation instructions before deployment
🔌 Multi-Cloud — Connect AWS, Azure, GCP, Datadog, PagerDuty, and more
🤖 Any MCP Client — Works with Claude Desktop, Claude Code, Cursor, GitHub Copilot, OpenAI Codex, and more

🚀 Quick Start

Installation

# Install globally
npm install -g @neubirdai/mcp-server-neubird

# Or use directly with npx (no installation)
npx @neubirdai/mcp-server-neubird

Configuration

Add to your MCP client configuration:

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "neubird": {
      "command": "npx",
      "args": ["-y", "@neubirdai/mcp-server-neubird@latest"],
      "env": {
        "NEUBIRD_EMAIL": "[email protected]",
        "NEUBIRD_PASSWORD": "your-password",
        "NEUBIRD_BASE_URL": "https://<your-deployment>.app.neubird.ai/api"
      }
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "neubird": {
      "command": "npx",
      "args": ["-y", "@neubirdai/mcp-server-neubird@latest"],
      "env": {
        "NEUBIRD_EMAIL": "[email protected]",
        "NEUBIRD_PASSWORD": "your-password",
        "NEUBIRD_BASE_URL": "https://<your-deployment>.app.neubird.ai/api"
      }
    }
  }
}

Restart your MCP client and start investigating.

Legacy env var support: HAWKEYE_EMAIL, HAWKEYE_PASSWORD, and HAWKEYE_BASE_URL are also accepted for backward compatibility. NEUBIRD_* takes precedence when both are set.

📖 Documentation

Full documentation is available at https://docs.neubird.ai/mcp/overview/.

Installation Guide — Detailed setup for all supported MCP clients
Quick Start — 5-minute getting-started guide
Complete Onboarding — End-to-end setup walkthrough
Tool Reference — All 43 tools documented
Examples — Real-world usage scenarios
Troubleshooting — Common issues and fixes

🎯 Example Usage

You: "Show me uninvestigated alerts from the last 24 hours"

Claude: *Lists uninvestigated incidents*

You: "Investigate the first one"

Claude: *Runs investigation and returns comprehensive RCA including:*
- Root cause analysis
- Timeline of events
- Corrective actions with bash scripts
- Preventive measures
- Business impact
- Time saved (e.g., "45 minutes saved: Manual 50min → NeuBird 5min")

You: "Why did this happen? Has it happened before?"

Claude: *Uses follow-up investigation to provide deeper analysis*

🌊 Real-Time Streaming Progress

NeuBird MCP streams real-time investigation progress so you see exactly what's happening instead of waiting with no feedback:

You: "Investigate high CPU usage in production"

Claude:
🔧 Preparing telemetry sources [2s]
📚 Loading investigation context [3s]
🔍 Classifying datasources (Step 1) [18s]
🎯 Fine-tuning datasources [26s]
🔎 Consulting telemetry (Query 7) [1m 6s]
🧠 Analyzing telemetry data (Analysis 12) [1m 13s]
📝 Summarizing results [1m 29s]

Investigation completed! Here's what I found...

Benefits:

✅ See exactly what NeuBird is doing in real time
✅ Know how long each phase takes
✅ Track query and analysis counts
✅ Estimated progress percentage (0–100%)
✅ Complete progress log for debugging
✅ Enabled by default (opt out with stream_progress: false)

Supported Tools:

neubird_create_manual_investigation — Stream progress for custom investigations
neubird_investigate_alert — Stream progress when investigating alerts

Tool prefix: Tools are prefixed with neubird_ by default. Set NEUBIRD_TOOL_PREFIX=hawkeye to use the legacy hawkeye_* prefix for backward compatibility.

🛠️ Tool Categories

| Category | Tools | Description | |----------|-------|-------------| | Projects | 9 | Create and manage NeuBird projects | | Investigations | 14 | Investigate alerts, get RCA, ask follow-ups | | Connections | 7 | Connect AWS, Azure, GCP, Datadog, PagerDuty, etc. | | Instructions | 6 | Create, test, and manage investigation instructions | | Analytics | 3 | MTTR, time saved, quality scores, incident statistics | | Discovery | 2 | Explore available resources and data sources | | Config | 1 | Switch between NeuBird instances | | Help | 1 | Interactive guidance system |

Total: 43 tools

See the Tool Reference for complete documentation.

🧪 Unique Features

Instruction Testing Workflow

NeuBird MCP lets you test instructions before deploying them:

Apply an instruction to a past investigation
Rerun that investigation with the new instruction
Compare the new RCA with the original
Only add to the project if it improves results

This prevents bad instructions from affecting all your investigations.

🤝 Supported AI Clients

Works with any MCP-compatible client:

✅ Claude Desktop (macOS, Windows)
✅ Claude Code (CLI — macOS, Windows, Linux)
✅ Cursor (macOS, Windows, Linux)
✅ GitHub Copilot (VS Code)
✅ OpenAI Codex
✅ Any other MCP-compatible client

🔧 Configuration Options

Transport Modes

NeuBird MCP Server supports two transport modes:

| Mode | Use Case | Authentication | |------|----------|----------------| | Stdio (default) | Local npm/npx usage with MCP clients | Environment variables | | HTTP/SSE | Kubernetes deployment, multi-user | Headers (Bearer token or password) |

Stdio Transport (Default)

For use with Claude Desktop, Cursor, and other MCP clients:

Required Environment Variables

| Variable | Description | |----------|-------------| | NEUBIRD_EMAIL | Your NeuBird account email | | NEUBIRD_PASSWORD | Your NeuBird account password | | NEUBIRD_BASE_URL | NeuBird API endpoint (e.g., https://<your-deployment>.app.neubird.ai/api) |

Optional Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | NEUBIRD_DEFAULT_PROJECT_UUID | None | Default project UUID | | NEUBIRD_LOG_LEVEL | info | Log level (debug, info, warn, error) | | NEUBIRD_MAX_POLL_ATTEMPTS | 30 | Max polling attempts | | NEUBIRD_POLL_INTERVAL_MS | 2000 | Polling interval (ms) | | NEUBIRD_TOOL_PREFIX | neubird | Prefix for tool names (set to hawkeye for legacy) |

Legacy HAWKEYE_* env vars are also accepted for backward compatibility; NEUBIRD_* takes precedence when both are set.

HTTP/SSE Transport (Kubernetes Deployment)

For multi-user deployments, use the HTTP/SSE transport with per-request authentication.

Server Configuration

| Variable | Description | |----------|-------------| | TRANSPORT_MODE | Set to http to enable HTTP/SSE transport | | HTTP_PORT | HTTP server port (default: 3000) | | NEUBIRD_BASE_URL | NeuBird API endpoint | | CONFIGDB_URI | PostgreSQL connection string | | CONFIGDB_USER | PostgreSQL username | | CONFIGDB_PASSWORD | PostgreSQL password |

Client Authentication

The HTTP/SSE transport supports two authentication methods:

1. Bearer Token (Auth0/OAuth) — Recommended

Authorization: Bearer <auth0_access_token>

2. Password Credentials

X-NeuBird-Email: [email protected]
X-NeuBird-Password: your-password

Legacy X-Hawkeye-Email / X-Hawkeye-Password headers are also accepted.

MCP Client Configuration (HTTP/SSE)

With Bearer Token:

{
  "mcpServers": {
    "neubird": {
      "type": "http",
      "url": "https://<your-deployment>.app.neubird.ai/mcp",
      "headers": {
        "Authorization": "Bearer <auth0_access_token>"
      }
    }
  }
}

With Password Credentials:

{
  "mcpServers": {
    "neubird": {
      "type": "http",
      "url": "https://<your-deployment>.app.neubird.ai/mcp",
      "headers": {
        "X-NeuBird-Email": "[email protected]",
        "X-NeuBird-Password": "your-password"
      }
    }
  }
}

📝 Changelog

See CHANGELOG.md for version history and release notes.

🐛 Troubleshooting

For detailed troubleshooting, see the Troubleshooting Guide.

Common issues:

Authentication errors: Verify NEUBIRD_EMAIL, NEUBIRD_PASSWORD, and NEUBIRD_BASE_URL
Tools not showing: Restart MCP client completely
Investigation timeout: Check connection sync status, increase NEUBIRD_MAX_POLL_ATTEMPTS

🤝 Support

Documentation: https://docs.neubird.ai/mcp/overview/
Email: [email protected]
Website: https://neubird.ai

📄 License

MIT License — see LICENSE for details.

🙏 Acknowledgments

Built with:

@modelcontextprotocol/sdk — MCP Protocol implementation
TypeScript — Type-safe JavaScript
Axios — HTTP client
Zod — Runtime validation

Made with ❤️ by NeuBird AI | Documentation | npm