Navegador

navegador / docs / guide / mcp-integration.md
Source Blame History 221 lines
ce0374a… lmata 1 # MCP Integration
ce0374a… lmata 2
ce0374a… lmata 3 Navegador ships a built-in [Model Context Protocol](https://modelcontextprotocol.io) server. When running in MCP mode, all navegador commands become callable tools that agents can invoke with structured input and receive structured output.
ce0374a… lmata 4
ce0374a… lmata 5 ---
ce0374a… lmata 6
ce0374a… lmata 7 ## CLI vs MCP: when to use which
ce0374a… lmata 8
ce0374a… lmata 9 The primary interface for agents is the **CLI**, not MCP. Here's why:
ce0374a… lmata 10
ce0374a… lmata 11 | | CLI | MCP |
ce0374a… lmata 12 |---|---|---|
ce0374a… lmata 13 | Token cost | Low — agent calls a shell tool, gets back only what it asked for | Higher — MCP tool calls involve protocol overhead |
ce0374a… lmata 14 | Setup | None beyond installing navegador | Requires MCP config in agent settings |
ce0374a… lmata 15 | Best for | Agent hooks, shell scripts, CI | Interactive sessions in Claude / Cursor |
ce0374a… lmata 16 | Output formats | JSON, markdown, rich terminal | Structured JSON always |
ce0374a… lmata 17
ce0374a… lmata 18 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.
ce0374a… lmata 19
ce0374a… lmata 20 ---
ce0374a… lmata 21
ce0374a… lmata 22 ## Starting the MCP server
ce0374a… lmata 23
ce0374a… lmata 24 ```bash
ce0374a… lmata 25 navegador mcp
ce0374a… lmata 26 ```
ce0374a… lmata 27
ce0374a… lmata 28 With a custom database path:
ce0374a… lmata 29
ce0374a… lmata 30 ```bash
ce0374a… lmata 31 navegador mcp --db .navegador/navegador.db
ce0374a… lmata 32 ```
ce0374a… lmata 33
ce0374a… lmata 34 The server speaks MCP over stdio. It does not bind a port.
ce0374a… lmata 35
ce0374a… lmata 36 ---
ce0374a… lmata 37
ce0374a… lmata 38 ## Agent configuration
ce0374a… lmata 39
ce0374a… lmata 40 === "Claude Code"
ce0374a… lmata 41
ce0374a… lmata 42 Add to your project's `.claude/settings.json`:
ce0374a… lmata 43
ce0374a… lmata 44 ```json
ce0374a… lmata 45 {
ce0374a… lmata 46 "mcpServers": {
ce0374a… lmata 47 "navegador": {
ce0374a… lmata 48 "command": "navegador",
ce0374a… lmata 49 "args": ["mcp"],
ce0374a… lmata 50 "env": {
ce0374a… lmata 51 "NAVEGADOR_DB": ".navegador/navegador.db"
ce0374a… lmata 52 }
ce0374a… lmata 53 }
ce0374a… lmata 54 }
ce0374a… lmata 55 }
ce0374a… lmata 56 ```
ce0374a… lmata 57
ce0374a… lmata 58 === "Claude Desktop"
ce0374a… lmata 59
ce0374a… lmata 60 Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
ce0374a… lmata 61
ce0374a… lmata 62 ```json
ce0374a… lmata 63 {
ce0374a… lmata 64 "mcpServers": {
ce0374a… lmata 65 "navegador": {
ce0374a… lmata 66 "command": "navegador",
ce0374a… lmata 67 "args": ["mcp", "--db", "/path/to/project/.navegador/navegador.db"]
ce0374a… lmata 68 }
ce0374a… lmata 69 }
ce0374a… lmata 70 }
ce0374a… lmata 71 ```
ce0374a… lmata 72
ce0374a… lmata 73 === "Cursor"
ce0374a… lmata 74
ce0374a… lmata 75 Add to `.cursor/mcp.json` in your project root:
ce0374a… lmata 76
ce0374a… lmata 77 ```json
ce0374a… lmata 78 {
ce0374a… lmata 79 "mcpServers": {
ce0374a… lmata 80 "navegador": {
ce0374a… lmata 81 "command": "navegador",
ce0374a… lmata 82 "args": ["mcp"],
ce0374a… lmata 83 "env": {
ce0374a… lmata 84 "NAVEGADOR_DB": ".navegador/navegador.db"
ce0374a… lmata 85 }
ce0374a… lmata 86 }
ce0374a… lmata 87 }
ce0374a… lmata 88 }
ce0374a… lmata 89 ```
ce0374a… lmata 90
ce0374a… lmata 91 ---
ce0374a… lmata 92
ce0374a… lmata 93 ## Available MCP tools
ce0374a… lmata 94
89816aa… lmata 95 All tools accept and return JSON. There are 11 tools in total.
ce0374a… lmata 96
ce0374a… lmata 97 | Tool | Equivalent CLI | Description |
ce0374a… lmata 98 |---|---|---|
ce0374a… lmata 99 | `ingest` | `navegador ingest` | Ingest a repo into the graph |
ce0374a… lmata 100 | `context` | `navegador context` | File-level context bundle |
ce0374a… lmata 101 | `function` | `navegador function` | Function with call graph |
ce0374a… lmata 102 | `class` | `navegador class` | Class with hierarchy |
ce0374a… lmata 103 | `explain` | `navegador explain` | Universal node lookup |
ce0374a… lmata 104 | `search` | `navegador search` | Text search across graph |
ce0374a… lmata 105 | `query` | `navegador query` | Raw Cypher passthrough |
89816aa… lmata 106 | `get_rationale` | `navegador explain --rationale` | Decisions and rules governing a node |
89816aa… lmata 107 | `find_owners` | `navegador codeowners` | People and domains that own a node |
89816aa… lmata 108 | `search_knowledge` | `navegador search --knowledge` | Search knowledge layer only |
89816aa… lmata 109 | `blast_radius` | `navegador impact` | Transitive impact set for a node |
ce0374a… lmata 110
ce0374a… lmata 111 ### Tool input schemas
ce0374a… lmata 112
ce0374a… lmata 113 **ingest**
ce0374a… lmata 114 ```json
ce0374a… lmata 115 { "path": "./repo", "clear": false }
ce0374a… lmata 116 ```
ce0374a… lmata 117
ce0374a… lmata 118 **context**
ce0374a… lmata 119 ```json
ce0374a… lmata 120 { "file": "src/auth/service.py", "format": "json" }
ce0374a… lmata 121 ```
ce0374a… lmata 122
ce0374a… lmata 123 **function**
ce0374a… lmata 124 ```json
ce0374a… lmata 125 { "name": "validate_token", "file": "src/auth/service.py", "depth": 2 }
ce0374a… lmata 126 ```
ce0374a… lmata 127
ce0374a… lmata 128 **class**
ce0374a… lmata 129 ```json
ce0374a… lmata 130 { "name": "PaymentProcessor", "file": "src/payments/processor.py" }
ce0374a… lmata 131 ```
ce0374a… lmata 132
ce0374a… lmata 133 **explain**
ce0374a… lmata 134 ```json
ce0374a… lmata 135 { "name": "AuthService", "file": "src/auth/service.py" }
ce0374a… lmata 136 ```
ce0374a… lmata 137
ce0374a… lmata 138 **search**
ce0374a… lmata 139 ```json
ce0374a… lmata 140 { "query": "rate limit", "all": true, "docs": false, "limit": 20 }
ce0374a… lmata 141 ```
ce0374a… lmata 142
ce0374a… lmata 143 **query**
ce0374a… lmata 144 ```json
ce0374a… lmata 145 { "cypher": "MATCH (f:Function) RETURN f.name LIMIT 10" }
ce0374a… lmata 146 ```
89816aa… lmata 147
89816aa… lmata 148 **get_rationale**
89816aa… lmata 149 ```json
89816aa… lmata 150 { "name": "process_payment", "file": "src/payments/processor.py" }
89816aa… lmata 151 ```
89816aa… lmata 152
89816aa… lmata 153 **find_owners**
89816aa… lmata 154 ```json
89816aa… lmata 155 { "name": "AuthService", "file": "src/auth/service.py" }
89816aa… lmata 156 ```
89816aa… lmata 157
89816aa… lmata 158 **search_knowledge**
89816aa… lmata 159 ```json
89816aa… lmata 160 { "query": "idempotency", "limit": 10 }
89816aa… lmata 161 ```
89816aa… lmata 162
89816aa… lmata 163 **blast_radius**
89816aa… lmata 164 ```json
89816aa… lmata 165 { "name": "validate_token", "depth": 3 }
89816aa… lmata 166 ```
89816aa… lmata 167
89816aa… lmata 168 ---
89816aa… lmata 169
89816aa… lmata 170 ## Read-only mode
89816aa… lmata 171
89816aa… lmata 172 Start the MCP server in read-only mode to prevent agents from modifying the graph. This is recommended for shared or production environments.
89816aa… lmata 173
89816aa… lmata 174 ```bash
89816aa… lmata 175 navegador mcp --read-only
89816aa… lmata 176 ```
89816aa… lmata 177
89816aa… lmata 178 In read-only mode, the `ingest` tool is disabled and the `query` tool only accepts `MATCH`/`RETURN` queries. Write keywords (`CREATE`, `MERGE`, `SET`, `DELETE`) are rejected.
89816aa… lmata 179
89816aa… lmata 180 Set in agent config:
89816aa… lmata 181
89816aa… lmata 182 ```json
89816aa… lmata 183 {
89816aa… lmata 184 "mcpServers": {
89816aa… lmata 185 "navegador": {
89816aa… lmata 186 "command": "navegador",
89816aa… lmata 187 "args": ["mcp", "--read-only"],
89816aa… lmata 188 "env": {
89816aa… lmata 189 "NAVEGADOR_DB": ".navegador/navegador.db"
89816aa… lmata 190 }
89816aa… lmata 191 }
89816aa… lmata 192 }
89816aa… lmata 193 }
89816aa… lmata 194 ```
89816aa… lmata 195
89816aa… lmata 196 Or set `read_only = true` in `.navegador/config.toml` under `[mcp]`.
89816aa… lmata 197
89816aa… lmata 198 ---
89816aa… lmata 199
89816aa… lmata 200 ## Editor integration
89816aa… lmata 201
89816aa… lmata 202 Instead of configuring MCP manually, use the editor setup command:
89816aa… lmata 203
89816aa… lmata 204 ```bash
89816aa… lmata 205 navegador editor setup claude-code
89816aa… lmata 206 navegador editor setup cursor
89816aa… lmata 207 navegador editor setup codex
89816aa… lmata 208 navegador editor setup windsurf
89816aa… lmata 209 ```
89816aa… lmata 210
89816aa… lmata 211 This writes the correct MCP config file for the selected editor and prompts for the database path.
ce0374a… lmata 212
ce0374a… lmata 213 ---
ce0374a… lmata 214
ce0374a… lmata 215 ## When MCP makes sense
ce0374a… lmata 216
ce0374a… lmata 217 - You are in an interactive Claude or Cursor session and want to call `explain`, `search`, or `function` without dropping to a terminal
ce0374a… lmata 218 - You want navegador tools auto-discovered by the agent without writing custom tool definitions
ce0374a… lmata 219 - You are building an agent workflow that dynamically queries the graph mid-task
5e4b8e4… anonymous 220
ce0374a… lmata 221 For automated background tasks (re-ingest on file save, sync on pull), use the CLI via [agent hooks](agent-hooks.md) instead.

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button