Connect an AI assistant with MCP

What it's for

Magnus Box can act as a Model Context Protocol (MCP) server. MCP is a standard way to give AI tools extra abilities. Once connected, your AI assistant can look things up in your backup account for you, in plain English.

In read-only mode there are about 80 tools, covering users, jobs, storage, policies, devices and settings. The tools are read-only by default. Write access (tools that change things) is only turned on if you ask for it, and it adds more tools. Read-only still means the AI can see everything the account can see, including the names of files and folders on your clients' online devices.

Things MSPs use it for:

• "Which of my clients had failed or missed backups last night?"
• "List devices that are offline or running an outdated version."
• "How much storage is each client using?"
• "Summarize this week's backup jobs for Contoso Dental."
• Pulling the numbers for a monthly client report or QBR without clicking through the portal.

Pick your AI tool

Jump to the copy-paste setup for your tool:

• Let your AI set it up for you: paste one prompt into Claude Code
• Claude Code: recommended for Claude users. One command, no config file.
• Claude Desktop
• Any other AI tool: Copilot, Cursor, Windsurf, Zed, Codex and more

Before you start: choose how to sign in

An AI tool connected over MCP can do anything the login it uses can do, and see everything that login can see: the users and devices in your own account, not anyone else's. You have two options.

Option 1: use your existing login (quickest)

You can connect with the portal login you already use. Before you do:

• The AI gets that login's full reach. It can see everything your login can see. With write access, it could also do anything your login can do, including deleting users or backup settings.
• Two-factor authentication gets in the way. The MCP connection signs in with just a username and password, so it can't answer 2FA prompts. If your login uses 2FA, don't turn 2FA off to make this work. Use Option 2 instead.
• Your password is stored on that computer. It ends up in the AI tool's config file. If that file is ever exposed, you'll need to change your password.
• It's harder to tell who did what. Anything the AI does shows up under your own name.

With great power comes great responsibility, so keep an eye on what you let the AI do.

Option 2: request a dedicated AI account (recommended)

We create a separate login just for AI access. It's safer because:

• It's read-only unless you ask for more. We set up dedicated AI accounts as read-only, and that's enforced on our side, so the AI can't change anything even if a tool asks to. If you need write access, tell us when you request the account.
• AI activity is tracked under its own name, separate from staff logins.
• It can be disabled or reset on its own, without touching your login or your team's.
• Your own login keeps two-factor authentication.
• You don't build anything. We send you a ready-made sign-in value to paste.

Email support@magnusbox.com to request one. Include:

1. Which AI tool or tools you'll connect, and whether it runs on your own computer or in the cloud.
2. Read-only or write access. We recommend starting read-only. If you want write access, tell us what you want the AI to be able to change and why.
3. Who will use it, and on which computers.
4. What you want to use it for, such as job monitoring, device health checks or reporting.

We'll reply with your connection details.

Your connection details

Every example below uses YOUR-PORTAL-URL and Basic BASE64-VALUE. Replace them with your details.

Build the sign-in value from your own login (Option 1)

It's the word Basic, one space, then the Base64 encoding of USERNAME:PASSWORD. To get the Base64 part:

• macOS or Linux terminal: echo -n 'USERNAME:PASSWORD' | base64
• Windows PowerShell: [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes('USERNAME:PASSWORD'))

Then put Basic and a space in front of the result.

Let your AI set it up for you

AI tools that can read web pages and run commands can read this article and do the setup themselves. Claude Code is the best fit. Copy and paste this prompt into it:

Read https://support.magnusbox.com/article/564-connect-an-ai-assistant-with-mcp and set up the Magnus Box MCP connection for me using Claude Code at user scope. Ask me for my sign-in details when you need them, then run the ping test to confirm it works.

• Use your dedicated read-only AI account. Support sends you the ready-made sign-in value (see Option 2).
• Never paste your credentials into a shared chat or a public AI tool.
• Using Claude Desktop? Restart it yourself after the AI edits the config file: fully quit from the system tray or menu bar, then reopen it.
• If your AI can't browse the web, copy the article text into the chat instead.

Steps

Claude Code (recommended for Claude users)

The easiest and most reliable route. It connects directly, with no config file and no Node.js.

1. Open a terminal: Terminal on macOS, PowerShell or Command Prompt on Windows.
2. Paste this command, with your details:

claude mcp add --transport http --scope user magnus-box https://YOUR-PORTAL-URL/mcp/ --header "Authorization: Basic BASE64-VALUE"

You should see Added HTTP MCP server magnus-box. --scope user makes it work in every folder. Without it, the server only loads in the folder you ran the command from.

Check it's connected: run claude mcp list. You should see magnus-box: https://YOUR-PORTAL-URL/mcp/ (HTTP) - ✔ Connected. Inside Claude Code, type /mcp to see the server and its tools.

Made a typo? Run claude mcp remove magnus-box --scope user, then run the add command again.

Claude Desktop

Claude Desktop connects through a small bridge called mcp-remote that runs on your computer. It needs Node.js 18 or later. Get the LTS version from nodejs.org. To check, run node --version in a terminal.

1. In Claude Desktop, go to Settings > Developer > Edit Config. This opens the folder with the config file:
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
2. Open the file in a text editor and paste in Example A or Example B below.
3. Save the file.
4. Fully quit Claude Desktop. Closing the window isn't enough, because the app keeps running in the background.
   • Windows: right-click the Claude icon in the system tray (bottom right, near the clock; you may need to click ^ first) and choose Quit.
   • macOS: click Claude in the menu bar and choose Quit Claude, or press Cmd+Q.
