Skip to main content

​
What is MCP?

Model Context Protocol (MCP) is an open protocol that allows AI assistants to connect to external tools and data sources. Nogic exposes its code intelligence through MCP, so AI agents like Claude and Cursor can query your codebase in real-time.

​
How It Works

  1. You index your codebase using the Nogic CLI (nogic watch or nogic sync)
  2. Your AI agent connects to Nogic’s MCP server using your API key
  3. The agent calls tools like find_symbol or before_writing as it works
  4. Nogic queries your code graph and returns results to the agent

​
Project ID

All MCP tools require a project_id parameter. Your AI agent reads this from .nogic/config.json in your project root: 
{
  "project_id": "abc123-def456-..."
}
Make sure you’ve run nogic init before using MCP tools.

​
Setup Guides

Claude Code

Set up with Claude Code CLI

Cursor

Set up with Cursor IDE

Windsurf

Set up with Windsurf

Other Editors

VS Code, Antigravity, Claude Desktop, and more

​
Tools Reference

Nogic provides 22 MCP tools organized into ten categories.

​
Before Writing Code

These tools should be called before writing any new code to prevent duplication and enforce naming conventions.

​
before_writing

Call this FIRST before writing any new code. Combines similarity search and convention detection in a single call. If similar code already exists, the agent should reuse it instead of writing a duplicate.
ParameterTypeRequiredDescription
project_idstringYesUUID from .nogic/config.json
descriptionstringYesWhat you’re about to write (e.g., “email validation function”)
Returns: Similar existing code (if any), naming conventions (camelCase vs snake_case), and plain-English guidance.

​
find_similar

Find existing code similar to a natural language description. Use before_writing instead when writing new code — this tool is for targeted searches when you need more results or a different similarity threshold.
ParameterTypeRequiredDefaultDescription
project_idstringYes—UUID from .nogic/config.json
querystringYes—Natural language description
max_resultsintNo5Maximum results to return
thresholdfloatNo0.7Minimum similarity score (0–1)

​
get_conventions

Detect naming conventions used across the codebase. Usually, before_writing is sufficient — use this directly only when you need a detailed breakdown by category.
ParameterTypeRequiredDescription
project_idstringYesUUID from .nogic/config.json
Returns: Dominant naming patterns for functions (e.g., snake_case, camelCase) and classes (e.g., PascalCase) with confidence scores.

​
Symbol Discovery

​
find_symbol

The primary code discovery tool. Locate any function, class, or method by name with fuzzy matching. Returns exact file:line locations with caller/usage stats and importance context.
ParameterTypeRequiredDefaultDescription
project_idstringYes—UUID from .nogic/config.json
namestringOne of name/node_id—Symbol name (partial match OK)
node_idstringOne of name/node_id—Exact node ID from previous results
node_typestringNo—Filter by type: Function, Class, Method
include_statsboolNotrueInclude caller/usage counts
max_resultsintNo10Maximum results to return
Returns: Matched symbols with file path, line numbers, signature, docstring, decorators, and context (callers, callees, usages, test count, importance level).

​
Code Relationships

These tools require a node_id obtained from find_symbol results.

​
get_references

Find all callers of a symbol. Returns every function that calls the target with file:line locations and distribution analysis.
ParameterTypeRequiredDefaultDescription
project_idstringYes—UUID from .nogic/config.json
node_idstringYes—Symbol’s ID (from find_symbol)
max_resultsintNo15Maximum callers to return
Returns: List of callers, distribution across modules, and a usage pattern description (e.g., “Widely used: 12 callers across 5 modules”).

​
get_dependencies

Find everything a symbol depends on. Returns every function the target calls with file:line locations.
ParameterTypeRequiredDefaultDescription
project_idstringYes—UUID from .nogic/config.json
node_idstringYes—Symbol’s ID (from find_symbol)
max_resultsintNo15Maximum dependencies to return
Returns: List of callees, modules involved, and a complexity pattern (e.g., “Orchestrator: calls 15 functions across 6 modules”).

​
assess_impact

Assess the risk of modifying a symbol. Returns the blast radius (affected files and functions) and test coverage information.
ParameterTypeRequiredDefaultDescription
project_idstringYes—UUID from .nogic/config.json
node_idstringYes—Symbol’s ID (from find_symbol)
depthintNo2How many levels of callers to check
Returns: Risk level (LOW, MEDIUM, or HIGH), number of affected functions and files, test file coverage in the blast radius.

​
File & Directory Analysis

​
list_files

List all indexed files in the project, grouped by area (core, tests, examples) with language breakdown.
ParameterTypeRequiredDescription
project_idstringYesUUID from .nogic/config.json
Returns: Total file count, language breakdown, directory listing, and all file paths.

​
get_directory_structure

Browse the project directory tree incrementally. Start with an empty path for the project root.
ParameterTypeRequiredDefaultDescription
project_idstringYes—UUID from .nogic/config.json
pathstringNo""Directory path to browse (empty = root)
Returns: Immediate children (subdirectories and files) at the given path.

​
get_file_structure

Get the outline of a file — every class, function, and component with line numbers and signatures. Useful for understanding a file’s structure before reading the whole thing.
ParameterTypeRequiredDescription
project_idstringYesUUID from .nogic/config.json
file_pathstringYesPath to the file (relative to project root)
Returns: List of symbols with names, types, signatures, and line numbers. Includes summary counts for classes, functions, and components.

​
get_file_dependencies

