Claude Code Integration

Overview

Recommended: Use the Claude Code Plugin instead. The plugin provides a better experience for Claude Code users — it includes the Context Engine skill, a code exploration subagent, and authentication hooks, all in a single install. The MCP integration described on this page is still supported and can be used alongside the plugin for direct tool access.

Integrate CodeAlive with Claude Code to enhance your AI coding assistant with deep contextual understanding of your entire codebase. This integration uses the Model Context Protocol (MCP) to provide Claude Code with semantic search and code intelligence capabilities.

Quick install: Run npx @codealive/installer to automatically configure CodeAlive for Claude Code. See the Installation Guide for details.

Claude Code defaults to its built-in Grep/Glob for exploration. Connecting the MCP server alone won’t change that — add routing rules to your project’s CLAUDE.md so Claude reaches for CodeAlive first. See Custom Instructions below for a complete snippet.

Prerequisites

Claude Pro, Max, Team, or Enterprise subscription (required for MCP support)
Claude Code installed
CodeAlive account (Sign up here)
Indexed repositories in your CodeAlive dashboard

Installation Steps

Claude Code supports both local and remote MCP servers with OAuth authentication.

Add via CLI (Recommended)

Run this command in your terminal:

claude mcp add --transport http codealive https://mcp.codealive.ai/api

Start Claude Code, run /mcp, select codealive, and complete browser sign-in. Claude Code stores and refreshes the OAuth credential automatically.

Existing API-key configurations remain supported. Add --header "Authorization: Bearer YOUR_API_KEY_HERE" only when you intentionally choose that fallback.

Alternative: Docker (STDIO)

For local development or enhanced privacy:

claude mcp add codealive-docker /usr/bin/docker run --rm -i -e CODEALIVE_API_KEY=YOUR_API_KEY_HERE ghcr.io/codealive-ai/codealive-mcp:main

Verify Integration

Test the integration by asking Claude Code:

“What CodeAlive repositories are available?”
“Search for authentication code in my codebase”
“Explain the architecture of my project”

Available Commands

Once integrated, Claude Code can use these CodeAlive capabilities:

Repository Management

"Show me all my indexed repositories"
"What codebases are connected to CodeAlive?"
"Update the repository index"

Semantic Code Search

"Find all API endpoints in the user service"
"Show me error handling patterns across the codebase"
"Locate database connection implementations"
"Search for OAuth implementation"

Contextual Analysis

"Explain how the payment flow works"
"Analyze this code for security vulnerabilities"
"Generate comprehensive tests for the AuthService"
"Review the authentication implementation"

Usage Patterns

Code Understanding
Bug Investigation
Code Generation
Refactoring

You: "Help me understand how the user authentication works"

Claude Code: [Searches your codebase for authentication logic]
            [Maps out the authentication flow]
            [Explains with actual code references]

You: "Debug why users can't reset their passwords"

Claude Code: [Searches for password reset code]
            [Traces the flow from UI to backend]
            [Identifies potential issues with code references]

You: "Create a new API endpoint similar to our existing ones"

Claude Code: [Analyzes existing API patterns]
            [Generates code matching your conventions]
            [Includes proper error handling and validation]

You: "Refactor this service to match our microservices pattern"

Claude Code: [Finds similar service implementations]
            [Suggests refactoring based on codebase patterns]
            [Ensures consistency with existing architecture]

Windows & WSL

Claude Code on Windows runs inside WSL (Windows Subsystem for Linux). The Remote HTTP option above works perfectly in WSL without any extra configuration — it’s the recommended approach.

Claude Code in WSL (Recommended)
Docker STDIO in WSL
Self-Hosted in WSL2

When Claude Code runs inside WSL, it operates as a normal Linux environment. Use the same Remote HTTP command:

claude mcp add --transport http codealive https://mcp.codealive.ai/api

This avoids all WSL-specific issues (path translation, Docker socket, networking).

If you need Docker STDIO in WSL, ensure Docker Desktop has WSL integration enabled for your distro:

