# Greptile MCP

> Greptile connects your AI agent directly to private codebases (GitHub, GitLab). Ask natural language questions about any repository—like asking 'How does the auth flow work?'—and get instant answers complete with file paths and line numbers. It's a technical deep dive tool that lets you understand massive or unfamiliar code in minutes.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Tags:** codebase-intelligence, semantic-search, repository-indexing, natural-language-query, code-understanding, developer-productivity

## Description

You can connect your AI agent to Greptile and treat your entire collection of private repositories like a searchable document. Instead of spending hours digging through READMEs or jumping between services, just ask your agent what it needs to know—whether it's how the database connection is handled or which files manage user permissions. The system reads every indexed file and answers in plain English, pointing you right to the code that matters. This entire service lives inside Vinkius, letting you connect once from any compatible client and get access to this codebase intelligence alongside hundreds of other tools. You can even track usage with specific calls or tell the agent to check the current status of a repository before starting work.

## Tools

### delete_repository
Removes an indexed repository from the system.

### get_file_info
Retrieves specific details about a single file in your codebase.

### get_repository_status
Gets the current status of a repository index (e.g., processing, complete).

### get_greptile_usage
Checks how much API usage you've consumed for billing purposes.

### index_repository
Starts the process of adding a new GitHub or GitLab repository to your searchable index.

### list_repositories
Shows you all the repositories that are currently indexed and available for querying.

### query_codebase
Asks an AI question against the entire codebase to get a conceptual answer with code references.

### query_with_context
Continues an ongoing conversation, allowing subsequent questions to build on previous context and search results.

### reindex_repository
Triggers a full re-scan of an existing repository if the code has changed or needs updating.

### search_by_filepath
Runs a search that is limited strictly to files matching a specific path.

### search_codebase
Performs a broad, semantic search across the codebase for relevant code patterns or functions.

## Prompt Examples

**Prompt:** 
```
How does the authentication middleware work in our backend repository?
```

**Response:** 
```
Based on your indexed repository 'github:main:company/backend-api', the authentication middleware is implemented in `src/middleware/auth.ts` (lines 12-48). It uses a JWT-based flow: 1) Extracts the Bearer token from the Authorization header (line 18). 2) Verifies the token signature using the RS256 algorithm with a public key from `config/keys.ts` (line 24). 3) Attaches the decoded user payload to `req.user` (line 32). 4) Falls through to a 401 handler if verification fails (line 41). The middleware is applied globally in `src/app.ts` line 15 via `app.use(authMiddleware)`. Would you like to search for how specific routes use this middleware?
```

**Prompt:** 
```
Search for all files that import the database connection module and show me the file info.
```

**Response:** 
```
Semantic search for 'database connection import' found 8 files: 1) `src/services/user-service.ts` — imports `db` from `../config/database`, 42 functions. 2) `src/services/order-service.ts` — imports `db`, 28 functions. 3) `src/repositories/user-repo.ts` — imports `pool` from database config, 15 functions. 4) `src/migrations/001-initial.ts` — direct pg import for schema setup. 5-8) Four test files importing the test database mock. File info for `src/config/database.ts`: 89 lines, exports `db` (Knex instance) and `pool` (pg Pool), last indexed 2 hours ago. Would you like to query how the connection pooling is configured?
```

**Prompt:** 
```
Index our new frontend repository and check the indexing status.
```

**Response:** 
```
Repository submitted for indexing! Remote: github, Repository: company/frontend-app, Branch: main. Current status: 'processing' — 45% complete (scanning 1,247 files). Estimated time remaining: 3 minutes. Indexed repositories: 3 total. 1) 'company/backend-api' (main, completed, 892 files). 2) 'company/shared-lib' (main, completed, 234 files). 3) 'company/frontend-app' (main, processing, 45%). Once completed, you'll be able to query and search the frontend codebase. Would you like to check again in a few minutes?
```

## Capabilities

### Query Codebases
Ask natural language questions about your indexed code and receive accurate, referenced answers.

### Semantic Search
Find relevant functions, files, or patterns across entire repositories using abstract concepts instead of keywords.

### Targeted File Searches
Run searches restricted to a single file path when you know exactly where the code lives.

### Repository Management
List, inspect metadata for, and manage your indexed repositories.

### Indexing Control
Submit new GitHub or GitLab repos for indexing or trigger a full re-scan of existing code.

## Use Cases

