Installation¶

Let your AI agents interact with Hawkeye's autonomous incident investigation platform using the Model Context Protocol.

Prerequisites¶

Before you begin, you'll need:

✅ Active Hawkeye account - Contact NeuBird to get started
✅ Node.js 20+ - Download Node.js
✅ Connected data source - At least one cloud provider (AWS, Azure, GCP) or monitoring tool (Datadog, PagerDuty, etc.)
✅ MCP-compatible client - Claude Code, Cursor, or GitHub Copilot

Connection Options¶

Hawkeye MCP Server supports two connection modes:

Mode	Best For	Setup
Local (Default)	Individual developers, quick setup	Run MCP server locally via `npx`
Remote Server	Teams, enterprise deployments	Connect to hosted MCP server via `mcp-remote`

Option 1: Local Setup (Default)¶

Run the MCP server locally on your machine. This is the simplest setup for individual users.

Set Environment Variables¶

export HAWKEYE_EMAIL="your-email@company.com"
export HAWKEYE_PASSWORD="your-password"
export HAWKEYE_BASE_URL="https://<your-deployment-name>.app.neubird.ai/api"

Configure Your MCP Client¶

CursorClaude CodeGitHub CopilotOpenAI Codex

Create .cursor/mcp.json in your project with the following content:

{
  "mcpServers": {
    "hawkeye": {
      "command": "npx",
      "args": ["-y", "hawkeye-mcp-server@latest"],
      "env": {
        "HAWKEYE_EMAIL": "${env:HAWKEYE_EMAIL}",
        "HAWKEYE_PASSWORD": "${env:HAWKEYE_PASSWORD}",
        "HAWKEYE_BASE_URL": "${env:HAWKEYE_BASE_URL}"
      }
    }
  }
}

View Cursor MCP documentation →

Use the claude mcp add command for quick setup:

claude mcp add hawkeye -- npx -y hawkeye-mcp-server@latest

This uses the environment variables you set earlier (HAWKEYE_EMAIL, HAWKEYE_PASSWORD, and HAWKEYE_BASE_URL).

View Claude Code MCP documentation →

Alternative: JSON Configuration

You can also add to .mcp.json in your project directory:

{
  "mcpServers": {
    "hawkeye": {
      "command": "npx",
      "args": ["-y", "hawkeye-mcp-server@latest"],
      "env": {
        "HAWKEYE_EMAIL": "${HAWKEYE_EMAIL}",
        "HAWKEYE_PASSWORD": "${HAWKEYE_PASSWORD}",
        "HAWKEYE_BASE_URL": "${HAWKEYE_BASE_URL}"
      }
    }
  }
}

Add the .vscode/mcp.json file to your workspace:

{
  "servers": {
    "hawkeye": {
      "command": "npx",
      "args": ["-y", "hawkeye-mcp-server@latest"],
      "env": {
        "HAWKEYE_EMAIL": "${HAWKEYE_EMAIL}",
        "HAWKEYE_PASSWORD": "${HAWKEYE_PASSWORD}",
        "HAWKEYE_BASE_URL": "${HAWKEYE_BASE_URL}"
      }
    }
  }
}

View GitHub Copilot MCP documentation →

Use the codex mcp add command for quick setup:

codex mcp add hawkeye \
  --env HAWKEYE_EMAIL=your-email@example.com \
  --env HAWKEYE_PASSWORD=your-password \
  --env HAWKEYE_BASE_URL=https://<your-deployment-name>.app.neubird.ai/api \
  -- npx -y hawkeye-mcp-server@latest

View Codex MCP documentation →

Alternative: TOML Configuration

You can also add to ~/.codex/config.toml:

[mcp_servers.hawkeye]
command = "npx"
args = ["-y", "hawkeye-mcp-server@latest"]

# NOTE: No variable expansion supported — values must be literal
[mcp_servers.hawkeye.env]
HAWKEYE_EMAIL = "your-email@example.com"
HAWKEYE_PASSWORD = "your-password"
HAWKEYE_BASE_URL = "https://<your-deployment-name>.app.neubird.ai/api"

Option 2: Remote Server¶