claude mcp add codealive-docker /usr/bin/docker run --rm -i -e CODEALIVE_API_KEY=YOUR_API_KEY_HERE ghcr.io/codealive-ai/codealive-mcp:main

If docker is not found, enable Docker Desktop WSL integration: Docker Desktop → Settings → Resources → WSL integration → enable your distro.

If you self-host the MCP server inside WSL2, note that WSL2 uses NAT networking — localhost in WSL2 is not the same as localhost on Windows.Fix: Enable mirrored networking (Windows 11 22H2+) in %USERPROFILE%\.wslconfig:

[wsl2]
networkingMode=mirrored

Then restart WSL: wsl --shutdown.Alternatively, use the WSL2 VM IP (run hostname -I inside WSL) instead of localhost.

Advanced Features

Multi-Repository Support

CodeAlive automatically provides access to all repositories indexed in your dashboard. Use the get_data_sources tool to discover available repositories and workspaces — pass your task as its query argument to get only the relevant ones — then target specific ones in your searches:

"Search for authentication code in the backend repository"
"Find user models across backend, frontend, and mobile repos"
"Show me API patterns in workspace:platform-team"

See Multi-Repository & Workspaces for details on organizing repositories.

Custom Search Scopes

Focus searches on specific parts of your codebase:

"Search for user models only in the backend repository"
"Find React components in the frontend folder"
"Look for migrations in the database directory"

Intelligent Code Reviews

"Review this PR for consistency with our codebase"
"Check if this change follows our patterns"
"Find potential breaking changes"

Best Practices

Keep Repos Updated

Regularly sync repositories in CodeAlive dashboard for accurate context

Use Specific Queries

Be precise with technical terms for better search results

Leverage Context

Reference CodeAlive when working with large codebases

Iterate Quickly

Use CodeAlive to validate ideas before implementing

Productivity Tips

Quick Commands

Use slash commands for common operations:

/search - Quick code search
/explain - Get explanations with context
/similar - Find similar implementations
/repos - List available repositories

Context Management

Clear context between unrelated tasks
Use CodeAlive to establish context for new features
Reference specific files when needed

Code Generation

Always search for existing patterns first
Let Claude Code match your coding style
Verify generated code against your conventions

Troubleshooting

CodeAlive not responding

Solutions:

Check MCP server status in Claude Code
Verify API key is correct and active
Ensure repositories are indexed
Try reloading Claude Code

No repositories found

Solutions:

Log into CodeAlive dashboard
Verify repositories are indexed
Wait for indexing to complete
Check API key permissions

Slow responses

Solutions:

Use more specific search queries
Limit search to specific repositories
Check CodeAlive service status
Consider upgrading your plan

Authentication errors

Solutions:

Regenerate API key in dashboard
Update MCP configuration
Ensure Bearer token format is correct
Test API key with curl

WSL: docker or npx not found

Solutions:

Use Remote HTTP instead — it avoids all WSL path issues
Enable Docker Desktop WSL integration for your distro (Settings → Resources → WSL integration)
Use absolute binary paths (e.g., /usr/bin/docker, /home/user/.nvm/versions/node/v20/bin/npx)
Add missing env vars explicitly in the MCP config env block — non-interactive WSL shells don’t source .bashrc

WSL2: Connection refused to self-hosted server

Solutions:

WSL2 uses NAT networking — localhost in WSL2 differs from Windows localhost
Enable mirrored networking in %USERPROFILE%\.wslconfig (see Windows & WSL section above)
Or use the WSL2 VM IP: run hostname -I inside WSL

For more solutions, see the Troubleshooting Guide.

Integration with Claude Code Features

Projects

CodeAlive automatically understands your project structure
Provides context across multiple files and folders
Maintains awareness of dependencies and imports

Custom Instructions