### Debugging a Cross-Service Bug
A developer finds an intermittent bug in user authentication. Instead of reading every service, they ask their agent (using `query_codebase`) to trace the flow from token generation through the middleware. The agent identifies that `src/middleware/auth.ts` is using an outdated key format and points out lines 12-48.

### Onboarding a New Team Member
A new engineer joins the project. To understand the database structure, they ask their agent to find all files that import the connection module. The agent uses `search_codebase` and reports back on 8 different services that interact with the database.

### Auditing Dependencies
A code reviewer needs to confirm how many places a specific library is called. They use `search_by_filepath` combined with targeted queries, limiting their search to only files in the `/services` directory for precise results.

### Architectural Planning
An engineering manager needs an overview of the frontend's structure. They first use `list_repositories` to ensure the 'frontend-app' repo is indexed, then ask a high-level question using `query_codebase` about state management patterns.

## Benefits

- Stop searching documentation. Instead, ask your agent a question like 'Where is the user profile picture uploaded?' and it will use `query_codebase` to point you directly to the relevant service file.
- Need to know if a function uses a specific database connection? Use `search_by_filepath` or run a semantic search with `search_codebase` to find every instance of that pattern across multiple files.
- Don't waste time on outdated data. If your team updated the API, just trigger a re-index using `reindex_repository`, and all subsequent queries will use the freshest code context.
- Track your work flow better with `query_with_context`. Instead of asking ten separate questions, you can guide the agent through an entire architectural deep dive in one session.
- When onboarding a new developer to a massive system, simply running `list_repositories` gives you an overview, and then you use the MCP tools to onboard them by answering their specific technical queries.

## How It Works

The bottom line is: you index the code once, and then your AI client can query it endlessly without needing manual file navigation.

1. First, you subscribe to the Greptile MCP and provide your API key from the developer dashboard.
2. Next, tell your AI agent which repositories it needs to index. You can submit a new repo or trigger a re-index on an existing one.
3. Once indexed, simply ask your agent any question—like 'Show me how X component connects to Y service'—and get the code answer instantly.

## Frequently Asked Questions

**How do I query codebases with Greptile MCP?**
Just ask your agent a natural language question after indexing. For example: 'Show me the flow for processing payments.' The system uses `query_codebase` to give you a technical walkthrough.

**What if my code changes? Do I need to reindex using Greptile MCP?**
Yes. If you know the codebase has changed, always run `reindex_repository`. Otherwise, your answers might point to outdated logic or deprecated functions.

**Can I search only in one specific file path using Greptile MCP?**
Absolutely. Use the dedicated `search_by_filepath` tool when you need a very precise search, limiting results to files matching that exact path.

**What is the difference between searching and querying with Greptile MCP?**
Search functions (`search_codebase`) find relevant code snippets. Querying (`query_codebase`) uses those findings to provide a narrative answer or explain an architectural process.

**What should I use to check the status of a repository before running `query_codebase` with Greptile MCP?**
Run `get_repository_status`. This tool confirms if your repository is indexed and ready for queries. If the status shows 'processing,' you'll need to wait until it reports 'completed.' 

**How can I monitor API consumption and rate limits when using Greptile MCP?**
Use `get_greptile_usage`. This tool immediately displays your current API usage metrics and remaining rate limit allowance. It helps you manage costs and prevents service interruptions during long sessions.

**If I need to follow up on a previous answer, should I use `query_with_context` with Greptile MCP?**
Yes, that's the right way. `query_with_context` maintains the conversation history within your session. This allows your agent to remember details from earlier questions when answering follow-ups.

**What is the proper way to completely remove a repository from my indexed sources using Greptile MCP?**
You must run `delete_repository`. This tool permanently removes an entire project's data and index from your connected environment. Use it when you no longer need the code in the codebase understanding.

**Can I ask natural language questions about my codebase?**
Yes! The `query_codebase` tool sends a natural language question along with repository references and returns AI-generated answers with specific code references (file paths and line numbers). For follow-up questions, use `query_with_context` with the session ID from the previous response to maintain conversation continuity.

**Do I need to index my repository before querying it?**
Yes. Use `index_repository` with the remote host (github or gitlab), repository path (owner/repo), and branch name. Check indexing progress with `get_repository_status`. Once indexed, you can query and search the repository. Use `reindex_repository` to refresh the index after significant code changes.

**Can I search for specific code patterns across my repositories?**
Yes. The `search_codebase` tool performs semantic search across your indexed repositories to find relevant files and functions. For targeted results, use `search_by_filepath` to narrow the search to a specific file path. Use `get_file_info` to retrieve indexed metadata for any file.