Hawkeye MCP Server


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

What is Hawkeye MCP?

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

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

✨ Key Features

- 🌊 Real-Time Progress ✨ NEW in v2.0 - Stream live investigation progress with emojis and timing
- 🔍 AI-Powered RCA - Automated root cause analysis with corrective actions (including bash scripts)
- 🎯 42 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, Continue, and more

🚀 Quick Start

$3

``bash


Install globally

npm install -g hawkeye-mcp-server

Or use directly with npx (no installation)

npx hawkeye-mcp-server
`

$3

Add to your MCP client configuration:

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

`json
{
"mcpServers": {
"hawkeye": {
"command": "npx",
"args": ["-y", "hawkeye-mcp-server"],
"env": {
"HAWKEYE_EMAIL": "your-email@company.com",
"HAWKEYE_PASSWORD": "your-password",
"HAWKEYE_BASE_URL": "https://app.neubird.ai/api"
}
}
}
}
`

Cursor (~/.cursor/mcp.json):

`json
{
"mcpServers": {
"hawkeye": {
"command": "npx",
"args": ["-y", "hawkeye-mcp-server"],
"env": {
"HAWKEYE_EMAIL": "your-email@company.com",
"HAWKEYE_PASSWORD": "your-password",
"HAWKEYE_BASE_URL": "https://app.neubird.ai/api"
}
}
}
}
`

Restart your MCP client and start investigating!

📖 Documentation

Complete documentation is available at: https://neubirdai.github.io/hawkeye-mcp-docs

- Installation Guide - Detailed setup for all platforms
- Quick Start - 5-minute getting started guide
- Complete Onboarding - End-to-end setup guide
- Tool Reference - All 39 tools documented
- Examples - Real-world usage examples
- Troubleshooting - Common issues and solutions

🎯 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 → Hawkeye 5min")

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

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

🌊 Real-Time Streaming Progress (NEW in v2.0)

No more waiting 5-10 minutes with no feedback! Hawkeye MCP now streams real-time investigation progress:

`
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 Hawkeye 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 (can opt-out with stream_progress: false)

Supported Tools:
- hawkeye_create_manual_investigation - Stream progress for custom investigations
- hawkeye_investigate_alert - Stream progress when investigating alerts

🛠️ Tool Categories

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

Total: 42 tools

See the Tool Reference for complete documentation.

🧪 Unique Features

$3

Hawkeye MCP is the only incident investigation tool that lets you test instructions before deploying them:

1. Apply 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 project if it improves results

This prevents bad instructions from affecting all your investigations.

Learn more: Testing Instructions Guide

🤝 Supported AI Clients

Works with any MCP-compatible client:

- ✅ Claude Desktop (macOS, Windows)
- ✅ Claude Code (CLI - macOS, Windows, Linux)
- ✅ Cursor (macOS, Windows, Linux)
- ✅ Continue (VS Code extension)
- ✅ Any other MCP-compatible client

🔧 Configuration Options

$3

Hawkeye MCP Server supports two transport modes:

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

$3

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

#### Required Environment Variables

| Variable | Description |
|----------|-------------|
| HAWKEYE_EMAIL | Your Hawkeye account email |
| HAWKEYE_PASSWORD | Your Hawkeye account password |
| HAWKEYE_BASE_URL | Hawkeye API endpoint (e.g., https://app.neubird.ai/api) |

#### Optional Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| HAWKEYE_DEFAULT_PROJECT_UUID | None | Default project UUID |
| HAWKEYE_LOG_LEVEL | info | Log level (debug, info, warn, error) |
| HAWKEYE_MAX_POLL_ATTEMPTS | 30 | Max polling attempts |
| HAWKEYE_POLL_INTERVAL_MS | 2000 | Polling interval (ms) |

$3

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) |
| HAWKEYE_BASE_URL | Hawkeye 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
`

2. Password Credentials (Legacy)
`
X-Hawkeye-Email: user@example.com
X-Hawkeye-Password: your-password
`

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

With Bearer Token:
`json
{
"mcpServers": {
"hawkeye": {
"url": "https://hawkeye-mcp.example.com/mcp",
"headers": {
"Authorization": "Bearer "
}
}
}
}
`

With Password Credentials:
`json
{
"mcpServers": {
"hawkeye": {
"url": "https://hawkeye-mcp.example.com/mcp",
"headers": {
"X-Hawkeye-Email": "user@example.com",
"X-Hawkeye-Password": "your-password"
}
}
}
}
`

#### Obtaining an Auth0 Token

Clients can obtain Auth0 tokens by:
1. Via Hawkeye UI: Login to hawkeye-ui, extract token from localStorage (access_token)
2. Via Auth0 SDK: Use Auth0 SDK to perform OAuth flow directly

👥 Contributing

We welcome contributions from NeuBird team members! This section is for internal developers.

$3

1. Clone the repository:
`bash
git clone https://github.com/neubird/hawkeye-mcp.git
cd hawkeye-mcp
`

2. Install dependencies:
`bash
npm install
`

3. Set up environment variables:
`bash
cp .env.example .env
# Edit .env with your Hawkeye credentials
`

4. Build the project:
`bash
npm run build
`

5. Run in development mode:
`bash
npm run dev
`

$3

`
hawkeye-mcp/
├── src/
│ ├── index.ts # Main MCP server entry point
│ ├── hawkeye-client.ts # Hawkeye API client
│ ├── tools/ # MCP tool implementations
│ ├── utils/ # Utility functions
│ └── types/ # TypeScript type definitions
├── build/ # Compiled JavaScript (gitignored)
├── tests/ # Test files
├── package.json
├── tsconfig.json
└── README.md
`

$3

1. Create a feature branch:
`bash
git checkout -b feature/your-feature-name
`

2. Make your changes:
- Add new tools in src/tools/
- Update types in src/types/
- Add tests for new functionality
- Update CHANGELOG.md

3. Test your changes:
`bash
# Build
npm run build

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node build/index.js

