Monofile over MCP

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.

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>.

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:

{"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.

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.

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

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