MCP API Reference

Complete reference for all 11 customer-facing Maguyva MCP tools. Each tool includes parameters, usage guidance, and best-for recommendations.

API Overview #

The Maguyva MCP API currently exposes 11 customer-facing tools across 4 main categories:

Core Search Tools - Advanced search capabilities across your codebase
Structural & Graph Tools - AST queries, symbol lookup, and dependency analysis
Code Analysis Tools - Deep code analysis and relationship mapping
System & Utility Tools - Repository context, deterministic compute, and guidance

All tools use a consistent repository identifier format: "owner/repo:branch". Branch defaults to main if not specified.

Repository Parameter Format #

All MCP tools use this repository identifier format:

With branch: "owner/repo:branch" - e.g., "owner/repository:develop"
Default branch: "owner/repo" - e.g., "owner/repository" (uses main branch)
Session context: Set default repository via repository_context tool

Example prompts:

Ask about a specific repo:  "Search owner/my-repo for authentication middleware"
Set a session default:      "Use owner/my-repo as my default repository"
Override for one query:     "Search owner/other-repo:develop for auth patterns"

Language Filtering #

All search tools support filtering results by programming language:

language_filter="python" - Filter to Python files only
language_filter="typescript" - Filter to TypeScript files only
Case-sensitive: Use lowercase language names
Default: Empty string (no filtering) - returns results from all languages
Supported coverage: Language filters work across the full 229+ supported languages and text-based technologies. See compatibility for the full list.

"Find authentication middleware in Python files only"
"Search for database connections in TypeScript"

API reference generated from source on March 27, 2026.

Core Search Tools #

intelligent_search Stable

START HERE — Multi-modal code search that auto-routes across semantic, text, AST, and graph. Combines search strategies with importance-aware ranking and dead code detection. Start here — auto-routes your question to the best search mode.

Parameters:

Parameter	Type	Required	Default	Description
`query`	`str`	No
`repository`	`str`	No		'owner/repo' or 'owner/repo:branch'. Session default if omitted.
`branch`	`str`	No		Branch name (leave blank to use the session or repository default).
`mode`	`Literal[auto, semantic, text, ast, graph, hybrid]`	No	`auto`
`quality`	`str`	No	`balanced`
`limit`	`int`	No	-	Max results
`include_content`	`bool`	No	-
`language_filter`	`str`	No
`path_filter`	`str`	No
`boost_by_importance`	`bool \| None`	No	-	Rank results higher if they have many dependencies (high PageRank). Use for finding core utilities, widely-used interfaces, or important code.
`orphans`	`bool`	No		Return symbols with no incoming references (potential dead code). Useful for cleanup but may include decorators, inner functions, CLI entry points.
`min_coupling_score`	`float`	No	`0`	Minimum bridging centrality threshold (0.0-1.0). Higher values only return coupling hotspots that connect different code communities.
`include_community_context`	`bool`	No	-	Include related symbols from the same code community for broader context. Helpful when exploring how a feature or module works.

Timeout: 60s

semantic_search Stable

Find code by meaning using vector similarity. Use for conceptual queries like 'authentication flow' or 'error handling pattern' when you don't know exact text. Use when you need to find code by meaning rather than exact text.

Parameters:

Parameter	Type	Required	Default	Description
`query`	`str`	No
`repository`	`str`	No		'owner/repo' or 'owner/repo:branch'. Session default if omitted.
`branch`	`str`	No		Branch name (leave blank to use the session or repository default).
`limit`	`int`	No	-	Max results (read-only)
`similarity_threshold`	`float`	No	-
`depth`	`str`	No
`include_content`	`bool`	No	-
`boost_by_importance`	`bool`	No	-
`language_filter`	`str`	No
`path_filter`	`str`	No

Timeout: 30s

text_pattern_search Stable

Search code by exact text, fuzzy match, or regex pattern. Use for known strings, error messages, identifiers, and grep-like queries. Use for regex patterns, exact strings, or when you know the specific text to find.

Parameters:

Parameter	Type	Required	Default	Description
`query`	`str`	No
`repository`	`str`	No		'owner/repo' or 'owner/repo:branch'. Session default if omitted.
`branch`	`str`	No		Branch name (leave blank to use the session or repository default).
`search_scope`	`Literal[content, symbols, files, auto]`	No	`content`	Search scope: 'content' (code chunks, default), 'symbols' (function/class names), 'files' (file paths), 'auto' (system chooses).
`mode`	`Literal[exact, fuzzy, regex]`	No	`exact`	Search mode: 'exact' (literal match), 'fuzzy' (similarity-based), 'regex' (pattern match). Note: fuzzy mode with search_scope='content' (the default) may route to semantic search for performance (23s→500ms). When routed, response metadata includes search_type='semantic_routed'.
`case_sensitive`	`bool`	No
`language_filter`	`str`	No
`limit`	`int`	No	-	Max results
`path_filter`	`str`	No

