Model Context Protocol¶

StrataFS runs a Model Context Protocol server alongside the REST API. The MCP server reuses the same hybrid search engine, with response shapes trimmed for LLM context windows.

Default port: :8081 (pkg/protocol/mcp.go).

Endpoints¶

The MCP server registers four routes:

GET /mcp¶

Protocol info and capabilities:

curl http://localhost:8081/mcp

{
  "protocol": "mcp",
  "version": "1.0.0",
  "capabilities": ["search", "resources"]
}

GET /mcp/search¶

Search optimized for agent consumption. Backed by the same SearchEngine as the REST /search endpoint, but the response is shaped for LLM context windows. The richer filter / weights surface lives on the REST API — see Search → REST API.

curl "http://localhost:8081/mcp/search?q=API+authentication&limit=5"

GET /mcp/documents/{path}¶

Fetch a stored document by its path within an indexed source. The path after /mcp/documents/ is looked up in the per-source database.

curl "http://localhost:8081/mcp/documents/docs/auth.md"

GET /mcp/resources¶

Enumerate the sources StrataFS is currently indexing as MCP resources. Each entry carries a type, name, and path so an agent can map the resource back to a search call.

{
  "resources": [
    { "type": "directory", "name": "/Users/you/Documents", "path": "/Users/you/Documents" }
  ]
}

Wiring it into an agent¶

Claude Desktop / Claude Code¶

Run stratafs serve (which boots both the REST and MCP servers on :8080 and :8081), then point your client at the running daemon's MCP endpoint via your client's HTTP-MCP bridge.

There is no dedicated MCP-only flag today — serve always brings both servers up together. The two share state, so anything indexed via one is visible to the other.

Custom Python client¶

import requests

resp = requests.get(
    "http://localhost:8081/mcp/search",
    params={"q": "rate limiting", "limit": 5},
    timeout=10,
)
for hit in resp.json()["results"]:
    print(hit["file"], hit["score"])

Custom TypeScript client¶

const res = await fetch(
  `http://localhost:8081/mcp/search?q=${encodeURIComponent("rate limiting")}&limit=5`,
);
const { results } = await res.json();
results.forEach(r => console.log(r.file, r.score));

When to prefer MCP over REST¶

The two servers share state. Anything indexed via one is visible to the other.