5. Open Claude Desktop again. In Settings > Developer, magnus-box should be listed as running.

Example A: the file is empty or only has {}. Replace everything in the file with this:

{
  "mcpServers": {
    "magnus-box": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://YOUR-PORTAL-URL/mcp/",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Basic BASE64-VALUE"
      }
    }
  }
}

Leave Authorization:${AUTH_HEADER} exactly as it is. Put your sign-in value only in the AUTH_HEADER line.

Example B: the file already has other settings or servers. Keep what's there and add the magnus-box entry. Here, preferences and filesystem stand in for whatever is already in your file:

{
  "preferences": {
    "sidebarMode": "chat"
  },
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\Users\\you\\Desktop"]
    },
    "magnus-box": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://YOUR-PORTAL-URL/mcp/",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Basic BASE64-VALUE"
      }
    }
  }
}

• Already have an "mcpServers" section? Add the "magnus-box" entry inside it. Put a comma after the } that closes the entry above it.
• No "mcpServers" section yet? Add the whole section after your other settings. Put a comma after the } that closes the setting above it.
• The file must start with one { and end with one }.

We don't recommend Claude's "Add custom connector" option for this. Custom connectors connect from Anthropic's cloud, not from your computer, and on Claude Team and Enterprise plans only users with the Owner role can add them.

Any other AI tool

Most MCP-compatible tools (for example Copilot, Cursor, Windsurf, Zed or Codex) can add a remote MCP server. In your tool's MCP settings:

1. Add a remote (HTTP) MCP server and give it the address from Your connection details.
2. Add a header named Authorization with your sign-in value (Basic BASE64-VALUE) as its value.

If the tool can only run local servers, use the same npx mcp-remote command, arguments and AUTH_HEADER setting shown for Claude Desktop. This needs Node.js 18 or later.

After you connect

• Set your AI tool to ask before it acts. Have it ask you to approve each tool call before it runs. This matters most with write access, but it's a good habit even in read-only mode.
• Write access: tools that change things are off by default. A dedicated AI account is also locked to read-only on our side. If you need write access, email support@magnusbox.com and tell us what you want the AI to change and why. We'll turn it on (for a dedicated AI account, we also lift the read-only lock) and send you one extra header line to add next to the Authorization header. Leave it out to stay read-only.

Verify it worked

1. In your AI tool, check that the magnus-box server shows as connected and lists its tools.
2. Ask a simple read-only question, such as "How many users are in my account?" or "Which devices are offline?", and compare the answer with the Web Portal.
3. To test the connection outside the AI tool, run this in a terminal on the same computer (macOS or Linux):

curl -i https://YOUR-PORTAL-URL/mcp/ -H "Authorization: Basic BASE64-VALUE" -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"ping"}'

On Windows, use Command Prompt (cmd) and this version:

curl -i https://YOUR-PORTAL-URL/mcp/ -H "Authorization: Basic BASE64-VALUE" -H "Content-Type: application/json" -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"ping\"}"

If it worked, you'll see HTTP 200 and a reply ending in "result":{}. That means the address is reachable and the login was accepted. If you get an error, see Troubleshooting.

Troubleshooting

• Supply HTTP Basic authentication (HTTP 403): the Authorization header is missing or in the wrong format. It must be Basic, one space, then the Base64 value. Sending the Base64 value without Basic causes this error.
• Feature unavailable (HTTP 400) when you run the curl test: MCP isn't enabled for your account. Email support@magnusbox.com.
• malformed payload when you run the curl test: the quotes in the -d part got lost, usually in PowerShell. Use the Command Prompt version above. Your address and login are fine.
• Feature unavailable for your user account in an AI answer or tool result: that tool needs permissions the login you connected with doesn't have. The connection itself is fine.
• Claude Code: claude mcp list shows ✘ Failed to connect: the line includes the HTTP status. For 403, check the sign-in value, then remove the server and add it again.
• spawn npx ENOENT in Claude Desktop: Node.js isn't installed or can't be found. Install Node.js 18 or later, then fully quit and reopen Claude Desktop. On Windows, if it still fails, run where npx in a terminal and put the full path it prints (ending in npx.cmd) in the "command" value. Type each backslash twice, for example "command": "C:\\Program Files\\nodejs\\npx.cmd".
• Claude Desktop doesn't show magnus-box after a restart (Windows): check that you quit from the system tray. If it still doesn't appear, Claude Desktop may be reading a second copy of the file at %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json. Put the same content in that file, then quit and reopen. If it still won't load, use Claude Code instead.
• Server disconnected in Claude Desktop: this is a generic message. Run the curl test above to see the real error. Claude Desktop also writes a log named mcp-server-magnus-box.log in ~/Library/Logs/Claude (macOS) or %APPDATA%\Claude\logs (Windows).
• A syntax error after you edit a JSON config file: look for a missing or extra comma near the line it mentions. Compare your file with Claude Desktop Example B.
• The AI tool is slow or uses a lot of context: around 80 tools (more with write access) take up room in the AI's context window. Most AI tools let you turn on only the tools you need.
• A tool you used before has changed or gone: MCP is still evolving, and the tool names and descriptions may change as Magnus Box is updated. Don't build scripts that rely on a specific tool name. For stable automation, use the API instead (see API Reference).

Need a hand getting connected? Email support@magnusbox.com and we'll walk through it with you.

Related articles

• API Reference
• Configure two-factor authentication