Claude Desktop MCP Setup: Add Servers, Config & Fixes

Claude Desktop is powerful out of the box, but on its own it has no idea what is happening inside your business. It cannot see how many visitors converted yesterday, which ad campaign is bleeding money, or which customer just churned. The Model Context Protocol (MCP) closes that gap: it is an open standard that lets an AI client like Claude Desktop call live tools and read live data from an external server you control.

BusinessMCP turns your entire company into exactly that kind of server. You connect your tools, databases, ad platforms and Stripe revenue once, install a single tracking script, and we unify everything into one hosted MCP endpoint. When you point Claude Desktop at that endpoint, Claude stops guessing and starts answering from your real numbers — the same numbers your dashboard shows.

The result is a single, model-agnostic source of truth. The endpoint you connect to Claude today works identically with GPT, Gemini, or any other MCP-capable agent tomorrow. You are never re-plumbing your data for a new model.

Claude Desktop now has two connection paths, and picking the right one saves you the most common frustration. The newer Connectors flow (Settings → Connectors → Add custom connector) is for remote MCP servers: paste an https URL, authenticate, done — no JSON, no local processes. If the server you want lives on the web (like a hosted BusinessMCP endpoint), start here.

The classic config-file flow — editing claude_desktop_config.json — is for local servers that run as a process on your machine (anything started with npx or node), and it remains the fallback on versions or setups where the Connectors UI is not available. This guide covers both, then the troubleshooting for each.

You need three things: a BusinessMCP workspace, at least the tracking script installed so events are flowing, and a Claude Desktop install on macOS or Windows. If you have not onboarded yet, the wizard walks you through the business context, goals and the one required step — pasting the tracking snippet onto your site.

You also need an API key. In BusinessMCP these are Bearer keys prefixed with mcph_ and scoped to a single workspace. Generate one from Settings, treat it like a password, and never commit it to a public repo. The key is what authorizes Claude Desktop to read your unified data through the /api/mcp endpoint.

Optionally, connect a few source tools first — Stripe, Google Search Console, your ad accounts — so there is richer data for Claude to query on day one. None of these are required to get a working connection, but they make the first conversation far more useful.

Claude Desktop reads local MCP servers from a JSON file named claude_desktop_config.json — the same file the official MCP quickstart walks through. On macOS the full path is ~/Library/Application Support/Claude/claude_desktop_config.json; on Windows it is %APPDATA%\Claude\claude_desktop_config.json. If the file does not exist, create it — or let the app create it for you via Settings → Developer → Edit Config, which opens the right file in the right place and is the safest route.

The structure is one top-level mcpServers object with one named entry per server. A local server entry has a command (the executable, for example npx or node) and an args array; a remote entry points at a URL. Keep the JSON strictly valid: straight quotes only, and no trailing comma after the last entry — a trailing comma is the single most common reason a config silently fails to load.

After any edit, save and fully quit Claude Desktop — actually quit the app (on Windows, exit it from the system tray), not just close the window — then reopen it. The config is only read at startup. When it loads, your servers appear behind the tools icon in the message composer.

A minimal config that bridges a remote BusinessMCP endpoint through the mcp-remote package looks like this:

{
  "mcpServers": {
    "businessmcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-endpoint.example.com/api/mcp",
        "--header",
        "Authorization: Bearer mcph_your_key_here"
      ]
    }
  }
}

For a hosted server like your BusinessMCP endpoint, paste the https URL of your workspace endpoint — it ends in /api/mcp — into a client that supports bearer auth: Claude Desktop, Claude Code, Cursor or VS Code. BusinessMCP speaks the streamable HTTP transport, so there is nothing to install and no process to keep running. Note that Claude.ai’s web Connectors flow currently accepts OAuth credentials only and has no field for a Bearer token, so use one of the config-file clients above for a mcph_ key.

If your Claude Desktop version does not expose custom headers in the Connectors UI, the reliable fallback is the config file with a small bridge: an entry whose command is npx and whose args run the mcp-remote package with your endpoint URL and an Authorization header of "Bearer mcph_your_key_here". Either route ends in the same place: Claude discovers your tools and can query your live business data.

Start a new chat and ask something only your business data could answer: "How many visitors did we get this week and what was the conversion rate?" Claude will call the analytics tool on your MCP server, receive the numbers, and answer in plain language. If you see a tool-use indicator followed by a real figure, the connection is live.

If Claude says it cannot access any tools, the usual culprits are a malformed JSON config, a stale key, or the app not being fully restarted. Re-check that your Bearer key is current, that the URL ends in /api/mcp, and that the JSON has no trailing commas. BusinessMCP also logs every tool call, so you can confirm from the dashboard whether the request ever reached the server.

Once verified, the whole surface of your business is available conversationally. Ask Claude to pull ROAS by campaign, summarize new leads, or draft a follow-up email to a customer — each of those maps to a real tool on your hosted endpoint.

Server not appearing at all: Claude Desktop only reads the config at startup, so fully quit and reopen — on Windows that means Exit from the system tray icon, because closing the window leaves the app running. Then check the tools icon in the composer rather than the settings list.

Config seems ignored: it is almost always JSON. Run the file through any JSON validator; the usual culprits are a trailing comma after the last entry, curly quotes pasted from a document, or the file saved under a slightly wrong name or folder. Use Settings → Developer → Edit Config to be certain you are editing the file the app actually reads.

Errors like "command not found" or "spawn npx ENOENT": desktop apps do not inherit your shell PATH, so a command that works in your terminal can fail inside Claude. Use absolute paths — run "which node" or "which npx" in a terminal and put the full result in the command field. Node version managers (nvm, asdf) make this bite hardest.

Permission or environment errors: environment variables your server needs (API keys, tokens) go in an env block inside its config entry — the server does not see your shell exports. On macOS, a server reading protected folders may also need you to grant disk access to the terminal or to Claude.

When you need real evidence, read the logs. macOS: ~/Library/Logs/Claude — mcp.log for the client side and one mcp-server-NAME.log per server. Windows: the logs folder under %APPDATA%\Claude. For a remote server, check the server side too — BusinessMCP logs every tool call in the dashboard, so you can see whether a request ever arrived.

If the failure is on the Claude side rather than your server, the Claude Help Center covers app-level issues like sign-in, updates, and platform availability.

Your mcph_ key is a bearer credential: anyone who holds it can read your workspace data. Store it in a password manager, rotate it if it ever leaks, and use a separate key per machine or per agent so you can revoke one without breaking the others. BusinessMCP scopes each key to a single workspace and honors row-level security, so a key can never reach another tenant.

For shared or automated setups, prefer generating a dedicated key rather than reusing your personal one. When someone leaves the team or a laptop is lost, revoking that single key instantly cuts off access without disturbing anyone else.