Copy-pasteable configuration for Claude Code, Claude Desktop and any other MCP client, for both the hosted endpoint and the local server. If you have not decided which of the two to use, [[Monofile over MCP]] compares them. The short answer is the hosted endpoint.

> [!NOTE]
> The snippets below target production. For an interactive version of every client's snippet, filled in for the deployment you are signed in to, open the app's MCP page at [https://www.monofile.ai/mcp](https://www.monofile.ai/mcp).

:::steps
### Get a key

Any `mk_` key works, including one you already use with the CLI or the REST API. If you are starting from nothing, register and get a key in one step:

```bash title="Terminal"
npx @monofile/cli init --name "YourName"
```

If you already have a key, mint a dedicated one for this client so you can revoke it on its own:

```http
POST /api/mcp-keys
{"name": "Claude Desktop", "scopes": ["files:read", "files:write"]}
```

```bash title="Terminal"
curl -X POST "https://www.monofile.ai/api/mcp-keys" \
  -H "Authorization: Bearer $MONOFILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Claude Desktop", "scopes": ["files:read", "files:write"]}'
```

The response contains `apiKey`, shown once. Omit `scopes` for the default set, or narrow it; the hosted endpoint offers a client only the tools its key can use. See [[Authentication]] and [[Scopes]].

```bash title="Terminal"
export MONOFILE_MCP_API_KEY="mk_..."
```

### Add Monofile to your client

Pick your client. Each tab shows the hosted endpoint first and the local server second.

:::tabs
:::tab Claude Code
Hosted endpoint:

```bash title="Terminal"
claude mcp add monofile https://www.monofile.ai/api/mcp \
  -t http \
  -H "Authorization: Bearer $MONOFILE_MCP_API_KEY"
```

Local server:

```bash title="Terminal"
claude mcp add monofile -e MONOFILE_MCP_API_KEY="$MONOFILE_MCP_API_KEY" -- npx -y @monofile/mcp
```
:::
:::tab Claude Desktop
Hosted endpoint: add it as a custom connector from inside the app. Open Customize, then Connectors, then Add custom connector, and fill in:

| Field | Value |
|---|---|
| Remote MCP server URL | `https://www.monofile.ai/api/mcp` |
| Authentication | No sign in |
| Request headers | `Authorization: Bearer mk_...` |

Local server: edit `claude_desktop_config.json` and restart the app. This file is for stdio servers only.

```json path="claude_desktop_config.json"
{
  "mcpServers": {
    "monofile": {
      "command": "npx",
      "args": ["-y", "@monofile/mcp"],
      "env": { "MONOFILE_MCP_API_KEY": "mk_..." }
    }
  }
}
```

The config file lives at:

| Platform | Path |
|---|---|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |
:::
:::tab Other clients
Any MCP client can connect. The two shapes are the same everywhere; only the field names in the client's own config differ.

For an HTTP client, you need a URL and one header:

```json title="HTTP server entry"
{
  "type": "http",
  "url": "https://www.monofile.ai/api/mcp",
  "headers": { "Authorization": "Bearer mk_..." }
}
```

For a stdio client, you need a command, its arguments and one environment variable:

```json title="stdio server entry"
{
  "command": "npx",
  "args": ["-y", "@monofile/mcp"],
  "env": { "MONOFILE_MCP_API_KEY": "mk_..." }
}
```

The local server needs Node 20 or newer. Add `MONOFILE_API_URL` to the same `env` block to point it at a deployment other than production.
:::
:::

### Check it works

Before wiring anything into a client, confirm the pieces separately. First, that the package runs and its tools are there:

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

Then, that the key is valid and you can see what it may do:

```bash title="Terminal"
curl -X POST "https://www.monofile.ai/api/tools/get_key_info" \
  -H "Authorization: Bearer $MONOFILE_MCP_API_KEY" \
  -H "Content-Type: application/json" -d '{}'
```

Then ask the client to list its tools. You should see the Monofile tools under whatever name you configured.
:::

> [!WARNING]
> Always the `www` host: `https://www.monofile.ai`. The apex domain answers with a redirect, and a redirect drops the `Authorization` header, which shows up as tools that connect but calls that fail.

## Troubleshooting

- **Tools appear but every call fails, or the auth seems to vanish.** Check the host. It must be `https://www.monofile.ai` with the `www`. The apex domain answers with a redirect, and a redirect strips the `Authorization` header.
- **401 Unauthorized.** The key is missing, malformed, expired or revoked. The header must read exactly `Authorization: Bearer mk_...`.
- **A tool returns an error but the request succeeded.** That is a tool-level error, not a connection problem. Read the `code` in the result JSON. `INSUFFICIENT_SCOPE` means the key is too narrow, and the other codes are in [[Errors and Limits]].
- **A tool you expected is missing from the list.** On the hosted endpoint the list is filtered to your key's scopes. Call `get_key_info` to see what you hold, then mint a key with the scopes you need.
- **The local server does nothing.** Run `npx -y @monofile/mcp --list` in a terminal. If that fails, the problem is in Node or npm. Check that Node is 20 or newer.
- **Config edits do not take effect.** Claude Desktop reads its config at startup, so restart the app after changing it.
- **Shell commands are refused with `SANDBOX_NOT_ENTITLED`.** The full shell is part of paid plans. Built-in commands keep working, see [[File and Shell Tools]].

## Next steps

:::cards
- [[Monofile over MCP]] — The hosted endpoint and the local server, and how they relate to the REST tools.
- [[Scopes]] — Every scope, what it unlocks, and the presets.
- [[File and Shell Tools]] — Reading, writing and editing files, plus the two shell tiers.
- [[Troubleshooting]] — The errors people actually hit, and the fix.
:::