Monofile speaks the Model Context Protocol, so an MCP client can use your workspace as a set of native tools with no glue code. There are two ways to connect, and both expose the same tools. One is a hosted endpoint you point a client at; the other is a local server you run with `npx`.

| | Hosted (HTTP) | Local (stdio) |
|---|---|---|
| What you configure | `https://www.monofile.ai/api/mcp` | `npx -y @monofile/mcp` |
| Auth | `Authorization: Bearer mk_...` header | `MONOFILE_MCP_API_KEY` environment variable |
| Runs where | Monofile's servers, nothing to install | Your machine, one Node process that proxies to the API |
| Pick it when | Your client speaks HTTP MCP, which most do | Your client only speaks stdio, or you want the process local |

## One registry, every surface

Monofile generates both MCP transports from the tool registry that serves the REST API. A tool has the same name, input schema, required scopes and behaviour whether you call it over MCP or with `POST /api/tools/<name>`.

```mermaid
flowchart LR
  R[Tool registry] --> H[Hosted /api/mcp]
  R --> S[skill.json snapshot]
  R --> T[POST /api/tools/name]
  S --> N[npx @monofile/mcp]
  N --> T
```

Two consequences follow. The tool list cannot drift between the three, so the REST tool pages are the MCP documentation too: [[File and Shell Tools]], [[Content Tools]], [[Sharing and Community]] and [[Account and Search]]. And a result is the REST envelope passed through unchanged, one text block whose content is the tool's JSON. A payload shaped `{ "error": { "code", "message" } }` means the call failed, and the server flags it as an error to the client.

Scopes apply as they do over REST. An `mk_` key with `files:read` alone can list and read but not write. See [[Scopes]].

## The hosted endpoint

Point your client at the endpoint with your key as a bearer token (`Authorization: Bearer mk_...`). Every MCP request is one JSON-RPC message:

```http
POST /api/mcp
{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}
```

It is a stateless Streamable HTTP server. Each request authenticates and runs on its own, with no session to establish or keep alive, and there is nothing to install, update or keep running.

Two details matter in practice:

- **`tools/list` is filtered to your key.** It returns only the tools whose scopes your key holds, so a client does not show a tool that would fail. Execution re-checks the scopes regardless.
- **`bash` runs with the full contract.** The hosted endpoint runs the same handler as REST. The two shell tiers, the write-back of file changes and the scope check on that write-back all behave the same. The tool description your client reads reflects the tier your plan has.

Writes made during one MCP request form one changeset, as a REST call's do, so a human can review and revert what a client did as one unit. See [[Changesets]].

> [!WARNING]
> Always use the `www` host. The apex domain answers with a redirect, and redirects strip the `Authorization` header, which shows up as tools that connect but calls that fail.

## The local stdio server

`npx -y @monofile/mcp` runs a small Node process that speaks MCP over stdio and forwards every call to `POST /api/tools/<name>` with your key. It needs Node 20 or newer and it stores nothing locally.

| Variable | Purpose |
|---|---|
| `MONOFILE_MCP_API_KEY` | Your `mk_` key. `MONOFILE_API_KEY` is accepted as a fallback |
| `MONOFILE_API_URL` | Point the proxy at a different Monofile deployment. Defaults to production |

To confirm the install before wiring it into a client, print the tool names the package ships:

```bash title="Terminal"
npx -y @monofile/mcp --list
```

One behaviour differs from the hosted endpoint. The local server lists every tool it ships, because the process does not know your key's scopes, and a call your key cannot make returns `INSUFFICIENT_SCOPE`.

## Which one to pick

Start with the hosted endpoint. It has nothing to install, it cannot fall behind a release, and its tool list is already tailored to your key.

Choose the local server when your client only supports stdio servers, when you want the outbound connection to come from your own machine, or when you are pointing at a non-production deployment with `MONOFILE_API_URL`.

Both read the same workspace with the same key, so you can run a client on each.

## Next steps

:::cards
- [[Connecting MCP Clients]] — Claude Code, Claude Desktop and other clients, with config blocks.
- [[Authentication]] — API keys: minting, storing, rotating, and folder-scoped keys.
- [[Calling Tools]] — The one-endpoint pattern, the MCP-shaped envelope, and the index of every tool.
- [[File and Shell Tools]] — Reading, writing and editing files, plus the two shell tiers.
:::