Connect to a hosted Hawkeye MCP server. This is ideal for teams and enterprise deployments where the MCP server is managed centrally.

Remote Server URL

Your deployment URL follows the pattern https://<your-deployment-name>.app.neubird.ai/mcp. Contact your administrator if you don't know your deployment name.

Prerequisites¶

Most modern MCP clients support HTTP transport natively. If your client doesn't support HTTP transport, you can use mcp-remote as a proxy (installed automatically via npx).

Configure Your MCP Client¶

CursorClaude CodeGitHub CopilotOpenAI Codex

Create .cursor/mcp.json in your project:

{
  "mcpServers": {
    "hawkeye": {
      "type": "http",
      "url": "https://<your-deployment-name>.app.neubird.ai/mcp",
      "headers": {
        "X-Hawkeye-Email": "your@email.com",
        "X-Hawkeye-Password": "your-password"
      }
    }
  }
}

Alternative: Using mcp-remote

If your client doesn't support HTTP transport natively, you can use mcp-remote as a proxy:

{
  "mcpServers": {
    "hawkeye": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://<your-deployment-name>.app.neubird.ai/mcp",
        "--header",
        "X-Hawkeye-Email: your@email.com",
        "--header",
        "X-Hawkeye-Password: your-password"
      ]
    }
  }
}

Use the claude mcp add command for quick setup:

claude mcp add hawkeye \
  --transport http \
  https://<your-deployment-name>.app.neubird.ai/mcp \
  --header "X-Hawkeye-Email: your@email.com" \
  --header "X-Hawkeye-Password: your-password"

Alternative: JSON Configuration

You can also add to .mcp.json in your project directory:

{
  "mcpServers": {
    "hawkeye": {
      "type": "http",
      "url": "https://<your-deployment-name>.app.neubird.ai/mcp",
      "headers": {
        "X-Hawkeye-Email": "your@email.com",
        "X-Hawkeye-Password": "your-password"
      }
    }
  }
}

Add .vscode/mcp.json to your workspace:

{
  "servers": {
    "hawkeye": {
      "type": "http",
      "url": "https://<your-deployment-name>.app.neubird.ai/mcp",
      "headers": {
        "X-Hawkeye-Email": "your@email.com",
        "X-Hawkeye-Password": "your-password"
      }
    }
  }
}

Alternative: Using mcp-remote

If your client doesn't support HTTP transport natively, you can use mcp-remote as a proxy:

{
  "servers": {
    "hawkeye": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://<your-deployment-name>.app.neubird.ai/mcp",
        "--header",
        "X-Hawkeye-Email: your@email.com",
        "--header",
        "X-Hawkeye-Password: your-password"
      ]
    }
  }
}

Use the codex mcp add command with the --url flag for HTTP transport:

codex mcp add hawkeye \
  --url https://<your-deployment-name>.app.neubird.ai/mcp \
  --header "X-Hawkeye-Email: your@email.com" \
  --header "X-Hawkeye-Password: your-password"

View Codex MCP documentation →

Authentication Methods¶

Method	Header	Best For
Email/Password	`X-Hawkeye-Email` + `X-Hawkeye-Password`	Simple setup, most use cases
Bearer Token	`Authorization: Bearer <token>`	Automated scripts, CI/CD pipelines

Using Bearer Token Authentication

You can obtain a Bearer token by calling the login endpoint:

curl --location "https://<your-deployment-name>.app.neubird.ai/api/user/login" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "email": "your@email.com",
    "password": "your-password"
  }'

The response contains an access_token field. You can use this directly or embed the curl command in a subshell:

claude mcp add hawkeye \
  --transport http \
  https://<your-deployment-name>.app.neubird.ai/mcp \
  --header "Authorization: Bearer $(curl -s 'https://<your-deployment-name>.app.neubird.ai/api/user/login' \
    -H 'Content-Type: application/json' \
    -d '{\"email\":\"your@email.com\",\"password\":\"your-password\"}' | jq -r '.access_token')"

Next Steps¶

Once your client is configured, head over to Quick Start to verify connectivity with Hawkeye and run sample commands.