View as Markdown

Connecting MCP Clients

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.

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

    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:

    POST/api/mcp-keys
    {"name": "Claude Desktop", "scopes": ["files:read", "files:write"]}
    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.

    Terminal
    export MONOFILE_MCP_API_KEY="mk_..."

  2. Add Monofile to your client

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

    Hosted endpoint:

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

    Local server:

    Terminal
    claude mcp add monofile -e MONOFILE_MCP_API_KEY="$MONOFILE_MCP_API_KEY" -- npx -y @monofile/mcp

  3. Check it works

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

    Terminal
    npx -y @monofile/mcp --list

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

    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.

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

Referenced byAuthenticationMonofile over MCPTroubleshooting
691 words