MCP Integration

Navegador ships a built-in Model Context Protocol server. When running in MCP mode, all navegador commands become callable tools that agents can invoke with structured input and receive structured output.

---

CLI vs MCP: when to use which

The primary interface for agents is the CLI , not MCP. Here's why:

| CLI | MCP
---|---|---
Token cost | Low — agent calls a shell tool, gets back only what it asked for | Higher — MCP tool calls involve protocol overhead
Setup | None beyond installing navegador | Requires MCP config in agent settings
Best for | Agent hooks, shell scripts, CI | Interactive sessions in Claude / Cursor
Output formats | JSON, markdown, rich terminal | Structured JSON always

Use MCP when you want navegador tools available as first-class tool calls in an interactive Claude or Cursor session. Use the CLI (via agent hooks) for automated background sync and pre-edit context loading.

---

Starting the MCP server

navegador mcp

With a custom database path:

navegador mcp --db .navegador/navegador.db

The server speaks MCP over stdio. It does not bind a port.

---

Agent configuration

Add to your project's .claude/settings.json:

{
  "mcpServers": {
    "navegador": {
      "command": "navegador",
      "args": ["mcp"],
      "env": {
        "NAVEGADOR_DB": ".navegador/navegador.db"
      }
    }
  }
}

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "navegador": {
      "command": "navegador",
      "args": ["mcp", "--db", "/path/to/project/.navegador/navegador.db"]
    }
  }
}

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "navegador": {
      "command": "navegador",
      "args": ["mcp"],
      "env": {
        "NAVEGADOR_DB": ".navegador/navegador.db"
      }
    }
  }
}

---

Available MCP tools

All tools accept and return JSON.

Tool	Equivalent CLI	Description
ingest	navegador ingest	Ingest a repo into the graph
context	navegador context	File-level context bundle
function	navegador function	Function with call graph
class	navegador class	Class with hierarchy
explain	navegador explain	Universal node lookup
search	navegador search	Text search across graph
query	navegador query	Raw Cypher passthrough

Tool input schemas

ingest

{ "path": "./repo", "clear": false }

context

{ "file": "src/auth/service.py", "format": "json" }

function

{ "name": "validate_token", "file": "src/auth/service.py", "depth": 2 }

class

{ "name": "PaymentProcessor", "file": "src/payments/processor.py" }

explain

{ "name": "AuthService", "file": "src/auth/service.py" }

search

{ "query": "rate limit", "all": true, "docs": false, "limit": 20 }

query

{ "cypher": "MATCH (f:Function) RETURN f.name LIMIT 10" }

---

When MCP makes sense

• You are in an interactive Claude or Cursor session and want to call explain, search, or function without dropping to a terminal
• You want navegador tools auto-discovered by the agent without writing custom tool definitions
• You are building an agent workflow that dynamically queries the graph mid-task

For automated background tasks (re-ingest on file save, sync on pull), use the CLI via agent hooks instead.

Z c