Documentation

Everything you need to get mcp-injector working

Quick Navigation

Installation

System requirements

  • macOS 12+, Linux (any modern distro), Windows 10+
  • Claude Desktop, Cursor, or VS Code with Continue extension
  • Git (for branch-aware re-indexing feature)

Install command

This command downloads and runs the local installer script:

curl -fsSL https://foldwork.dev/install | sh

The script performs the following tasks:

  • Downloads the correct binary for your OS and architecture.
  • Installs to /usr/local/bin/mcp-injector (or ~/.local/bin if /usr/local/bin is not writable).
  • Detects installed IDEs and writes the MCP configuration.
  • Does not require sudo unless /usr/local/bin needs it.

Manual installation

If you prefer not to use the automated install script, follow these steps:

  1. Go to github.com/foldwork-dev/mcp-injector/releases/latest.
  2. Download the binary matching your platform.
  3. Make the downloaded binary executable: 
    chmod +x mcp-injector-darwin-arm64
  4. Move the binary to your path: 
    mv mcp-injector-darwin-arm64 /usr/local/bin/mcp-injector
  5. Add the MCP configuration manually. Refer to the IDE Setup section below.

Free tier vs Pro

Free: workspaces under 100,000 lines. No license key is needed.

Pro: workspaces of any size. Requires a license key from foldwork.dev after purchase.

To check your workspace line count before installing, run the benchmark tool:

mcp-benchmark ./your-project

The output shows your total line count. If it is under 100,000 lines, you do not need Pro.

Verifying it works

After installation and restarting your IDE, verify mcp-injector is running by prompting Claude:

Prompt: "Call get_project_map and show me the structure of this project"

A working installation returns a payload similar to the following:

{
  "workspace": "/path/to/your/project",
  "total_files": 47,
  "total_raw_tokens": 198400,
  "total_compressed_tokens": 72600,
  "savings_pct": 63.4,
  "current_branch": "main",
  "modules": []
}

If Claude says it cannot find the tool, see the Troubleshooting section below.

Signs of correct operation:

  • Claude can answer questions about files not currently open.
  • Claude knows your project structure without you explaining it.
  • Claude references the correct branch name.
  • Token usage in your Claude dashboard decreases over time.

IDE setup

Claude Desktop

Config file locations:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json
  • Windows: %APPDATA%/Claude/claude_desktop_config.json

Add this entry to the mcpServers object:

"mcp-injector": {
  "command": "/usr/local/bin/mcp-injector",
  "env": {
    "MCP_WORKSPACE": "/absolute/path/to/your/project"
  }
}

Important: MCP_WORKSPACE must be an absolute path. Use the full path from the root. Restart Claude Desktop after editing this configuration.

Cursor

Config file path: ~/.cursor/mcp.json

Cursor supports the workspace folder variable. You can use the following configuration structure:

"mcp-injector": {
  "command": "/usr/local/bin/mcp-injector",
  "env": {
    "MCP_WORKSPACE": "${workspaceFolder}"
  }
}

Cursor automatically resolves ${workspaceFolder} to the open project folder. This enables one Cursor configuration to work across all your projects.

VS Code with Continue

Config file path: ~/.continue/config.json

Add the configuration to the mcpServers array in your Continue configuration file. Refer to the Continue documentation for exact formatting details.

Running multiple projects

Each project requires its own MCP_WORKSPACE value. If you work on multiple projects, you have two options:

Option A: Update MCP_WORKSPACE in your IDE configuration manually when switching projects.

Option B: Run a separate daemon instance for each project on a different configuration. Each daemon maintains its own index at ~/.mcp-injector/cache/<workspace-hash>.db to avoid conflicts.

Using the MCP tools

mcp-injector exposes three tools. Claude calls these tools automatically when relevant. You can also prompt Claude to call them explicitly.

get_project_map

This tool returns a compressed view of the codebase.

Prompt: "Use get_project_map to show me this project"

Parameters:

  • tier (1, 2, or 3): compression level. Default is 3. Tier 1 does not compress. Tier 2 folds function bodies but keeps signatures. Tier 3 folds bodies and strips comments.
  • unfolded_files: array of file paths or glob patterns to serve at full resolution.

Example prompt: "Get the project map but show me src/auth/handler.go at full resolution"

injector_retrieve

This tool fetches the complete uncompressed source of a file.

Prompt: "Show me the full implementation of UserService.java"

Claude calls this tool automatically when it needs to inspect a folded function body.

injector_stats

This tool shows daemon status and cumulative savings.

Prompt: "Call injector_stats and show me my token savings"

