MCP Servers

MCP Servers

The chat agent ships with six built-in tools. MCP (Model Context Protocol) lets you give it more: your issue tracker, your notes app, a database, a scraper — anything exposed by an MCP server. They appear alongside the native tools and the model picks between them freely.

Configure them in Settings → MCP servers; they are stored under mcp_servers in settings.json.

Configuration

{
  "mcp_servers": [
    { "name": "github",
      "url": "https://mcp.example.com/mcp",
      "auth": "Bearer ghp_xxxxxxxx",
      "command": "", "args": [],
      "enabled": true },

    { "name": "notes",
      "url": "", "auth": "",
      "command": "npx",
      "args": ["-y", "@some/mcp-notes-server", "--dir", "D:\\Notes"],
      "enabled": true }
  ]
}

Field	Meaning
name	Short namespace for the server's tools. Keep it simple — it becomes part of the tool name.
url	HTTP transport: the Streamable-HTTP / JSON-RPC endpoint.
auth	The complete Authorization header value (e.g. Bearer xxx). Optional.
command	stdio transport: the executable to launch (npx, uvx, a binary path). If non-empty, stdio wins and url is ignored.
args	Arguments for the stdio command.
enabled	Off = completely ignored, not even contacted.

The two transports

HTTP — JSON-RPC 2.0 POSTed to url, with Accept: application/json, text/event-stream. A returned Mcp-Session-Id header is captured and replayed on subsequent calls. Responses are accepted as plain JSON or as an SSE stream (the last data: line carrying a result or error is used). 20-second timeout.

stdio — the command is spawned, JSON-RPC exchanged line by line over stdin/stdout, and the process killed when the exchange ends. Non-JSON lines (server logs) are skipped, and replies are matched by request id, so notifications interleaved in the stream cause no confusion. On Windows the command runs through cmd /C so PATH launchers like npx.cmd and uvx.cmd resolve.

Both do the same handshake: initialize (protocol version 2025-06-18, client identified as SenseTree + version), then a notifications/initialized notification, then tools/list. Calling a tool is tools/call with {"name": ..., "arguments": ...}; the response's content[].text items are concatenated into the observation handed back to the model (a result with no text is passed through raw rather than dropped).

How tools reach the model

Discovered tools are namespaced and sanitised to the function-calling name grammar (^[A-Za-z0-9_-]{1,64}$):

mcp__<server>__<tool>

Their JSON Schema is reused verbatim as the function's parameters, and their description is prefixed with [<server>]. They are appended to the built-in tool list in the same tools array — see AI Server Protocol §4.

In the chat's live trace, an external tool shows as 🔌 <server> · <tool>.

Discovery cache

Handshaking every server on every chat message would be slow and noisy. Discovery is cached in memory, keyed by a signature of the server configuration (name, url, auth, command, args) with a 120-second TTL.

So: edit a server and the cache invalidates immediately; leave it alone and a busy conversation costs at most one handshake per two minutes. The cache is in-memory only — restarting the app rediscovers.

Failure behaviour

Best-effort throughout. An unreachable, misbehaving or non-conforming server is logged and skipped; the agent proceeds with whatever tools it did get. A tool call that errors returns the error text as the observation, letting the model react — try another approach, or tell you it couldn't.

Nothing about MCP can break the chat.

Security

This is the one place where SenseTree's usual guarantees don't apply, and it is worth being explicit:

• MCP tools are not bounded by your indexed roots. The root-boundary check protects the built-in tools (read_file, list_directory, read_semantics, propose_actions). An MCP server does whatever it was written to do.
• Arguments are chosen by the model, from a conversation that contains your file excerpts. A server that exfiltrates its inputs receives whatever the agent passes it.
• stdio servers run as arbitrary local processes, with your user's privileges.
• auth is stored in plain text in settings.json, like every other credential in the file.

Add servers you trust, from sources you trust, and treat enabled: false as the real off switch.

Verifying a server

There is no dedicated test button. The quickest check:

1. Add the server, enable it, save.
2. Ask the assistant something the server should answer.
3. Watch the live trace — a 🔌 name · tool line means discovery worked and the model chose it.

If nothing appears, the app log (MCP <name> unavailable: …, or MCP <name>: N tool(s) exposed) tells you whether discovery succeeded. Run the app from a terminal to see it.