Hawkeye AI Bridge MCP Server

Runway at 10M tokens/month - Days until a hypothetical 10M/month context budget is exhausted, if every one of 50 daily search steps looked like this one. Longer bar, more runway.

• Broad grep - 1.6 days
• Compact grep - 7.0 days
• Hawkeye indexed - 29.0 days

Local codebase search for Claude Code, VS Code, Cursor, and AI agents.

Hawkeye AI Bridge lets AI coding assistants query Hawkeye’s local project index through MCP, so they can find exact references across large codebases, assets, scripts, localization, config files, and project content without uploading the full repository.

Instead of giving an AI agent huge raw grep output, Hawkeye can return compact file/line results that help the agent decide which files are actually worth reading next.

1. Search large projects locally
2. Reduce token usage from noisy raw search output
3. Find exact references across code and non-code project files
4. Useful for C++, C#, Unreal Engine, Unity, legacy projects, and proprietary codebases
5. Hawkeye runs locally/on-premises and does not use AI for indexing or searching

Table of Contents

• What is this?
• Why use Hawkeye AI Bridge?
• Prerequisites
• Client Setup
  • Claude Desktop
  • Claude Code (CLI)
  • VS Code / GitHub Copilot
  • Cursor
  • OpenCode
• Installing the Skill for Claude
• Available Tools
• Token Savings
• Example Prompts
• Privacy and Security
• Updating
• Removing
• Troubleshooting
• License
• Support

What is this?

This repository is the official public setup and discovery repository for using Hawkeye AI Bridge as an MCP server.

It does not contain the proprietary Hawkeye AI Bridge source code. Hawkeye and Hawkeye AI Bridge are proprietary software owned by Zaragsoft.

Why use Hawkeye AI Bridge?

Hawkeye helps developers quickly search and understand large projects. With MCP support, AI coding assistants can ask Hawkeye for fast local search results, saving tokens on each call.

Typical use cases:

• Find all references to a class, function, symbol, asset, localization key, or file.
• Search large codebases without relying only on editor search.
• Help AI coding assistants understand more of the project before making changes.
• Navigate large game/software projects with less reliance on tribal knowledge.
• Keep search local/on-premises.
• ~80% token reduction vs. blind file reading.
• If you do not specify any groups then all groups will be used.

Prerequisites

• Hawkeye installed — get it from https://www.zaragsoft.se/downloads
• Hawkeye AI Bridge installed — get it from https://www.zaragsoft.se/aibridge
• A local project indexed by Hawkeye
• Video walkthrough: https://www.youtube.com/watch?v=l1J-G36QSwI

Recommended install path: Place the AIBridge folder at C:\Program Files\Hawkeye\AIBridge\. Use this path in all examples below. If you install elsewhere, substitute your actual path throughout.

Client Setup

Claude Desktop

You don't need this zip for Claude Desktop. Download Hawkeye.mcpb from the release page and install it directly:

• If .mcpb is a recognised file type on your system: double-click the file.
• Otherwise: go to Settings → Extensions → Install Extension and select the file.

Claude Code (CLI)

Quick Start (5 steps)

1. Install Hawkeye from https://www.zaragsoft.se/downloads if you haven't already.
2. Move the AIBridge folder to a permanent location — recommended: C:\Program Files\Hawkeye\AIBridge\. Don't run it from Downloads; the registered path must keep working.
3. Register the MCP server with Claude Code:
   Terminal

   Copy

   claude mcp add hawkeye --scope user -- "C:\Program Files\Hawkeye\AIBridge\HawkeyeAIBridge.exe"
   

4. Install the Skill so Claude knows when to use Hawkeye. hawkeye-search.skill is a zip archive (it just contains SKILL.md), so it needs to be extracted, not renamed:
   powershell

   Copy

   $skillDir = "$env:USERPROFILE\.claude\skills\hawkeye-search"
   New-Item -ItemType Directory -Force -Path $skillDir | Out-Null
   Expand-Archive -Path "C:\Program Files\Hawkeye\AIBridge\hawkeye-search.skill" -DestinationPath $skillDir -Force
   

5. Verify — close and reopen your terminal, then run:
   Terminal

   Copy

   claude mcp list
   

   You should see hawkeye with 9 tools available.

Make sure Claude Code can find Hawkeye