# Or test with your MCP client
`

4. Commit your changes:
`bash
git add .
git commit -m "feat: add new feature"
`

Commit message format:
- feat: New features
- fix: Bug fixes
- docs: Documentation changes
- refactor: Code refactoring
- test: Test additions/changes
- chore: Maintenance tasks

5. Push and create PR:
`bash
git push origin feature/your-feature-name
`

Create a pull request on GitHub with:
- Clear description of changes
- Testing steps performed
- Any breaking changes noted

$3

Hawkeye MCP includes comprehensive testing for unit, integration, and end-to-end validation.

#### Test Organization

`
tests/
├── README.md # Complete testing guide
├── unit/ # Unit tests for individual tools
├── integration/ # Integration tests (planned)
└── e2e/ # End-to-end testing workflows
├── test-connections.md # Test credentials and setup
└── test-prompt.md # Complete onboarding workflow
`

#### Running Tests

Unit Tests:
`bash


Build first

npm run build

Run authentication test

node tests/unit/test-auth.js

Run connection tools test

node tests/unit/test-connection-tools.mjs

Run manual investigation test (requires prompt argument)

./tests/unit/test-manual-investigation.mjs "Investigate high CPU in api-gateway"

Test with MCP Inspector (interactive)

npx @modelcontextprotocol/inspector node build/index.js
`

End-to-End Tests:

E2E tests are designed for AI coding agents (Claude Desktop/Code):

1. Open your AI coding agent
2. Navigate to tests/e2e/test-prompt.md
3. Copy the test workflow
4. Paste into your AI agent
5. Let it execute each phase
6. Verify outcomes match expectations

Test Resources:

- tests/README.md - Complete testing guide with best practices
- tests/e2e/test-connections.md - Test environment credentials
- tests/e2e/test-prompt.md - Complete E2E onboarding workflow

#### Test Types

| Type | Location | Purpose | Duration |
|------|----------|---------|----------|
| Unit | tests/unit/ | Test individual tools in isolation | Seconds |
| Integration | tests/integration/ | Test tools working together | Minutes |
| E2E | tests/e2e/ | Test complete user workflows with AI agent | 45-90 min |

#### Quick Validation

Before submitting a PR, run these quick tests:

`bash


1. Build

npm run build

2. Test authentication

node tests/unit/test-auth.js

3. Test a few core tools

node tests/unit/test-connection-tools.mjs
./tests/unit/test-manual-investigation.mjs "Test investigation"

4. Verify tools load in MCP Inspector

npx @modelcontextprotocol/inspector node build/index.js
`

For comprehensive testing documentation, see tests/README.md.

$3

Building:
`bash
npm run build
`

Publishing to npm:
`bash


Update version in package.json

npm version patch # or minor, or major

Build

npm run build

Publish

npm publish
`

Note: Only maintainers can publish to npm.

$3

- Use TypeScript for all new code
- Follow existing code patterns
- Add JSDoc comments for public APIs
- Use meaningful variable names
- Keep functions focused and small

$3

1. Create tool file in src/tools/:
`typescript
export const toolName = {
name: 'hawkeye_tool_name',
description: 'Tool description',
inputSchema: {
type: 'object',
properties: {
// Define parameters
},
required: []
}
};
`

2. Implement handler in src/index.ts:
`typescript
case 'hawkeye_tool_name':
// Implementation
break;
`

3. Update documentation:
- Add to TOOLS_REFERENCE.md
- Update tool count in README.md
- Add examples if needed

4. Add tests:
- Create test file in tests/
- Test both success and error cases

$3

If your changes affect the documentation site:

1. Documentation lives in separate repo: neubirdai/hawkeye-mcp-docs
2. Create PR there with documentation updates
3. Link documentation PR in your code PR

$3

- Internal Slack: #hawkeye-mcp channel
- Code Questions: Ask in PR comments
- Design Discussions: Create GitHub issue

🐛 Troubleshooting

For detailed troubleshooting, see Troubleshooting Guide.

Common issues:

- Authentication errors: Verify HAWKEYE_EMAIL, HAWKEYE_PASSWORD, and HAWKEYE_BASE_URL
- Tools not showing: Restart MCP client completely
- Investigation timeout: Check connection sync status, increase HAWKEYE_MAX_POLL_ATTEMPTS`

📝 Changelog

See CHANGELOG.md for version history and release notes.

🤝 Support

- Documentation: https://neubirdai.github.io/hawkeye-mcp-docs
- Email: support@neubird.ai
- Website: https://neubird.ai

📄 License

MIT License - see LICENSE file for details.

Copyright © 2024 NeuBird AI

🙏 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