Installation

Let your AI agents interact with NeuBird’s AI-powered production operations platform using the Model Context Protocol.

Prerequisites

Before you begin, you’ll need:

Active NeuBird 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

NeuBird 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 a hosted MCP server and sign in with OAuth

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 NEUBIRD_EMAIL="your-email@company.com"
export NEUBIRD_PASSWORD="your-password"
export NEUBIRD_BASE_URL="https://<your-deployment-name>.app.neubird.ai/api"

Legacy env var support

The HAWKEYE_EMAIL, HAWKEYE_PASSWORD, and HAWKEYE_BASE_URL variables are also accepted for backward compatibility. NEUBIRD_* takes precedence when both are set.

Configure Your MCP Client

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

{
  "mcpServers": {
    "neubird": {
      "command": "npx",
      "args": ["-y", "@neubirdai/mcp-server-neubird@latest"],
      "env": {
        "NEUBIRD_EMAIL": "${env:NEUBIRD_EMAIL}",
        "NEUBIRD_PASSWORD": "${env:NEUBIRD_PASSWORD}",
        "NEUBIRD_BASE_URL": "${env:NEUBIRD_BASE_URL}"
      }
    }
  }
}

View Cursor MCP documentation →

Use the claude mcp add command for quick setup:

claude mcp add neubird -- npx -y @neubirdai/mcp-server-neubird@latest

This uses the environment variables you set earlier (NEUBIRD_EMAIL, NEUBIRD_PASSWORD, and NEUBIRD_BASE_URL).

View Claude Code MCP documentation →

Alternative: JSON Configuration

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

{
  "mcpServers": {
    "neubird": {
      "command": "npx",
      "args": ["-y", "@neubirdai/mcp-server-neubird@latest"],
      "env": {
        "NEUBIRD_EMAIL": "${NEUBIRD_EMAIL}",
        "NEUBIRD_PASSWORD": "${NEUBIRD_PASSWORD}",
        "NEUBIRD_BASE_URL": "${NEUBIRD_BASE_URL}"
      }
    }
  }
}

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

{
  "servers": {
    "neubird": {
      "command": "npx",
      "args": ["-y", "@neubirdai/mcp-server-neubird@latest"],
      "env": {
        "NEUBIRD_EMAIL": "${NEUBIRD_EMAIL}",
        "NEUBIRD_PASSWORD": "${NEUBIRD_PASSWORD}",
        "NEUBIRD_BASE_URL": "${NEUBIRD_BASE_URL}"
      }
    }
  }
}

View GitHub Copilot MCP documentation →

Use the codex mcp add command for quick setup:

codex mcp add neubird \
  --env NEUBIRD_EMAIL=your-email@example.com \
  --env NEUBIRD_PASSWORD=your-password \
  --env NEUBIRD_BASE_URL=https://<your-deployment-name>.app.neubird.ai/api \
  -- npx -y @neubirdai/mcp-server-neubird@latest

View Codex MCP documentation →

Alternative: TOML Configuration

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

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

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

Option 2: Remote Server

Connect to a hosted NeuBird 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

Your MCP client must support HTTP transport with OAuth. Claude Code, Cursor, GitHub Copilot (VS Code), and OpenAI Codex all do.

Configure Your MCP Client

Add the server URL — no credential headers. On first connect, the client opens a browser window for you to sign in with your NeuBird login (including SSO and MFA, if your organization uses them).

Create .cursor/mcp.json in your project:

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

Cursor prompts you to sign in when the server is first enabled.

Use the claude mcp add command:

claude mcp add neubird \
  --transport http \
  https://<your-deployment-name>.app.neubird.ai/mcp

Then run /mcp inside Claude Code, select neubird, and choose Authenticate to sign in.

Alternative: JSON Configuration

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

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

Add .vscode/mcp.json to your workspace:

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

VS Code prompts you to sign in when the server starts.

Add the server, then sign in:

codex mcp add neubird \
  --url https://<your-deployment-name>.app.neubird.ai/mcp
codex mcp login neubird

View Codex MCP documentation →

Authentication

The remote server accepts only OAuth. X-NeuBird-Email / X-NeuBird-Password and the legacy X-Hawkeye-Email / X-Hawkeye-Password headers are rejected with 401 Unauthorized — remove them from your configuration and sign in as shown above. Email/password credentials work only with the local setup.

Next Steps

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