MCP API Reference

Explore Maguyva's 11 MCP tools, their parameters, and when to use each. Check your connected client's tools/list response for the arguments available to you.

The tools are organized into 4 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, tool guidance, and feedback

For tools that accept a repository, use this repository identifier format: "owner/repo:branch". Branch defaults to main if not specified.

Omit repository when your MCP client supplies a request default or the key can access exactly one repository; otherwise pass it explicitly. Use repository_context(action="info", repository="owner/repo") to inspect how a repository resolves.

Use these formats when specifying a repository:

• With branch: "owner/repo:branch" - e.g., "owner/repository:develop"
• Default branch: "owner/repo" - uses main branch when no branch is specified "owner/repository"
• Request or sole-repository default: Omit repository when the MCP client supplies a request default or the key can access exactly one repository; otherwise pass it explicitly

Example prompts:

Ask about a specific repo:  "Search owner/my-repo for authentication middleware"
List accessible repos:      "What repositories can this Maguyva key access?"
Override for one query:     "Search owner/other-repo:develop for auth patterns"

Use language_filter on supported search modes. For text_pattern_search, choose search_scope="content"; for get_task_context, use scope="semantic" without seeds or related context.

• 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 285+ 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 October 21, 2026.

1. Use Explicit Overrides Deliberately: Omit the repository when your MCP client supplies a request default or the key can access exactly one repository; otherwise pass it explicitly.
2. Choose the Right Search Mode: Use intelligent_search with mode="auto" for most cases. Specify a mode when you know exactly what you need.
3. Leverage Language Filters: Use language_filter to narrow results and improve performance.
4. GraphRAG Boosting: GraphRAG importance boosting is off by default for semantic search (boost_by_importance=false) to keep ranking agent-safe. Pass boost_by_importance=true to enable centrality-aware re-ranking for architecture tours.
5. Repository Matching Is Case-Insensitive, Not Fuzzy: repository_context matches repository names case-insensitively — it does not correct typos. When the identity served differs from the one requested, metadata.resolution_reason reports "defaulted" (no branch was requested) or "fallback" (the requested branch or repository is unavailable). It is omitted when the request matched exactly.
6. Combine Tools: Use multiple API methods together for comprehensive analysis.
7. Handle Large Results: Use limit and tool-specific paging controls (for example line_start/line_end in get_file).
8. Use ask_maguyva for Tool Guidance: Call ask_maguyva with operation="guidance" and query="tool_selection" for tool-selection advice and examples. Use your local tools for calculations and string transformations.
9. Verify Impact Before and After Editing: Before editing a shared symbol, call dependency_search with analysis_type="impact" (or pass changed_paths for PR/diff impact) to see its blast radius. After editing, set verify_after_edit=true with targets and/or changed_paths for a compact re-check of the indexed graph. This does not read uncommitted local changes or replace local tests. Check indexed_commit_sha and index freshness before treating results as evidence for a new revision.

Tool responses contain common status fields and tool-specific payload fields at the top level. Searches return results; get_file returns content. Common fields include:

• status: String — "success" or "error". Degraded-match and freshness signals live in their own fields: metadata.resolution_reason under metadata, and top-level index_freshness.status on the repository_context info action.
• timing_ms: Elapsed tool execution time in milliseconds
• applied_filters: Effective request parameters recorded for the operation
• error: Error message string when status is "error"; it may include recovery guidance.
• metadata: Additional information about the operation (routing, caching, parameter adjustments)
• pagination: Present on cursor-paged collection responses — includes has_more and next_cursor. Ranked search windows are bounded top-K results, not exhaustive paginated collections.

Check the status field before processing a tool payload — its values are "success" or "error". Also handle MCP/JSON-RPC transport and request-validation errors, which may occur before a tool payload is produced. For degraded-match or freshness signals, read the dedicated field instead: metadata.resolution_reason under metadata, or top-level index_freshness.status on the repository_context info action (known/partial/unknown/unavailable).

1. Configure MCP Client: Point your MCP client to the Maguyva server endpoint
2. Confirm Repository Access: Use repository_context with list or info to inspect repositories available to the API key
3. Start Searching: Begin with intelligent_search and explore specialized tools as needed
4. Combine Tools: Use multiple tools together for comprehensive code analysis

For detailed integration instructions, see the installation guide.