Timeout: 30s

Structural & Graph Tools #

structural_search Stable

Search code structure by AST node type, symbol name, decorator, or base class. Use when you need structural precision — find all classes inheriting from X, functions with @decorator, or specific AST patterns. Use for AST pattern matching to find code by structure rather than text.

Parameters:

Parameter	Type	Required	Default	Description
`pattern`	`str`	No
`query_type`	`Literal[node_type, name_pattern, parent_child]`	No	`node_type`	Search mode (auto-detected when omitted). Inferred from provided parameters: name_pattern → 'name_pattern', parent_type → 'parent_child', otherwise 'node_type'. Set explicitly to override auto-detection.
`node_type`	`str`	No
`name_pattern`	`str`	No
`parent_type`	`str`	No
`preset`	`str`	No
`decorator`	`str`	No
`callee_text`	`str`	No
`callee_name`	`str`	No
`field_role`	`str`	No
`ltree_ancestor`	`str`	No
`ltree_descendant`	`str`	No
`definition_name`	`str`	No
`base_class`	`str`	No
`min_depth`	`int`	No	`0`
`max_depth`	`int`	No	`0`
`repository`	`str`	No
`branch`	`str`	No
`limit`	`int`	No	-	Max results (capped at 100-200 based on query type)
`language_filter`	`str`	No
`path_filter`	`str`	No

Timeout: 30s

dependency_search Stable

Graph-powered dependency and relationship analysis with centrality ranking. Use for finding dependencies, impact radius, module boundaries, orphan detection, and coupling hotspots. Use for import tracking, caller/callee discovery, and coupling assessment.

Parameters:

Parameter	Type	Required	Default	Description
`analysis_type`	`str`	No	`centrality`	Query mode: centrality\|dependencies\|modules\|impact_radius\|orphans
`repository`	`str`	No		'owner/repo' or 'owner/repo:branch'. Session default if omitted.
`branch`	`str`	No		Branch name (leave blank to use the session or repository default).
`symbol_types`	`tuple[str, Ellipsis] \| list[str]`	No		Symbol type filter
`limit`	`int`	No	-	Max graph nodes
`min_centrality`	`float`	No	`0`
`find_similar_patterns`	`bool`	No
`target`	`str \| None`	No
`direction`	`str`	No	`both`	Traversal direction: 'outgoing' = what this symbol depends on (its dependencies), 'incoming' = what depends on this symbol (its dependents), 'both' = full context. Use 'incoming' to find all callers/users of a symbol.
`depth`	`int \| str \| None`	No		Traversal depth (1-3, or aliases: shallow, balanced, deep)
`include_metrics`	`bool \| None`	No		Include graph metrics
`language_filter`	`str`	No
`relationship_types`	`tuple[str, Ellipsis] \| list[str] \| None`	No		Explicit edge types (e.g., CALL, IMPORT). Overrides analysis_type if provided.
`exact_match`	`bool`	No		Require exact symbol name match (case-insensitive). Disables fuzzy matching
`path_filter`	`str`	No
`exclude_test_paths`	`bool`	No		Exclude common test/fixture paths from results. When true, filters paths matching fixtures/, test_fixtures/, __fixtures__/. Default false (no filtering).

Timeout: 60s

Code Analysis Tools #

find_symbol Stable

Look up symbol definitions and references with graph metrics. Use when you know the exact function, class, or variable name and need its location, callers, or importance.

Parameters:

Parameter	Type	Required	Default	Description
`symbol_name`	`str`	No
`symbol_type`	`str`	No
`repository`	`str`	No		'owner/repo' or 'owner/repo:branch'. Session default if omitted.
`branch`	`str`	No		Branch name (leave blank to use the session or repository default).
`scope`	`str`	No	`both`
`limit`	`int`	No	-	Max results
`find_similar`	`bool`	No
`include_metrics`	`bool`	No
`high_impact`	`bool`	No
`in_cycle`	`bool`	No
`path_filter`	`str`	No

Timeout: 30s

analyze_dependencies Stable

Analyze import chains and dependency relationships for a symbol or directory. Use for understanding module coupling and dependency depth. Use for comprehensive dependency analysis of a file or symbol.

Parameters:

Parameter	Type	Required	Default	Description
`target`	`str`	Yes	-	Symbol or module name to analyze (e.g., 'SupabaseService', 'get_config'). Use symbol names for reliable results.
`analysis_type`	`str`	No	`imports`
`repository`	`str`	No		'owner/repo' or 'owner/repo:branch'. Session default if omitted.
`branch`	`str`	No		Branch name (leave blank to use the session or repository default).
`depth`	`int`	No	`1`	Analysis depth (supports aliases: auto, shallow/quick=1, balanced/medium=2, deep/thorough=3)
`direction`	`str`	No	`both`
`limit`	`int`	No	-	Max relationships
`include_metrics`	`bool`	No
`language_filter`	`str`	No
`relationship_types`	`list[str] \| tuple[str, Ellipsis] \| None`	No		Explicit edge types (e.g., CALL, IMPORT). Overrides analysis_type if provided.

