> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qodo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP tools

> Reference for the dedicated tools that Qodo Context Engine exposes via the Model Context Protocol.

<Note>The Context Engine MCP is a standalone developer tool that exposes codebase intelligence via the Model Context Protocol. For the Context Engine as the core technology layer of the Qodo platform, see [Understanding the Context Engine](/core-concepts/context-engine).</Note>

The Context Engine MCP server exposes three tools that you call from your MCP client. For conceptual background, see the [Context Engine MCP overview](/developer-tools/context-engine-mcp).

| Tool            | What it does                               | Use it for                                                |
| --------------- | ------------------------------------------ | --------------------------------------------------------- |
| `deep_research` | Multi-step reasoning across services       | Refactors, architectural changes, impact analysis         |
| `context_ask`   | Evidence-based answers with code citations | Tracing flows, understanding implementations, scoped Q\&A |
| `get_context`   | Semantic search over indexed code          | Finding examples, exploring patterns, raw code retrieval  |

All three tools accept a `repositories` parameter to scope the search and, where applicable, a `session_id` parameter to maintain context across follow-up calls.

## deep\_research

The `deep_research` endpoint is an intelligent code analysis agent that goes beyond simple search to provide comprehensive understanding of your codebase. Think of it as having a senior architect who has thoroughly studied every line of your code and can answer complex questions about architecture, patterns, and implementation strategies.

### Key features

* **Code understanding:** Comprehends code logic, architecture, and design patterns
* **Cross-repository analysis:** Analyzes relationships between different parts of your codebase
* **Implementation planning:** Helps plan new features based on existing code patterns
* **Best practice recommendations:** Suggests improvements based on codebase analysis
* **Architecture insights:** Provides high-level understanding of system design

### Request format

```json theme={null}
{
  "tool": "deep_research",
  "parameters": {
    "input": "How does the authentication flow work across our microservices? What security measures are in place?",
    "repositories": ["backend/api", "frontend/app"],
    "session_id": "analysis-123"
  }
}
```

### Parameters

| Parameter      | Type   | Required | Description                                                                      |
| -------------- | ------ | -------- | -------------------------------------------------------------------------------- |
| `input`        | string | Yes      | Your question or research query. Be specific and detailed for best results.      |
| `repositories` | array  | No       | List of repository identifiers to scope the search. Format: `org/repo`           |
| `session_id`   | string | No       | Unique identifier to maintain context across multiple queries in a conversation. |

### Recommended query strategies

* **Be specific and detailed.** "How does user authentication work across our microservices?" provides richer insights than general queries.
* **Include context about your goals.** Mentioning why you need the information helps Deep Research tailor its analysis.
* **Leverage `session_id` for complex investigations.** Build on previous queries to dive deeper into specific areas.
* **Specify repositories for focused analysis.** When you know which repos are relevant, include them for more targeted results.
* **Ask "why" and "how" questions.** Deep Research excels at explaining design decisions and implementation reasoning.

**Avoid:**

* Simple keyword searches: use `get_context` instead
* Asking the agent to modify your code: `deep_research` analyzes and suggests code, it will not modify files
* Questions about external services not in your codebase
* Real-time data: it analyzes code structure, not runtime behavior

### Usage patterns

**Pattern 1: Architecture discovery**

When to use: Understanding how your system works.

```json theme={null}
{
  "input": "Explain our payment processing architecture. How do orders flow from the frontend through our services to the payment gateway?",
  "repositories": ["acme/frontend", "acme/api-gateway", "acme/payment-service"]
}
```

Returns: Complete flow diagram in text, service interactions, data transformations, error handling paths.

**Pattern 2: Security audit**

When to use: Evaluating security implementation.

```json theme={null}
{
  "input": "Analyze our JWT authentication implementation. Are we following security best practices? What vulnerabilities might exist?",
  "repositories": ["acme/auth-service", "acme/api-gateway"]
}
```

Returns: Security analysis, best practice violations, specific vulnerabilities, improvement recommendations.

**Pattern 3: Feature planning**

When to use: Before implementing new features.

```json theme={null}
{
  "input": "We need to add real-time notifications. Based on our current architecture, where should this be implemented and what patterns should we follow?",
  "repositories": ["acme/backend", "acme/frontend", "acme/websocket-service"]
}
```

Returns: Implementation strategy, integration points, consistent patterns to follow, potential challenges.

**Pattern 4: Performance analysis**

When to use: Identifying bottlenecks and optimization opportunities.

```json theme={null}
{
  "input": "What are the performance bottlenecks in our data processing pipeline? Focus on database queries and data transformations.",
  "repositories": ["acme/data-service", "acme/analytics-engine"]
}
```

Returns: Bottleneck identification, N+1 queries, inefficient algorithms, caching opportunities.

**Pattern 5: Dependency impact**

When to use: Before upgrading dependencies or making breaking changes.

```json theme={null}
{
  "input": "If we upgrade from Express 4 to Express 5, what parts of our codebase would be affected? What breaking changes should we prepare for?",
  "repositories": ["acme/api", "acme/admin-portal", "acme/webhook-service"]
}
```

Returns: Affected code sections, breaking changes, migration strategy, risk assessment.

**Pattern 6: Onboarding new developers**

When to use: Explaining complex parts of the codebase.

