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¶

The remote server supports two authentication methods:

Method	Header	Best For
Email/Password	`X-Hawkeye-Email` + `X-Hawkeye-Password`	Simple setup, most use cases
Bearer Token	`Authorization: Bearer <token>`	OAuth integrations, automated pipelines, token-based workflows

The examples above use email/password headers. To use bearer token authentication instead, replace the headers with a single Authorization header:

CursorClaude CodeGitHub CopilotOpenAI Codex

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

claude mcp add hawkeye \
  --transport http \
  https://<your-deployment-name>.app.neubird.ai/mcp \
  --header "Authorization: Bearer <your-token>"

Or in .mcp.json:

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

{
  "servers": {
    "hawkeye": {
      "type": "http",
      "url": "https://<your-deployment-name>.app.neubird.ai/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

codex mcp add hawkeye \
  --url https://<your-deployment-name>.app.neubird.ai/mcp \
  --header "Authorization: Bearer <your-token>"

Obtaining a Bearer Token¶

You can obtain a bearer token by calling the Hawkeye login API:

curl -s -X POST "https://<your-deployment-name>.app.neubird.ai/api/v1/user/login" \
  -H "Content-Type: application/json" \
  -d '{"email": "your@email.com", "password": "your-password"}' \
  | jq -r '.access_token'

The returned access_token is a JWT that can be used as the bearer token. The server validates it by calling the Auth0 userinfo endpoint (discovered from the token's issuer claim) and extracts your email for session tracking.

Token Refresh

If you send a refreshed token on a subsequent request, the server detects the change and re-validates automatically. You do not need to create a new session when your token is refreshed.

Next Steps¶

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