Timeout: 60s

get_task_context Stable

Gather multi-layered context for a task description. Combines semantic search, symbol lookup, and dependency analysis in one call. Use when working on a specific task to get relevant context snippets.

Parameters:

Parameter	Type	Required	Default	Description
`task_description`	`str`	Yes	-
`repository`	`str`	No		'owner/repo' or 'owner/repo:branch'. Session default if omitted.
`branch`	`str`	No		Branch name (leave blank to use the session or repository default).
`scope`	`list[str] \| str`	No
`language_filter`	`str`	No
`include_related_context`	`bool`	No		Include related context (neighbors + community members)
`limit`	`int \| None`	No	`0`	Max context items

Timeout: 60s

get_file Stable

Retrieve file content with optional line range and metadata. Use for reading specific source files or code sections. Use to read a specific file's content from the indexed repository.

Parameters:

Parameter	Type	Required	Default	Description
`file_path`	`str`	Yes	-
`repository`	`str`	No		'owner/repo' or 'owner/repo:branch'. Session default if omitted.
`branch`	`str`	No		Branch name (leave blank to use the session or repository default).
`line_range`	`list[int] \| dict[str, int] \| str \| None`	No		[start, end] or 'start-end'
`max_tokens`	`int`	No	-
`include_metadata`	`bool`	No	`true`
`include_syntax_highlighting`	`bool`	No
`chunk_start`	`int`	No	`0`

Timeout: 60s

System & Utility Tools #

repository_context Stable

Manage repository session context — list, set, set_default, or inspect available repositories and branches. Call this first to set your session's default repository.

Parameters:

Parameter	Type	Required	Default	Description
`action`	`Literal[list, set, set_default, info]`	Yes	-
`repository`	`str`	No
`branch`	`str`	No
`pattern`	`str \| None`	No
`include_stats`	`bool`	No		Include statistics
`limit`	`int`	No	-	Max repositories
`include_graph_metrics`	`bool`	No		Include graph topology metrics in info response

Timeout: 30s

ask_maguyva Stable

Guidance and deterministic compute (hash, base64, uuid, json, math). Use 'guidance' operation for tool usage help.

Parameters:

Parameter	Type	Required	Default	Description
`operation`	`str`	Yes	-	One of guidance, hash, base64, uuid, json, math
`topic`	`str`	No
`text`	`str`	No
`hash_type`	`str`	No
`base64_operation`	`str`	No
`uuid_version`	`int`	No	`0`
`uuid_namespace`	`str`	No
`uuid_name`	`str`	No
`json_text`	`str`	No
`json_indent`	`int`	No	`0`
`math_operation`	`str`	No
`math_value`	`float`	No	`0`
`math_value_a`	`int`	No	`0`
`math_value_b`	`int`	No	`0`
`math_exponent`	`float`	No	`0`

Timeout: 30s

Best Practices #

Use Repository Context: Set a session default repository to avoid repeating it in every call.
Choose the Right Search Mode: Use intelligent_search with mode="auto" for most cases. Specify a mode when you know exactly what you need.
Leverage Language Filters: Use language_filter to narrow results and improve performance.
GraphRAG Boosting: GraphRAG importance boosting is enabled by default for semantic search. Set boost_by_importance=False to disable it for pure vector similarity.
Fuzzy Resolution Is Built-In: repository_context automatically resolves close repository matches to handle minor typos.
Combine Tools: Use multiple API methods together for comprehensive analysis.
Handle Large Results: Use limit and tool-specific paging controls (for example chunk_start in get_file).
Deterministic Operations: Use ask_maguyva for hash, base64, JSON, and math operations to avoid hallucination.

Performance Characteristics #

Operation	Latency
Semantic search	Sub-second
Text search	Sub-second
Structural search	Fast (optimized AST indexing)
Dependency search	Efficient (depth limiting)
File retrieval	Near-instant
Repository context	Cached
ask_maguyva (deterministic ops)	Near-instant (local compute)

Error Handling #

All API methods return structured responses with:

success: Boolean indicating operation success
data: Result data when successful
error: Error message if operation failed
metadata: Additional information about the operation

Always check the success field before processing results.

Getting Started #

Configure MCP Client: Point your MCP client to the Maguyva server endpoint
Set Repository Context: Use repository_context to set your default repository
Start Searching: Begin with intelligent_search and explore specialized tools as needed
Combine Tools: Use multiple tools together for comprehensive code analysis

For detailed integration instructions, see the installation guide.