Get import/export relationships for a file. Shows what files it imports and what files import it, plus the file’s architectural role.
ParameterTypeRequiredDescription
project_idstringYesUUID from .nogic/config.json
file_pathstringYesPath to the file (relative to project root)
Returns: List of imported files, list of importing files, and an architectural role classification (e.g., UTILITY, HIGH-LEVEL, ENTRY POINT, STANDALONE, INTERMEDIATE).

​
Class Analysis

​
get_class_structure

Get a class’s full API: methods with signatures, instance variables, class variables, and inheritance hierarchy.
ParameterTypeRequiredDescription
project_idstringYesUUID from .nogic/config.json
node_idstringYesThe class node ID (from find_symbol)
Returns: Class location and docstring, all methods with signatures, instance and class variables, ancestor/descendant hierarchy, and metrics (method count, public methods, variable count).

​
find_tests

Find tests for a specific function or method. Returns all tests with file:line locations and a coverage assessment.
ParameterTypeRequiredDefaultDescription
project_idstringYes—UUID from .nogic/config.json
node_idstringYes—Function/method node ID (from find_symbol)
include_indirectboolNofalseInclude tests that call the function indirectly
Returns: List of test functions, whether each is a direct or indirect caller, coverage assessment (NO TESTS, INDIRECT ONLY, MINIMAL, GOOD), and test file paths.

​
Framework Patterns

​
find_by_framework

Find API routes, models, controllers, services, tests, and other framework-specific patterns.
ParameterTypeRequiredDefaultDescription
project_idstringYes—UUID from .nogic/config.json
pattern_typestringYes—One of: route, model, controller, service, test, auth, task
frameworkstringNo—Filter by framework (e.g., fastapi, flask, django, nestjs)
http_methodstringNo—For routes only: filter by HTTP method (GET, POST, PUT, DELETE)
Returns: Matched patterns grouped by area (core, tests), with file:line locations. For routes, includes HTTP method and route path.

​
Error Analysis

​
find_error_paths

Find functions that raise a given exception type and trace which callers handle or propagate them.
ParameterTypeRequiredDefaultDescription
project_idstringYes—UUID from .nogic/config.json
error_typestringNo""Exception class name to search for (empty = all)
Returns: Functions that raise the exception, callers that handle it, and callers that let it propagate.

​
get_unhandled_errors

Find exceptions that propagate up without any caller catching them. High-value for identifying potential crash paths.
ParameterTypeRequiredDescription
project_idstringYesUUID from .nogic/config.json
Returns: Unhandled exception paths with the raising function, exception type, and the call chain where no handler exists.

​
Project Overview

​
describe_project

Get a high-level overview of the codebase: size, language composition, project type, and scale.
ParameterTypeRequiredDescription
project_idstringYesUUID from .nogic/config.json
Returns: File, function, class, and component counts. Project type classification (Frontend/React, Object-oriented, Functional/procedural, Mixed) and scale (Small, Medium, Large, Very large).

​
resolve_project

Resolve a workspace path to a project_id when ~/.nogic/projects.json is unavailable.
ParameterTypeRequiredDescription
workspace_pathstringYesAbsolute path to the workspace root
machine_idstringNoUUID from ~/.nogic/machine_id
Returns: The project_id for the given workspace path.

​
Code Review

​
review_step

Step-by-step code review investigation tool. Call repeatedly to investigate code changes. The server returns prioritized assignments with node_ids you can pass directly to other tools.
ParameterTypeRequiredDescription
project_idstringYesUUID from .nogic/config.json
thoughtstringYesCurrent investigation step
step_numberintYesCurrent step (1-based)
total_stepsintYesEstimated total steps
next_step_neededboolYesWhether more investigation is needed
file_pathslistFirst call onlyChanged file paths
Returns: Prioritized investigation assignments, coverage tracking, and phase guidance (gathering → analyzing → synthesizing).

​
finalize_review

Write .nogic/review.json with the complete review results. Call after review_step’s synthesizing phase.
ParameterTypeRequiredDescription
project_idstringYesUUID from .nogic/config.json
summarystringYesWhat changed and why it matters
ratingintYes1–5 (5 = definitely mergeable)
annotationslistYesList of findings with risk levels
Returns: Writes .nogic/review.json with server-computed review depth.

​
Canvas & Visualization

​
agent_canvas

Create interactive visual diagrams and flowcharts. Build incrementally by adding elements, connections, groups, and narrative steps.
ParameterTypeRequiredDescription
project_idstringYesUUID from .nogic/config.json
modestringNo"create" or "build" (build incrementally, then create)
Returns: Writes canvas spec file for interactive visualization.

​
agent_canvas_sequence

Create sequence diagrams showing participant interactions and message flows.
ParameterTypeRequiredDescription
project_idstringYesUUID from .nogic/config.json
titlestringNoDiagram title
modestringNo"create" or "build"
Returns: Writes sequence diagram spec file for interactive visualization.
  1. Start a session: Call describe_project to understand the codebase
  2. Before writing code: Call before_writing with a description of what you plan to create
  3. Find existing code: Use find_symbol to locate functions and classes by name
  4. Understand relationships: Use get_references and get_dependencies with node_id from find_symbol
  5. Before refactoring: Call assess_impact to understand the blast radius
  6. Check test coverage: Use find_tests to see if a function has tests before modifying it
  7. Find crash paths: Use get_unhandled_errors to identify potential unhandled exceptions
  8. Review changes: Use review_step repeatedly, then finalize_review to generate a structured review