# NeuBird MCP Server

[![npm version](https://img.shields.io/npm/v/@neubirdai/mcp-server-neubird.svg)](https://www.npmjs.com/package/@neubirdai/mcp-server-neubird)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org/)

> Model Context Protocol (MCP) server that brings [NeuBird](https://neubird.ai)'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](https://neubird.ai) 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

```bash
# 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):

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

**Cursor** (`.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "neubird": {
      "command": "npx",
      "args": ["-y", "@neubirdai/mcp-server-neubird@latest"],
      "env": {
        "NEUBIRD_EMAIL": "your-email@company.com",
        "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/](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](https://docs.neubird.ai/mcp/overview/) for complete documentation.

## 🧪 Unique Features

### Instruction Testing Workflow

NeuBird MCP lets you **test instructions before deploying them**:

1. Apply an instruction to a past investigation
2. Rerun that investigation with the new instruction
3. Compare the new RCA with the original
4. 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: user@example.com
X-NeuBird-Password: your-password
```

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

#### MCP Client Configuration (HTTP/SSE)

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

**With Password Credentials:**
```json
{
  "mcpServers": {
    "neubird": {
      "type": "http",
      "url": "https://<your-deployment>.app.neubird.ai/mcp",
      "headers": {
        "X-NeuBird-Email": "user@example.com",
        "X-NeuBird-Password": "your-password"
      }
    }
  }
}
```

## 📝 Changelog

See [CHANGELOG.md](./CHANGELOG.md) for version history and release notes.

## 🐛 Troubleshooting

For detailed troubleshooting, see the [Troubleshooting Guide](https://docs.neubird.ai/mcp/overview/).

**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/](https://docs.neubird.ai/mcp/overview/)
- **Email:** support@neubird.ai
- **Website:** [https://neubird.ai](https://neubird.ai)

## 📄 License

MIT License — see [LICENSE](./LICENSE) for details.

Copyright © 2024–2026 NeuBird AI

## 🙏 Acknowledgments

Built with:
- [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol) — MCP Protocol implementation
- [TypeScript](https://www.typescriptlang.org/) — Type-safe JavaScript
- [Axios](https://axios-http.com/) — HTTP client
- [Zod](https://zod.dev/) — Runtime validation

---

**Made with ❤️ by [NeuBird AI](https://neubird.ai)** | [Documentation](https://docs.neubird.ai/mcp/overview/) | [npm](https://www.npmjs.com/package/@neubirdai/mcp-server-neubird)