```json theme={null}
{
  "input": "Explain how our multi-tenant isolation works. How do we ensure data separation between clients?",
  "repositories": ["acme/core", "acme/tenant-service"]
}
```

Returns: Conceptual explanation, implementation details, key files and functions, potential gotchas.

**Pattern 7: Best practice validation**

When to use: Ensuring code quality and consistency.

```json theme={null}
{
  "input": "Are we following React best practices in our component architecture? Identify anti-patterns and suggest improvements.",
  "repositories": ["acme/web-app", "acme/mobile-web"]
}
```

Returns: Pattern analysis, anti-pattern identification, specific improvement suggestions, refactoring priorities.

***

## context\_ask

The `context_ask` endpoint is an intelligent codebase question-answering system that combines semantic search with expert-level code analysis. Think of it as having a principal software engineer who instantly understands your entire codebase and can provide detailed, evidence-based answers with actual code snippets and precise implementation details.

Unlike traditional documentation or search tools, `context_ask`:

* Provides evidence-based answers with actual code snippets and line numbers
* Combines semantic search with graph-based repository knowledge
* Analyzes code relationships and dependencies across your entire codebase
* Delivers expert-level explanations with complete implementation details
* Shows actual code proof for every claim, never just descriptions

### Request format

```json theme={null}
{
  "tool": "context_ask",
  "parameters": {
    "input": "How does user authentication work in our FastAPI application? Show me the complete flow from login request to JWT token generation.",
    "repositories": ["backend/auth", "api/v1"],
    "session_id": "engineering-review-789"
  }
}
```

### Parameters

| Parameter      | Type   | Required | Description                                                                      |
| -------------- | ------ | -------- | -------------------------------------------------------------------------------- |
| `input`        | string | Yes      | Your question or research query. Be specific and detailed for best results.      |
| `repositories` | array  | No       | List of repository identifiers to scope the search. Format: `org/repo`           |
| `session_id`   | string | No       | Unique identifier to maintain context across multiple queries in a conversation. |

### Response format

````json theme={null}
{
  "response": "The authentication system works through a multi-stage process:\n\n## Stage 1: Login Validation\n\n```python\n# From backend/auth/controllers/auth.py, lines 23-35\n@router.post('/login')\nasync def login(credentials: LoginRequest):\n    user = await User.find_by_email(credentials.email)\n    if not user or not verify_password(credentials.password, user.password_hash):\n        raise HTTPException(401, 'Invalid credentials')\n    return generate_jwt_response(user)\n```\n\nThis code first retrieves the user by email (line 25), then verifies the password using bcrypt (lines 26-27)..."
}
````

### Recommended query strategies

* **Ask specific technical questions.** "How does error handling work in the payment processing module?" rather than "Tell me about errors."
* **Request complete implementations.** Ask for end-to-end flows, not just isolated functions.
* **Focus on architectural patterns.** Questions about how components interact yield comprehensive answers.
* **Specify scope with repositories.** Target relevant codebases for focused, accurate responses.
* **Use session continuity.** Maintain `session_id` for follow-up questions on related topics.

### Usage examples

**Understanding authentication flow**

```json theme={null}
{
  "input": "Show me the complete user authentication flow from request to response, including middleware, validation, and token generation with exact code implementations",
  "repositories": ["api/auth", "middleware/security"],
  "session_id": "auth-analysis"
}
```

**Analyzing error handling patterns**

```json theme={null}
{
  "input": "How are database connection errors handled across our microservices? Show me the specific error handling code and retry mechanisms",
  "repositories": ["microservices/user", "microservices/order", "shared/db"],
  "session_id": "error-analysis"
}
```

**Exploring API design patterns**

```json theme={null}
{
  "input": "What validation patterns do we use for API endpoints? Show me examples of request validation, schema definitions, and error responses with actual code",
  "repositories": ["api/v1", "api/v2", "shared/validators"]
}
```

**Investigating performance optimizations**

```json theme={null}
{
  "input": "How do we implement caching in our application? Show me the caching layers, cache key strategies, and invalidation mechanisms with complete code examples",
  "repositories": ["services/cache", "api/controllers"],
  "session_id": "performance-review"
}
```

## get\_context

The `get_context` tool performs semantic search across one or more codebases to find relevant code snippets.

### Key features

* **Semantic search:** Uses vector embeddings to find conceptually similar code, not just keyword matches
* **Multi-repository support:** Search across multiple repositories simultaneously
* **Language filtering:** Filter results by programming language (Python, JavaScript, TypeScript, etc.)
* **Intelligent ranking:** Returns results ranked by relevance with configurable result limits

### Request format

```json theme={null}
{
  "tool": "get_context",
  "parameters": {
    "query": "authentication middleware implementation",
    "repositories": ["backend/api", "frontend/app"],
    "language": ["python", "typescript"],
    "max_results": 10
  }
}
```

### Parameters

| Parameter      | Type    | Required | Description                                                   |
| -------------- | ------- | -------- | ------------------------------------------------------------- |
| `query`        | string  | Yes      | Semantic search query describing the code you're looking for. |
| `repositories` | array   | No       | Target specific repositories. Format: `org/repo`              |
| `language`     | array   | No       | Filter results by programming language.                       |
| `max_results`  | integer | No       | Limit the number of results returned.                         |