Model Context Protocol (MCP)

Overview

Model Context Protocol (MCP) is an open standard developed by Anthropic that enables AI assistants to connect with external tools and data sources. MCP is now generally available across major development platforms including VS Code, JetBrains IDEs, and more. CodeAlive’s MCP server provides your AI assistant with deep, contextual understanding of your entire codebase through semantic search and intelligent code analysis.

Already using an older CodeAlive MCP integration? Follow the MCP v1/v2 → v3 migration guide to update tool names, arguments, prompts, and deployment configuration.

Why Use CodeAlive MCP?

Deep Context

AI understands relationships across your entire codebase, not just individual files

Semantic Search

Find code by meaning and intent, not just keywords

Multi-Repository

Work seamlessly across multiple repositories in one session

Real-Time Updates

Always work with the latest indexed version of your code

Deployment Options

CodeAlive MCP can be deployed in three ways, depending on your needs:

1. Remote Service (Recommended)

URL: https://mcp.codealive.ai/api/
Best for: Quick setup, no infrastructure management
Requirements: CodeAlive API key
Supported Clients: All MCP-compatible AI assistants

2. Docker Container

Image: ghcr.io/codealive-ai/codealive-mcp:main
Best for: Enterprise environments, local development
Requirements: Docker, CodeAlive API key
Benefits: Network isolation, custom configuration

3. Self-Hosted Instance

Repository: CodeAlive MCP Server
Best for: Complete control, custom modifications
Requirements: Python 3.11+, infrastructure management
Benefits: Full customization, on-premise deployment

Getting Started

Add at least one repository to CodeAlive before creating an API key. You do not need to wait for indexing to finish to create the key, but MCP queries become useful only after the repository is indexed.

Add a repository

Sign up or log in at app.codealive.ai
Go to Repositories in your dashboard
Click Add Repository
Connect your GitHub/GitLab/Bitbucket account
Select at least one repository to add

Create your API key

Navigate to MCP & API
Click ”+ Create API Key”
Copy your key immediately (it won’t be displayed again)
Store your API key securely

Wait for indexing

CodeAlive starts indexing after the repository is added. Wait for initial indexing to complete before expecting useful chat or search results. Initial indexing typically takes 5-15 minutes.

Choose Your Integration

Quick setup: Run npx @codealive/installer to auto-configure CodeAlive for your agents. See the Installation Guide for details.Or select your AI assistant to see manual setup instructions:

Claude Code

Remote MCP with OAuth support

VS Code + GitHub Copilot

Native MCP support (GA)

Cursor

MCP with elicitation & resources

Windsurf

Streamable HTTP with serverUrl

Continue

Full MCP feature support

Cline

Auto-tool creation capabilities

Claude Desktop

Desktop app with MCP

Codex

OpenAI Codex CLI with TOML config

Gemini CLI

One-command setup

Amazon Q

CLI and IDE integration

OpenCode

Terminal AI with remote transport

SourceCraft

Code Assistant and CLI setup

Zed

Native remote MCP support

ChatGPT

Custom GPTs with Actions

Other Agents

Roo Code, KodaCode, GigaCode, and more

Available MCP Tools

CodeAlive exposes eleven MCP v3 tools. The default discovery pair is semantic_search and grep_search; chat is a slower stateless synthesis fallback that should be called only when explicitly requested. Agent-repairable failures, such as an invalid path or ambiguous data source, return actionable <tool_error> text and set the MCP result’s native isError flag. Authentication, quota, network, and server failures are also surfaced as tool errors rather than empty results.

`get_data_sources`

Lists all indexed repositories and workspaces available for querying. Pass the optional query argument — a natural-language description of the task, such as “add OAuth to checkout” — to get only the data sources relevant to it, each with a relevanceReason explaining the match. Recommended whenever the agent knows what the user is trying to accomplish; omit query to list everything. Use cases:

Scope the source list to the current task with query
Verify repository access
Check indexing status
List available codebases

`semantic_search`

Canonical semantic search across indexed artifacts. Find code by meaning and intent, not just keywords. Use cases:

Find implementation patterns
Locate specific functionality
Discover related code
Trace data flows

`grep_search`

Canonical exact text or regex search with line-level previews. Use cases:

Find exact strings, identifiers, or log messages
Run regex lookups across indexed repositories
Confirm literal matches before fetching full source

`chat`

Canonical synthesized codebase Q&A tool. Use chat only when explicitly requested and when you need a synthesized answer instead of direct evidence gathering. It can take substantially longer than retrieval. Tool API v3 chat is stateless: include prior findings, artifact identifiers, assumptions, scope, and constraints in every question. If your agent supports subagents and you need the highest reliability or depth, prefer a multi-step agent workflow that combines ontology, semantic_search, grep_search, fetch_artifacts, read_file, relationship inspection, metadata queries, and local file reads. Use cases:

Architecture explanations after search
Synthesized flow walkthroughs
One-shot answers with all required context included in the question

`get_repository_ontology`

Get repository-level orientation for exactly one selected repository.

`get_file_tree`

Inspect a bounded file tree for exactly one selected repository.

`read_file`

Read a repository-relative file path, optionally bounded by line range.

`fetch_artifacts`

Retrieve full source code content for specific artifacts found via search. Use this to get the actual code after reviewing search descriptions. Use cases:

Get full content for external repo search results
Inspect specific functions or classes in detail
Follow the search → review → fetch workflow