Claude Code reads CLAUDE.md from the repo root (and ~/.claude/CLAUDE.md globally) on every run; it also picks up a repo-root AGENTS.md. Add a CodeAlive section with explicit routing rules — naming the built-in tools you are overriding is what makes the instruction stick:

CLAUDE.md — CodeAlive section

## CodeAlive context engine

CodeAlive MCP tools search server-side indexes of all our repositories —
cross-repo, always in sync with the default branch.

- For exploration questions — "how does X work", "where is Y implemented",
  "what calls Z" — use CodeAlive `semantic_search` FIRST. Do NOT use the
  built-in Grep/Glob for these questions unless CodeAlive has returned
  nothing useful twice.
- Phrase `semantic_search` as a full English sentence, never bare keywords.
  Keep exact identifiers verbatim.
- Use CodeAlive `grep_search` for exact symbol names, literals, error
  messages, config keys, and acronyms — pass the literal text, not a question.
- Read returned artifact identifiers with `fetch_artifacts`; map callers and
  callees with `get_artifact_relationships` before claiming how code flows.
- Built-in Grep/Glob/Read remain correct for files you are actively editing
  in the working tree.

Two refinements once the basics work:

Isolate heavy exploration in a subagent. Search-heavy CodeAlive sessions fill the main context with tool output. A dedicated subagent (.claude/agents/) that owns CodeAlive exploration and returns only conclusions keeps the main conversation clean — this is exactly what the Claude Code Plugin ships out of the box.
Keep the section short. CLAUDE.md is injected into every request; 10–15 lines is the sweet spot. General patterns and rationale live in Instructing Coding Agents.

Code Review Mode

When reviewing code:

"Use CodeAlive to check if this follows our patterns"
"Find similar code that might need the same fix"
"Identify all places affected by this change"

Instructing Coding Agents

Patterns that make agents prefer CodeAlive tools

MCP Protocol

Learn about Model Context Protocol

API Reference

Direct API integration guide

Dashboard

Manage your repositories

Support

Get help from our team

Instruct Your Agent

Connecting CodeAlive makes its tools available, but the agent may still default to its built-in search. For reliable results, add a short instruction in the agent’s native format telling it to prefer semantic_search and grep_search when exploring indexed code. See Instructing Coding Agents.

Getting Started

Features

Model Context Protocol

Agent Skills & Plugins

Instructing Agents

Claude Code Integration

Overview

Prerequisites

Installation Steps

Available Commands

Repository Management

Semantic Code Search

Contextual Analysis

Usage Patterns

Windows & WSL

Advanced Features

Multi-Repository Support

Custom Search Scopes

Intelligent Code Reviews

Best Practices

Keep Repos Updated

Use Specific Queries

Leverage Context

Iterate Quickly

Productivity Tips

Troubleshooting

Integration with Claude Code Features

Projects

Custom Instructions

Code Review Mode

Instructing Coding Agents

MCP Protocol

API Reference

Dashboard

Support

Instruct Your Agent

​Overview

​Prerequisites

​Installation Steps

​Available Commands

​Repository Management

​Semantic Code Search

​Contextual Analysis

​Usage Patterns

​Windows & WSL

​Advanced Features

​Multi-Repository Support

​Custom Search Scopes

​Intelligent Code Reviews

​Best Practices

Keep Repos Updated

Use Specific Queries

Leverage Context

Iterate Quickly

​Productivity Tips

​Troubleshooting

​Integration with Claude Code Features

​Projects

​Custom Instructions

​Code Review Mode

​Related Resources

Instructing Coding Agents

MCP Protocol

API Reference

Dashboard

Support

​Instruct Your Agent

Overview

Prerequisites

Installation Steps

Available Commands

Repository Management

Semantic Code Search

Contextual Analysis

Usage Patterns

Windows & WSL

Advanced Features

Multi-Repository Support

Custom Search Scopes

Intelligent Code Reviews

Best Practices

Productivity Tips

Troubleshooting

Integration with Claude Code Features

Projects

Custom Instructions

Code Review Mode

Related Resources

Instruct Your Agent