The MCP server needs to locate hawkeye.exe. Pick one option:

Option A (recommended): Set HAWKEYE_PATH

# PowerShell — persistent
[Environment]::SetEnvironmentVariable("HAWKEYE_PATH", "C:\Program Files\Hawkeye\hawkeye.exe", "User")

:: Command Prompt — persistent
setx HAWKEYE_PATH "C:\Program Files\Hawkeye\hawkeye.exe"

After setting an environment variable, close and reopen your terminal so the new value takes effect.

Option B: Add Hawkeye to PATH via Windows GUI

1. Press Win, type Environment Variables, open Edit the system environment variables.
2. Click Environment Variables… → under User variables, select Path → Edit… → New.
3. Add C:\Program Files\Hawkeye and click OK on all dialogs.
4. Restart your terminal.

Avoid setx PATH "%PATH%;..." from the command line — it can truncate PATH at 1024 characters. Use the GUI instead.

Notes on the registration command

• --scope user makes Hawkeye available in every Claude Code session, not just the current folder.
• The -- separator is required. It tells Claude Code where its own flags end and the registered command begins. Without it, registration may fail.

VS Code / GitHub Copilot

Hawkeye works as an MCP server in VS Code's Copilot Agent mode. Register the exe, then open Copilot Chat in Agent mode.

Quick install (default path)

Click the button above, then click Allow in VS Code.

Manual setup

Add this to your .vscode/mcp.json (create the file if it doesn't exist):

{
  "servers": {
    "hawkeye": {
      "type": "stdio",
      "command": "C:\\Program Files\\Hawkeye\\AIBridge\\HawkeyeAIBridge.exe"
    }
  }
}

To make Hawkeye available across all projects, add it to your user-level config instead:

// %APPDATA%\Code\User\mcp.json
{
  "servers": {
    "hawkeye": {
      "type": "stdio",
      "command": "C:\\Program Files\\Hawkeye\\AIBridge\\HawkeyeAIBridge.exe"
    }
  }
}

Using Hawkeye in Copilot Chat

1. Open Copilot Chat (Ctrl+Alt+I)
2. Switch to Agent mode (the dropdown at the top — must be Agent, not Ask or Edit)
3. Try: "Search for findTeam in my codebase"

Note: The hawkeye-search.skill file is for Claude Code and Claude Desktop only — VS Code uses Copilot's own context system and doesn't need it.

Cursor

Open Settings → Tools & MCP → New MCP Server and add:

{
  "mcpServers": {
    "hawkeye": {
      "command": "cmd",
      "args": ["/c", "C:\\Program Files\\Hawkeye\\AIBridge\\HawkeyeAIBridge.exe"],
      "env": {}
    }
  }
}

Why cmd /c? Cursor passes the command path to the shell without quoting it, which breaks paths containing spaces (like C:\Program Files\). Wrapping it with cmd /c works around this.

Adjust the path if Hawkeye AI Bridge is installed somewhere else.

OpenCode

Add the following to your opencode.json (create it in your project root or home directory if it doesn't exist):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "hawkeye": {
      "type": "local",
      "command": ["C:\\Program Files\\Hawkeye\\AIBridge\\HawkeyeAIBridge.exe"]
    }
  }
}

Three things differ from the Claude Code config:

• The key is "mcp", not "mcpServers"
• command is an array of strings, not a command + args split
• "type": "local" is required

Installing the Skill for OpenCode

The Skill is required for OpenCode. Without it, OpenCode will try to call hawkeye.exe directly on the command line rather than routing tool calls through the MCP server.

OpenCode expects skills to be extracted from the .skill zip archive:

$skillDir = "$env:USERPROFILE\.opencode\skills"
New-Item -ItemType Directory -Force -Path $skillDir | Out-Null

$tempZip = "$env:TEMP\hawkeye-search.zip"
Copy-Item "C:\Program Files\Hawkeye\AIBridge\hawkeye-search.skill" $tempZip -Force
Expand-Archive -Path $tempZip -DestinationPath $skillDir -Force
Remove-Item $tempZip

Once both are in place, restart OpenCode and try: "Find where PlayerController is defined." You should see it call hawkeye_search_minimal.

Installing the Skill for Claude

The Skill teaches Claude when and how to use the Hawkeye tools. Without it, Claude has to guess from tool descriptions alone — results will be worse.