Workflow: Call semantic_search or grep_search first, review the descriptions or line previews and identifiers in the results, then call fetch_artifacts with the identifiers you want to inspect (max 50 per request). For repositories in your working directory, use local file reads instead. Optional data_source (disambiguation): Each search result carries a dataSource id and name. When an identifier exists in more than one data source, pass that name or id as the optional data_source argument to scope the fetch to one source. Missing identifiers: If some requested identifiers cannot be resolved (or are outside your access scope), the response is not silently truncated — they are listed in a <not_found count="N"> block naming each concrete identifier, followed by a hint to re-check those ids and retry the problematic ones. Surface them to the user rather than omitting the requested artifact.

`get_artifact_relationships`

Expand one artifact’s call graph, inheritance hierarchy, or reference relationships after you already have its identifier. Use cases:

Trace outgoing and incoming calls for one function
Explore class inheritance chains
Inspect reference-heavy symbols without fetching whole files

Optional data_source (disambiguation): Same as fetch_artifacts — pass a data source name or id (from a search result’s dataSource) to resolve an identifier that exists in more than one data source.

Handling the ambiguous-identifier 409. If you call fetch_artifacts or get_artifact_relationships with an identifier that exists in more than one data source and you do not pass data_source, the backend returns a 409 and the tool surfaces the list of candidate data sources (by name and id). Each candidate will resolve, so the sequence is: call without data_source → read the 409 candidates → retry with one candidate’s name/id → if that data source isn’t the one you want, retry with the next. Do not invent a result.Scoped request found nothing. If you did pass data_source but the call comes back empty (fetch_artifacts returns no content, get_artifact_relationships returns found: false), the tool emits a hint: the identifier likely belongs to a different data source, or the data_source value is wrong. Retry with a different candidate’s name/id, or omit data_source to get the 409 candidate list — don’t conclude the artifact doesn’t exist.

`get_artifact_query_schema`

Inspect supported ArtifactQuery entities, fields, operators, and examples before writing metadata queries.

`query_artifact_metadata`

Run read-only metadata analytics across selected repositories. Use this for aggregate questions such as file counts, languages, complexity, relationship counts, and metadata filtering.

Common Use Cases

Code Understanding
Bug Investigation
Code Generation
Architecture Analysis

You: "Explain how user authentication works in our system"

AI: [Searches for authentication code across repositories]
    [Maps out the complete auth flow]
    [Explains with actual code references]

You: "Debug why payments are failing intermittently"

AI: [Searches for payment processing code]
    [Analyzes error handling and retry logic]
    [Identifies potential race conditions]

You: "Create a new API endpoint following our patterns"

AI: [Analyzes existing API endpoints]
    [Identifies conventions and patterns]
    [Generates code matching your style]

You: "What would be impacted if we change this database schema?"

AI: [Searches for all references to the schema]
    [Maps dependencies across services]
    [Lists required migrations and updates]

Security & Privacy

CodeAlive MCP follows security best practices:

All connections are encrypted with TLS
API keys are never logged or stored in plain text
Repository access is controlled at the API key level
Self-hosted options available for sensitive codebases

Best Practices

Keep Repos Updated

Regularly sync repositories in your dashboard for accurate context

Use Specific Queries

Be precise with technical terms for better search results

Organize by Project

Use separate API keys for different projects or environments

Monitor Usage

Track API usage in your dashboard to optimize queries

Troubleshooting

Connection Issues

Common causes:

Invalid or expired API key
Network connectivity problems
Incorrect MCP server URL

Solutions:

Regenerate API key in dashboard
Check network/firewall settings
Verify URL is https://mcp.codealive.ai/api/

No Repositories Found

Common causes:

Repositories not indexed
API key lacks permissions
Indexing still in progress

Solutions:

Check indexing status in dashboard
Wait 5-15 minutes for initial indexing
Verify API key has repository access

Slow Response Times

Common causes:

Large codebase searches
Broad/vague queries
Network latency

Solutions:

Use more specific search queries
Limit search to specific repositories
Consider Docker or self-hosted deployment

For more solutions, see the Troubleshooting Guide.

Next Steps

Choose Your Client

Set up CodeAlive with your preferred AI assistant

Self-Hosting Guide

Deploy CodeAlive MCP on your infrastructure

API Reference

Explore the full CodeAlive API

GitHub Repository

View source code and contribute

​Overview

​Why Use CodeAlive MCP?

Deep Context

Semantic Search

Multi-Repository

Real-Time Updates

​Deployment Options

​1. Remote Service (Recommended)

​2. Docker Container

​3. Self-Hosted Instance

​Getting Started

Claude Code

VS Code + GitHub Copilot

Cursor

Windsurf

Continue

Cline

Claude Desktop

Codex

Gemini CLI

Amazon Q

OpenCode

SourceCraft

Zed

ChatGPT

Other Agents

​Available MCP Tools

​get_data_sources

​semantic_search

​grep_search

​chat

​get_repository_ontology

​get_file_tree

​read_file

​fetch_artifacts

​get_artifact_relationships

​get_artifact_query_schema

​query_artifact_metadata

​Common Use Cases

​Security & Privacy

​Best Practices

Keep Repos Updated

Use Specific Queries

Organize by Project

Monitor Usage

​Troubleshooting

​Next Steps

Choose Your Client

Self-Hosting Guide

API Reference

GitHub Repository

Overview

Why Use CodeAlive MCP?

Deployment Options

1. Remote Service (Recommended)

2. Docker Container

3. Self-Hosted Instance

Getting Started

Available MCP Tools

`get_data_sources`

`semantic_search`

`grep_search`

`chat`

`get_repository_ontology`

`get_file_tree`

`read_file`

`fetch_artifacts`

`get_artifact_relationships`

`get_artifact_query_schema`

`query_artifact_metadata`

Common Use Cases

Security & Privacy

Best Practices

Troubleshooting

Next Steps