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.
4
5
---
6
7
## CLI vs MCP: when to use which
8
9
The primary interface for agents is the **CLI**, not MCP. Here's why:
10
11
| | CLI | MCP |
12
|---|---|---|
13
| Token cost | Low — agent calls a shell tool, gets back only what it asked for | Higher — MCP tool calls involve protocol overhead |
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.
19
20
---
21
22
## Starting the MCP server
23
24
```bash
25
navegador mcp
26
```
27
28
With a custom database path:
29
30
```bash
31
navegador mcp --db .navegador/navegador.db
32
```
33
34
The server speaks MCP over stdio. It does not bind a port.
35
36
---
37
38
## Agent configuration
39
40
=== "Claude Code"
41
42
Add to your project's `.claude/settings.json`:
43
44
```json
45
{
46
"mcpServers": {
47
"navegador": {
48
"command": "navegador",
49
"args": ["mcp"],
50
"env": {
51
"NAVEGADOR_DB": ".navegador/navegador.db"
52
}
53
}
54
}
55
}
56
```
57
58
=== "Claude Desktop"
59
60
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
Start the MCP server in read-only mode to prevent agents from modifying the graph. This is recommended for shared or production environments.
173
174
```bash
175
navegador mcp --read-only
176
```
177
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.
179
180
Set in agent config:
181
182
```json
183
{
184
"mcpServers": {
185
"navegador": {
186
"command": "navegador",
187
"args": ["mcp", "--read-only"],
188
"env": {
189
"NAVEGADOR_DB": ".navegador/navegador.db"
190
}
191
}
192
}
193
}
194
```
195
196
Or set `read_only = true` in `.navegador/config.toml` under `[mcp]`.
197
198
---
199
200
## Editor integration
201
202
Instead of configuring MCP manually, use the editor setup command:
203
204
```bash
205
navegador editor setup claude-code
206
navegador editor setup cursor
207
navegador editor setup codex
208
navegador editor setup windsurf
209
```
210
211
This writes the correct MCP config file for the selected editor and prompts for the database path.
212
213
---
214
215
## When MCP makes sense
216
217
- You are in an interactive Claude or Cursor session and want to call `explain`, `search`, or `function` without dropping to a terminal
218
- You want navegador tools auto-discovered by the agent without writing custom tool definitions
219
- You are building an agent workflow that dynamically queries the graph mid-task
220
221
For automated background tasks (re-ingest on file save, sync on pull), use the CLI via [agent hooks](agent-hooks.md) instead.