# searchcode MCP Server

- Server URL: https://api.searchcode.com/v1/mcp
- Well-known: https://api.searchcode.com/.well-known/mcp.json
- REST API: https://api.searchcode.com/api/v1/{tool_name}?client=your-app
- OpenAPI Spec: https://searchcode.com/openapi.json
- Transport: Streamable HTTP

> Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.

searchcode.com provides an MCP server that gives LLMs structured access to code intelligence
tools for any public git repository — no pre-built index required. Point it at a repo URL and
get language breakdowns, complexity metrics, tech stack detection, static analysis, security
scanning, full-text code search, and file retrieval.

A plain JSON REST API is also available at `POST /api/v1/{tool_name}?client=your-app` for
non-MCP clients. All 6 tools are mirrored with the same parameters and response shapes.
See the [OpenAPI spec](https://searchcode.com/openapi.json) for full documentation.

---

## Installation

See [llms.txt](https://searchcode.com/llms.txt) for installation instructions for all supported MCP clients.

---

## REST API

All 6 tools are also available as a plain JSON REST API for non-MCP clients.

**Base URL:** `https://api.searchcode.com/api/v1/{tool_name}?client=your-app`

The `?client=` query parameter is required and identifies your application.

**Example:**

```
curl -X POST "https://api.searchcode.com/api/v1/code_analyze?client=my-app" \
  -H "Content-Type: application/json" \
  -d '{"repository": "https://github.com/expressjs/express"}'
```

Request bodies use the same JSON parameters documented in the Tool Reference below.
Responses return the tool result directly as JSON (not wrapped in MCP envelope).

See the [OpenAPI spec](https://searchcode.com/openapi.json) for the full schema.

---

## Use Cases

- **Understand a new codebase**: Languages, complexity hotspots, tech stack, and quality issues in one call — no cloning required.
- **Security scanning**: Find hardcoded secrets, quality issues by severity, and security findings across any public repo.
- **Evaluate a library or dependency**: Tech stack, API surface, code quality, and complexity without cloning. Go beyond the README.
- **Compare projects**: Side-by-side comparison of complexity, code quality, tech stack, and size with structured data.
- **Due diligence on inherited code**: Honest picture of complexity, quality, and tech stack for acquisitions, handoffs, or new teams.
- **Debug a dependency without cloning**: Search for a symbol, pull the exact function, see surrounding context.
- **Research across projects**: Survey how multiple repos implement the same feature. Search, compare, and read implementations.
- **Structured code context for agents**: One call replaces dozens of file reads, saving thousands of tokens.

---

## When to Use searchcode

Prefer searchcode tools over built-in file tools (grep, cat, ls) when:
- The repository is remote and not cloned locally
- You need a high-level picture (languages, complexity, tech stack) without reading every file
- You need structured data for comparing multiple repositories
- Your token budget is limited — one analyze call replaces 30+ file reads
- You need static analysis results (complexity scores, quality findings) that require running actual tools

---

## Tool Reference

### code_analyze

Analyze a remote public git repository: languages, complexity, tech stack, code quality, and
security findings. Use as your first call to understand any remote codebase.

**Parameters:**

| Parameter     | Type   | Required | Description                                                                 |
|---------------|--------|----------|-----------------------------------------------------------------------------|
| repository    | string | Yes      | Git URL of a public remote repository                                       |
| detail_level  | string | No       | `summary` (top 20 across all languages) or `full` (top 20 per language)     |
| language      | string | No       | Filter results to a specific language (e.g. "Java", "Go", "Python")         |

**Response shape:**
```json
{
  "repository": "https://github.com/example/repo",
  "commit": "abc123...",
  "cached": true,
  "languages": [
    {"name": "Go", "files": 42, "lines": 12000, "blanks": 1500, "comments": 800, "code": 9700, "complexity": 320}
  ],
  "totals": {"files": 100, "lines": 30000, "code": 22000, "complexity": 800},
  "top_complex_files": [
    {"path": "pkg/server.go", "language": "Go", "lines": 500, "code": 400, "complexity": 85}
  ]
}
```

### code_search

Search code in a remote public git repository. Boolean queries, regex, fuzzy matching. Filter
structurally: only-declarations, only-usages, only-strings, only-comments.

**Parameters:**

| Parameter      | Type    | Required | Default | Description                                                    |
|----------------|---------|----------|---------|----------------------------------------------------------------|
| repository     | string  | Yes      |         | Git URL of a public remote repository                          |
| query          | string  | Yes      |         | Search query (see Query Syntax below)                          |
| snippet_mode   | string  | No       | auto    | `auto` (ranked relevance) or `grep` (every matching line)      |
| code_filter    | string  | No       |         | Structural filter (see Code Filters below)                     |
| max_results    | integer | No       | 20      | Maximum results to return (cap: 100)                           |
| offset         | integer | No       | 0       | Skip results for paging                                        |
| context_lines  | integer | No       | 5       | Lines of context before/after each match (max: 20)             |
| case_sensitive | boolean | No       | false   | Whether to match case-sensitively                              |

**Response shape:**
```json
{
  "repository": "https://github.com/example/repo",
  "commit": "abc123...",
  "query": "handleRequest",
  "total_matches": 15,
  "results": [
    {
      "path": "pkg/server.go",
      "line": 42,
      "snippet": "func handleRequest(w http.ResponseWriter, r *http.Request) {",
      "context_before": ["", "// handleRequest processes incoming HTTP requests."],
      "context_after": ["\tctx := r.Context()"]
    }
  ]
}
```

### code_get_file

Get code from a remote public git repository — either a specific function/class by name, a
line range, or a full file. Use after analyze or search identifies a file of interest. For
supported languages (Go, Python, TypeScript, JavaScript, Java, C, C++, C#, Kotlin, Swift,
Rust) the response includes a symbols list of declarations with line ranges.

**Parameters:**

| Parameter                | Type    | Required | Default | Description                                                                                       |
|--------------------------|---------|----------|---------|---------------------------------------------------------------------------------------------------|
| repository               | string  | Yes      |         | Git URL of a public remote repository                                                             |
| path                     | string  | Yes      |         | File path relative to repository root                                                             |
| start_line               | integer | No       | 1       | First line to return (1-based). Cannot combine with symbol_name.                                  |
| end_line                 | integer | No       |         | Last line to return (inclusive). Cannot combine with symbol_name.                                  |
| max_lines                | integer | No       | 500     | Safety cap on lines returned (cap: 2000)                                                          |
| symbol_name              | string  | No       |         | Name of a function/method/class to extract — returns only that declaration. Cannot combine with start_line/end_line. |
| include_adjacent_symbols | boolean | No       | false   | When true and symbol_name is set, includes structurally related declarations (nearby siblings) alongside the target symbol. |

**Response shape:**
```json
{
  "repository": "https://github.com/example/repo",
  "commit": "abc123...",
  "path": "pkg/server.go",
  "language": "Go",
  "start_line": 1,
  "end_line": 50,
  "total_lines": 200,
  "content": "package pkg\n\nimport (\n...",
  "symbols": [
    {"name": "HandleRequest", "kind": "function", "start_line": 10, "end_line": 45}
  ]
}
```

When `symbol_name` and `include_adjacent_symbols` are both set, the response includes an
`adjacent_symbols` array with up to 6 neighboring declarations (3 above, 3 below):

```json
{
  "adjacent_symbols": [
    {
      "name": "RequestConfig",
      "kind": "type",
      "start_line": 5,
      "end_line": 9,
      "content": "type RequestConfig struct {\n\tTimeout int\n\tRetries int\n}",
      "relationship": "sibling"
    }
  ]
}
```

Each adjacent symbol is capped at 50 lines. If truncated, `"truncated": true` is set.

### code_get_files

Batch retrieve up to 10 files in a single call with a 5,000 total lines budget. Each file
supports optional line ranges. Failed files return per-file errors without blocking other files.

**Parameters:**

| Parameter  | Type   | Required | Description                                                                |
|------------|--------|----------|----------------------------------------------------------------------------|
| repository | string | Yes      | Git URL of a public remote repository                                      |
| paths      | array  | Yes      | Array of file requests (max 10). Each: `{"path": "...", "start_line": N, "end_line": N}` |

**Response shape:**
```json
{
  "repository": "https://github.com/example/repo",
  "commit": "abc123...",
  "total_lines_returned": 350,
  "lines_budget": 5000,
  "files": [
    {
      "path": "pkg/server.go",
      "start_line": 1,
      "end_line": 200,
      "total_lines": 200,
      "content": "package pkg\n..."
    },
    {
      "path": "missing.go",
      "error": "file_not_found"
    }
  ]
}
```

### code_file_tree

List directory structure of a remote public git repository. Filter by language, path, or
depth. Lightweight — no analysis overhead. Supports fuzzy file finding via the `query`
parameter — when set, returns a flat list of ranked matches instead of a tree.

**Parameters:**

| Parameter     | Type    | Required | Default | Description                                              |
|---------------|---------|----------|---------|----------------------------------------------------------|
| repository    | string  | Yes      |         | Git URL of a public remote repository                     |
| max_depth     | integer | No       |         | Maximum directory depth to return                         |
| language      | string  | No       |         | Filter to only show files of this language                |
| path_filter   | string  | No       |         | Glob pattern to restrict tree (e.g. "pkg/**", "src/**")   |
| query         | string  | No       |         | Fuzzy file finder query (e.g. "srvr.go"). Returns ranked matches instead of a tree. |
| max_results   | integer | No       | 20      | Maximum fuzzy matches to return (cap: 100). Only used with `query`. |
| include_stats | boolean | No       | false   | If true, include line count and file size for each file   |

**Response shape (tree mode — default):**
```json
{
  "repository": "https://github.com/example/repo",
  "commit": "abc123...",
  "total_files": 150,
  "files_shown": 150,
  "tree": [
    {"path": "pkg/server.go", "type": "file", "language": "Go", "lines": 200, "size": 5400},
    {"path": "pkg/", "type": "dir"}
  ]
}
```

**Response shape (fuzzy mode — when `query` is set):**
```json
{
  "repository": "https://github.com/example/repo",
  "commit": "abc123...",
  "total_files": 150,
  "files_shown": 3,
  "matches": [
    {"path": "pkg/server.go", "language": "Go", "score": 0.95},
    {"path": "pkg/service.go", "language": "Go", "score": 0.82},
    {"path": "cmd/srv.go", "language": "Go", "score": 0.71}
  ]
}
```

### code_get_findings

Returns detailed code quality findings including rule IDs, line numbers, severity (error,
warning, info), and categories (security, deprecated, safety, correctness, maintainability,
accessibility, modernization, performance, concurrency). Supports filtering by file path,
severity, and category.

**Parameters:**

| Parameter  | Type   | Required | Description                                                                 |
|------------|--------|----------|-----------------------------------------------------------------------------|
| repository | string | Yes      | Git URL of a public remote repository                                       |
| path       | string | No       | Filter findings to a specific file path                                     |
| severity   | string | No       | Filter by severity: `error`, `warning`, or `info`                           |
| category   | string | No       | Filter by category (e.g. `security`, `correctness`, `performance`)          |

**Response shape:**
```json
{
  "repository": "https://github.com/example/repo",
  "commit": "abc123...",
  "total_findings": 23,
  "findings": [
    {
      "path": "pkg/server.go",
      "line": 42,
      "rule_id": "G104",
      "severity": "warning",
      "category": "security",
      "message": "Unhandled error in call to fmt.Fprintf"
    }
  ]
}
```

---

## Query Syntax Reference

The `query` parameter for `code_search` supports:

- **Keywords**: ANDed by default. `handleRequest timeout` matches files containing both terms.
- **OR**: `handleRequest OR processRequest` matches either term.
- **NOT**: `handleRequest NOT test` excludes files matching the second term.
- **Phrases**: `"func handleRequest"` matches the exact phrase.
- **Regex**: `/handle[A-Z]\w+/` matches a regular expression pattern.
- **Fuzzy**: `handle~1` matches terms within edit distance 1.
- **In-query filters**:
  - `file:server.go` — restrict to files matching the pattern
  - `path:pkg/` — restrict to paths matching the prefix
  - `lang:Go` — restrict to a specific language
  - `ext:go` — restrict to a specific file extension

## Code Filters

The `code_filter` parameter restricts matches to specific code regions:

| Filter              | Description                                           | Use case                        |
|---------------------|-------------------------------------------------------|---------------------------------|
| `only-code`         | Matches only in code (excludes strings and comments)  | Find logic, not documentation   |
| `only-strings`      | Matches only inside string literals                   | Find hardcoded values, messages |
| `only-comments`     | Matches only inside comments                          | Find TODOs, documentation       |
| `only-declarations` | Matches only at declaration sites (func, class, etc.) | Find where something is defined |
| `only-usages`       | Matches only at usage sites (calls, references)       | Find where something is used    |

---

## Error Codes

| Code             | HTTP Status | Description                              | Suggestion                                  |
|------------------|-------------|------------------------------------------|---------------------------------------------|
| repo_not_found   | 404         | Repository URL not found or inaccessible | Check URL is correct and repo is public      |
| repo_too_large   | 413         | Repository exceeds size limit            | Try a smaller repository                     |
| repo_private     | 403         | Repository requires authentication       | Only public repositories are supported       |
| clone_timeout    | 504         | Clone operation timed out                | Try a smaller repository                     |
| clone_queue_full | 503         | Server busy cloning other repos          | Wait and retry in 30 seconds                 |
| rate_limited     | 429         | Too many requests per minute             | Reduce request frequency                     |
| invalid_params   | 400         | Invalid or missing parameters            | Check parameter types and required fields    |
| file_not_found   | 404         | File path not found in repository        | Check path is correct                        |
| file_too_large   | 413         | File exceeds size limit                  | Request a line range instead                 |
| tool_timeout     | 504         | Tool execution timed out                 | Try a simpler query or smaller repo          |
| internal_error   | 500         | Unexpected server error                  | Retry or report the issue                    |

---

## Free Tier Limits

searchcode is currently free. A free tier will always remain available. Paid tiers are planned for heavier usage. If you receive a 429 rate_limited response, wait briefly and retry.

---

## Enterprise / Private Instances

searchcode can be deployed on your own infrastructure for private code analysis. Self-hosted instances run the same tools with full access to your private git repositories.

**Deployment options:**
- Docker image with Helm chart for Kubernetes
- SSH key authentication for private git repos (mount keys as k8s Secrets)
- HTTPS token authentication via .netrc for GitHub/GitLab/Bitbucket personal access tokens
- Single-tenant model: one instance per team/org, git server controls repository permissions

Contact ben@boyter.org for enterprise deployment details.

---

## MCP Operational Protocol

See the MCP Operational Protocol section in [llms.txt](https://searchcode.com/llms.txt) for tool hallucination guards and redirection logic.

---

## Example Workflows

### Workflow 1: Understand a new codebase

1. **Analyze** the repository to get language breakdown and complexity:
   `code_analyze(repository="https://github.com/example/repo")`

2. **Browse** the file tree to understand project structure:
   `code_file_tree(repository="https://github.com/example/repo", max_depth=2)`

3. **Read** key files identified from the analysis:
   `code_get_file(repository="https://github.com/example/repo", path="README.md")`

### Workflow 2: Find and understand specific code

1. **Search** for the function or concept:
   `code_search(repository="https://github.com/example/repo", query="handleRequest", code_filter="only-declarations")`

2. **Get** the full file for context:
   `code_get_file(repository="https://github.com/example/repo", path="pkg/server.go", start_line=30, end_line=80)`

3. **Search** for usages of the same function:
   `code_search(repository="https://github.com/example/repo", query="handleRequest", code_filter="only-usages")`

### Workflow 3: Security review

1. **Analyze** to get security findings:
   `code_analyze(repository="https://github.com/example/repo", detail_level="full")`

2. **Search** for common vulnerability patterns:
   `code_search(repository="https://github.com/example/repo", query="exec OR eval OR system", code_filter="only-code")`

3. **Search** for hardcoded secrets:
   `code_search(repository="https://github.com/example/repo", query="/password|secret|api_key/", code_filter="only-strings")`

### Workflow 4: Evaluate a library before integrating it

1. **Analyze** the candidate repo to understand its tech stack, languages, and complexity:
   `code_analyze(repository="https://github.com/candidate/library")`

2. **Browse** the file tree to understand project layout and find key entry points:
   `code_file_tree(repository="https://github.com/candidate/library", max_depth=2)`

3. **Search** for the API surface — exported functions, types, and interfaces:
   `code_search(repository="https://github.com/candidate/library", query="export OR public", code_filter="only-declarations")`

4. **Read** specific implementations to check compatibility with your codebase:
   `code_get_file(repository="https://github.com/candidate/library", path="src/index.ts", symbol_name="createClient")`

5. **Check** code quality and findings to assess maintenance risk:
   `code_get_findings(repository="https://github.com/candidate/library", severity="error")`

### Workflow 5: Candidate portfolio evaluation

1. **Analyze** each of the candidate's public repos to build a language and complexity profile:
   `code_analyze(repository="https://github.com/candidate/repo1")`
   `code_analyze(repository="https://github.com/candidate/repo2")`

2. **Compare** language proficiency, complexity handling, and code quality across repos:
   `code_analyze(repository="https://github.com/candidate/repo1", detail_level="full")`

3. **Search** for engineering patterns and conventions — error handling, testing, documentation:
   `code_search(repository="https://github.com/candidate/repo1", query="error OR panic OR recover", code_filter="only-code")`
   `code_search(repository="https://github.com/candidate/repo1", query="test OR assert", code_filter="only-code")`

4. **Check** findings for quality signals — recurring issues, severity distribution:
   `code_get_findings(repository="https://github.com/candidate/repo1")`
   `code_get_findings(repository="https://github.com/candidate/repo2")`