# MCP server usage
SIFS can run as a Model Context Protocol server over standard input and output.
For long-lived agent use, pair it with the shared SIFS daemon so repeated agent
searches can reuse warm indexes across MCP server launches and direct CLI
commands.
## Start the server
Run `sifs mcp` to start stdio server mode. You can pass a default local path or
Git URL as the first positional argument.
```bash
target/release/sifs mcp
target/release/sifs mcp /path/to/project
```
When the default source is a Git URL, use `--ref` to choose a branch or tag.
```bash
target/release/sifs mcp https://github.com/owner/project --ref main
```
Use `--encoder`, `--model`, `--no-download`, or `--offline` to control
semantic encoder and model loading for server mode. `--offline` also rejects
Git URL sources.
When you pass a default source, MCP tool calls can omit `repo` to use that
source. Calls may still pass a different `repo` local path or Git URL when the
agent needs to search another checkout. If you don't pass a default source,
SIFS uses the MCP server process working directory as the default source and
still accepts explicit `repo` overrides.
## Configure a client
Most MCP clients let you configure a command and argument list. Use an absolute
path to the release binary when the client doesn't run from the SIFS repository.
```toml
[mcp_servers.sifs]
command = "/absolute/path/to/sifs"
args = ["mcp"]
```
For Git-backed search, pass the Git URL and optional ref as arguments.
```toml
[mcp_servers.sifs]
command = "/absolute/path/to/sifs"
args = ["mcp", "https://github.com/owner/project", "--ref", "main"]
```
## Install into Codex or Claude Code
After installing `sifs` with Cargo or Homebrew, install the user daemon once and
then use `sifs mcp install` to add the server to Codex and/or Claude Code.
```bash
sifs daemon install-agent
sifs mcp install --client all
```
Use one client at a time when you want tighter control.
```bash
sifs mcp install --client codex --source /path/to/project
sifs mcp install --client claude --scope local --source /path/to/project
```
Defaults:
- `--client all`
- `--name sifs`
- no pinned `--source`; the server defaults to its process working directory
- Claude Code uses `--scope local` unless another scope is provided.
Use `--dry-run` to print the client commands and fallback config without
changing anything.
```bash
sifs mcp install --dry-run --client all
```
The Codex command generated by the installer is equivalent to:
```bash
codex mcp add sifs -- /absolute/path/to/sifs mcp
```
The Claude Code command generated by the installer is equivalent to:
```bash
claude mcp add-json sifs '{"type":"stdio","command":"/absolute/path/to/sifs","args":["mcp"],"env":{}}' --scope local
```
If a server with the same name already exists, the installer exits without
changing it. Use `--force` to remove and recreate the existing client entry.
For Git-backed MCP search:
```bash
sifs mcp install --client codex --source https://github.com/owner/project --ref main
```
The installer rejects `--offline` with Git URL sources, matching server mode.
For local sources it canonicalizes the path before writing config.
Use `sifs mcp doctor` to inspect readiness and print the exact server command
that clients should launch.
```bash
sifs mcp doctor /path/to/project --offline --no-cache
```
Security note: SIFS runs as a local stdio process and can read local paths
provided in tool calls. Project-scoped Claude Code `.mcp.json` files are shared
through the repository, so only add them to trusted repositories.
## Protocol surface
The server uses JSON-RPC messages with `Content-Length` framing. It handles the
standard MCP initialization and tool-list methods that clients call during
startup.
Supported methods are:
- `initialize`: Returns server metadata, tool capability information, and usage
instructions. The instructions include the configured default source/ref and
repo selection policy when a default source is present.
- `resources/list`: Returns context resources for server state and index
discovery.
- `resources/read`: Reads context resources such as `sifs://server/context`.
- `tools/list`: Returns schemas for search, related-code discovery, index
inspection, refresh, cache clearing, indexed-file listing, and chunk reading.
- `tools/call`: Runs a supported tool and returns text content.
Unsupported methods return an error string inside the JSON-RPC result payload.
## Search tool
Use the `search` tool to find relevant chunks in a repository. The query can be
natural language, code, an identifier, or a short phrase.
Input schema:
```json
{
"query": "Natural language or code query.",
"repo": "/path/to/project",
"mode": "hybrid",
"top_k": 5
}
```
Fields:
- `query` is required.
- `repo` is optional when the server started with a default source. When a
default source is configured, omitting `repo` uses that source; passing `repo`
searches the requested local path or Git URL instead.
- `mode` is optional and can be `hybrid`, `semantic`, or `bm25`.
- `top_k` is optional and defaults to `5`.
- `alpha` is optional for hybrid search. Omit it to let SIFS choose the blend
from the query shape.
- `filter_languages` is optional and accepts exact language labels such as
`rust`.
- `filter_paths` is optional and accepts repository-relative file paths.
Use `hybrid` for most tasks. Use `bm25` for exact symbols and `semantic` for
meaning-only exploration.
Search responses include text content for agent context injection and
`structuredContent` with source metadata, index stats, and result objects. Each
structured result includes `file_path`, `start_line`, `end_line`, `language`,
`score`, `source`, and `content`.
## find-related tool
Use the `find_related` tool to locate chunks similar to a known file and line.
The file path must match an indexed chunk path or resolve to one.
Input schema:
```json
{
"file_path": "src/auth/session.rs",
"line": 42,
"repo": "/path/to/project",
"top_k": 5
}
```
Fields:
- `file_path` is required.
- `line` is required and uses one-based line numbers.
- `repo` is optional when the server started with a default source. When a
default source is configured, omitting `repo` uses that source; passing `repo`
searches the requested local path or Git URL instead.
- `top_k` is optional and defaults to `5`.
When SIFS can't resolve the file and line, the tool returns a text error that
asks you to check whether the file is indexed and the line is inside a known
chunk.
## Index inspection tools
Use `index_status` to inspect the selected repository before or after searching.
It returns the source, optional Git ref, memory cache state, indexed file count,
chunk count, language distribution, and available MCP tools.
```json
{
"repo": "/path/to/project"
}
```
Use `list_indexed_files` to see which repository-relative file paths are in the
index.
```json
{
"repo": "/path/to/project",
"limit": 200
}
```
Use `get_chunk` to read the indexed chunk containing a known file and one-based
line.
```json
{
"file_path": "src/auth/session.rs",
"line": 42,
"repo": "/path/to/project"
}
```
Use `refresh_index` after a user or agent edits files while a long-running MCP
server is active. The server keeps in-memory indexes for the process lifetime,
so refresh is the explicit way to make search reflect recent file changes
without restarting the server.
Use `clear_index` to remove a source from the in-memory cache. The next search
or status call rebuilds or reloads the index.
Use `init_agent` to create the generated SIFS Claude agent file from an MCP
client. It defaults to `.claude/agents/sifs-search.md` and accepts `force` to
overwrite an existing file.
```json
{
"destination": ".claude/agents/sifs-search.md",
"force": false
}
```
## Resources
The server exposes lightweight MCP resources for discovery:
- `sifs://server/context`: server version, default source/ref, cache keys, tools,
and resource URIs.
- `sifs://index/status`: pointer to the `index_status` tool for current stats.
- `sifs://index/files`: pointer to the `list_indexed_files` tool for indexed
file inventory.
## Index caching
The MCP server caches indexes for the lifetime of the process. Local sources
are keyed by canonical path. Git sources are keyed by URL and optional ref.
The first call for a source pays the indexing cost. Later calls reuse the
in-memory `SifsIndex`, including the BM25 index and chunk mappings. Semantic
model state and dense vectors are loaded lazily only after semantic, hybrid, or
`find_related` calls. BM25 tool calls stay model-free.
The MCP server also uses SIFS persistent caches unless started with
`--no-cache`. By default those entries live in the platform cache directory;
start the server with `--cache-dir` for a custom cache root or `--project-cache`
to opt into repository-local `.sifs/` state.
If files change while the MCP server keeps running, call `refresh_index` before
trusting search results for the changed source. Git URL mode indexes a temporary
clone, so it does not include uncommitted changes from a separate local checkout.
## Error handling
Tool calls return text content even when indexing or lookup fails. This keeps
the response shape simple for clients and agents.
Common errors include:
- Missing `repo` when the server has no default source.
- A local path that doesn't exist or isn't a directory.
- A Git clone failure.
- A semantic or hybrid search when the requested model is unavailable under
`--offline` or `--no-download`.
- A file and line that don't map to an indexed chunk.