The response includes indexed files, workspace line count, compression ratio, cache hit rate, and Pro license status.

Advanced configuration

Excluding files from compression

Create a .mcp-ignore file in your workspace root. It uses the same formatting rules as a .gitignore file:

# Exclude generated files
generated/
*.pb.go
dist/

# Exclude large data files
testdata/
fixtures/

Files matching these patterns are excluded from the index. They will not appear in get_project_map and cannot be retrieved via injector_retrieve. mcp-injector also respects your existing .gitignore file automatically.

Adjusting default compression tier

The default compression tier is 3. If you want to change the default behavior, prompt Claude to use a lower tier:

Prompt: "Use get_project_map with tier 2"

Tier 2 keeps signatures and folds bodies but preserves comments. This is useful when comments contain design decisions.

Branch switching

mcp-injector installs a post-checkout git hook on startup. When you switch branches, the hook signals the daemon to re-index.

The daemon logs show the transition details:

[mcp-injector] Branch switched to feature/auth, re-indexing...
[mcp-injector] Re-index complete in 4.2s

If branch switching does not trigger re-indexing:

  1. Check that .git/hooks/post-checkout exists in your workspace.
  2. Verify the hook file is executable.
  3. If the hook is missing, restart the daemon on that workspace to reinstall it.

Pro license activation

Activate your Pro subscription license key by adding it to the environment section of your IDE MCP configuration:

"env": {
  "MCP_WORKSPACE": "/path/to/project",
  "MCP_LICENSE_KEY": "your-license-key-here"
}

License validation runs offline. No outbound network connections are required after activation.

Troubleshooting

Claude says it cannot find get_project_map

Cause: The MCP server is not running or not configured for this IDE.

Fix: Verify the binary path by running which mcp-injector. Confirm your IDE configuration file contains the correct entry. Restart your IDE completely.

The tool runs but returns an empty project map

Cause: The MCP_WORKSPACE environment variable points to the wrong directory or an empty directory.

Fix: Check the workspace path in your IDE configuration. Verify it is an absolute path. Run mcp-benchmark /your/workspace/path to confirm it finds source files.

Branch switching is not triggering re-indexing

Cause: The post-checkout hook is missing or not executable.

Fix: Run cat .git/hooks/post-checkout inside your repository. If the file is missing, restart the daemon on this workspace. If present, make it executable: 

chmod +x .git/hooks/post-checkout

Daemon exits immediately on startup

Cause: The MCP_WORKSPACE environment variable is not set, or points to a path that does not exist. You will see: [mcp-injector] Error: MCP_WORKSPACE is not set.

Fix: Add MCP_WORKSPACE to the env section of your IDE MCP configuration.

Free tier workspace limit message

Cause: Your project codebase size exceeds the 100,000 line free tier limit.

Fix: Run mcp-benchmark ./your-project to confirm the line count. Obtain a Pro license key from foldwork.dev to lift the limit.

Secrets are being redacted unexpectedly

Cause: The Shannon entropy analyzer flagged a high-entropy string (such as a hash or UUID) in your source code.

Fix: The output will show the redaction metadata. The variable name is preserved. The value is replaced with [REDACTED: high entropy]. Add the affected file to .mcp-ignore if you need to serve it raw.

Windows-specific issues

Cause: The MCP_WORKSPACE path uses backslashes which are not escaped in JSON.

Fix: Use forward slashes in your Windows path settings. For example: "C:/Users/username/projects/myapp". Do not include a trailing slash.

Limitations

mcp-injector works well on most codebases but has the following known limitations:

  • Files over 5MB are skipped. Large generated outputs or data assets are excluded from indexing.
  • Minified files are skipped. Files with fewer than 10 lines but exceeding 50KB are detected as minified and ignored.
  • inotify limits on Linux. Large repositories (100,000+ files) may exceed default inotify watch limits. Increase the limit with this command: 
    echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p
  • NFS and network drives. File watching does not work on network-mounted filesystems. The index is built on startup but will not update incrementally.
  • Windows file watching. File watching on Windows uses polling. Changes are detected within 2 to 3 seconds.
  • Polyglot files. Files with mixed content (.vue, .svelte, .astro) only compress the script section. Template sections are preserved but not compressed.

Uninstalling

Remove the binary file from your path:

sudo rm /usr/local/bin/mcp-injector

Remove the local cache index directory:

rm -rf ~/.mcp-injector/

Open your IDE configuration file and remove the mcp-injector entry from the servers list.

Remove the git hook installed in your repository:

rm .git/hooks/post-checkout

If you have other hooks, open the file and remove only the lines referencing mcp-injector.