> ## Documentation Index
> Fetch the complete documentation index at: https://unch.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

> Install and use unch MCP from Codex.

## Codex setup

Install the npm wrapper and register unch with Codex:

```bash theme={null}
npm install -g @uchebnick/unch
unch codex install
```

Then restart Codex.

`unch codex install` does two things:

* registers the `unch` MCP server with Codex
* writes the `unch` skill to `~/.codex/skills/unch/SKILL.md`

The npm `postinstall` step does not modify Codex automatically. Run `unch codex install` explicitly when you want the integration.

## How to use it

After restarting Codex, work in a repository and ask codebase questions normally. The installed skill tells Codex to call unch before broad file reads when semantic code search can help.

Codex starts the stdio MCP server for you. You normally do not need to run `unch start mcp` by hand.

## Tools

All tools accept an optional `directory` argument. Codex should pass the absolute path of the active repository so the MCP server operates on the workspace being edited, not on the directory where the server process was launched.

### `workspace_status`

Returns the repository root, state directory, selected provider/model, index path, manifest metadata, and whether an index is already present.

Agents should call this first.

### `search_code`

Searches indexed code symbols with `auto`, `semantic`, or `lexical` mode.

Agents should call this before opening many files or running broad grep-style exploration.

### `index_repository`

Builds or refreshes the index for the configured workspace.

Agents should call this when no index exists, when search reports no active snapshot for the selected provider/model, or when the user explicitly asks to rebuild.

### `create_ci_workflow`

Creates `.github/workflows/unch-index.yml` in the target repository.

Agents should call this only when the user asks to set up GitHub Actions-backed remote indexing.

### `bind_remote_ci`

Binds the local `.semsearch/manifest.json` to a GitHub repository or workflow URL.

Agents should call this after the workflow exists, or when the user provides a GitHub repository/workflow URL to bind for remote sync.

### `remote_sync_index`

Refreshes the local index from the bound remote workflow.

Agents should call this before local reindexing when `workspace_status` reports a `remote_ci` binding.

### `remote_download_index`

Downloads and activates a published index artifact for a specific commit without binding the workspace to ongoing remote sync.

## What Codex runs

The registered MCP server uses:

* Name: `unch`
* Command: `unch-mcp`
* Arguments: none

`unch-mcp` is a small launcher for `unch start mcp`.

## Notes

* The installed skill passes the active repository directory into unch MCP tool calls.
* The process reuses the same provider/model/runtime configuration across tool calls.
* OpenRouter token lookup checks `OPENROUTER_API_KEY`, then `~/.config/unch/tokens.json`, then `.semsearch/tokens.json`.
* The MCP server exposes tools only in this release; streamable HTTP is not supported yet.