Skip to content

How Do I Connect Claude Desktop to WaveBrain?

Connect Claude Desktop to WaveBrain: add the mcp-remote entry to claude_desktop_config.json with your API key, restart Claude and log a test action.

Reviewed by WaveBrain Operations TeamReviewed 7 min read

The short answer

To connect Claude Desktop to WaveBrain, add a wavebrain entry that runs npx -y mcp-remote https://getwavebrain.com/api/mcp with your API key in an Authorization header to claude_desktop_config.json, then fully quit and reopen Claude. It needs Node.js 18 or newer. Ask Claude to log a test action, approve the tool call, and the entry appears on your WaveBrain timeline.

Claude Desktop is where many founders and ops people do their non-coding agent work: drafting and sending emails through a connector, updating a doc, posting to Slack. A week later it's hard to say which chat sent what, because the record is spread across conversations. Connecting Claude Desktop to WaveBrain gives each of those outside actions one line on a shared timeline.

The setup is one JSON entry in Claude's config file and a restart. This guide covers the exact entry, why it goes through a small bridge called mcp-remote, how to confirm the first log_action call, and what to check when nothing shows up.

What do you need before you start?#

You need the Claude desktop app, Node.js 18 or newer, a WaveBrain account and a WaveBrain API key. WaveBrain's free plan includes 1,000 actions a month, 7-day history and 2 API keys, with no credit card. Pro is $12 a month for 50,000 actions and 90-day history.

Node.js matters because of how Claude Desktop's config file works. The Model Context Protocol docs describe claude_desktop_config.json as the way to run local MCP servers, and WaveBrain is a hosted server at https://getwavebrain.com/api/mcp. The mcp-remote package bridges the two: Claude starts it like a local server, and it forwards each call to WaveBrain over HTTPS with your key. Its README says Claude Desktop uses your system's Node, even if a newer version is installed elsewhere. Run node --version in a terminal to check.

How do you connect Claude Desktop to WaveBrain step by step?#

You connect Claude Desktop by adding WaveBrain to claude_desktop_config.json as an mcp-remote server, then restarting the app. It takes about three minutes.

  1. Create a free WaveBrain account, open the Setup page in the dashboard and pick Claude Desktop.
  2. Click "Create a key for Claude Desktop". The page fills the key into the snippet. Copy it now, because it is shown only once and isn't kept after you leave the page.
  3. In Claude Desktop, open the Claude menu in your system's menu bar (not the settings inside the chat window), choose Settings, open the Developer tab and click Edit Config. The MCP docs say this creates the file if it doesn't exist.
  4. Merge this entry into mcpServers, keeping any servers already in the file.
{
  "mcpServers": {
    "wavebrain": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://getwavebrain.com/api/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}
  1. Save the file, then quit Claude Desktop completely and reopen it. The MCP docs say the app has to fully restart to load the new config.
  2. Optional, for consistent logging. Paste WaveBrain's logging rules from the Setup page into the instructions of the Claude project you work in.

The file lives at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows. The MCP docs list ~/.config/Claude/claude_desktop_config.json for Linux.

Why does the key go in env instead of args?#

The key goes in env because of a bug the mcp-remote README documents. It says Cursor, Codex CLI and Claude Desktop on Windows don't escape spaces inside args when they start npx, which mangles a header like Authorization: Bearer <key>. The README's workaround is the one WaveBrain uses: put Authorization:${AUTH_HEADER} in args with no spaces, and keep the full Bearer <key> value in an environment variable, where spaces are fine.

The same README describes a --header-file option that reads headers from a file instead, so the credential stays out of the process arguments. Either way, the key sits in a file on your computer, so don't sync claude_desktop_config.json to a shared folder or paste it into a support chat.

Can you use a Claude custom connector instead?#

Sometimes, but it's a different route with different trade-offs. Claude's custom connectors add a remote MCP server by URL in Settings, and Claude's connector docs say a fixed API key can be sent as a request header. That request-header option is in beta for a limited set of organizations, and if you don't see a Request headers section when adding a connector, your organization doesn't have it yet.

Config file + mcp-remoteCustom connector
Where the connection startsYour computerAnthropic's cloud, per Claude's help center
Where it worksClaude Desktop on that computerclaude.ai, Claude Desktop and Cowork
Needs Node.jsYes, 18 or newerNo
How the API key is sentAuthorization header from envRequest headers (beta, limited organizations)
Shown on WaveBrain's Setup pageYesNo

WaveBrain's Setup page gives the config-file version because it works without the beta. Claude's help center also notes that local servers in claude_desktop_config.json aren't available in claude.ai or Cowork sessions, so actions taken there won't reach WaveBrain through this setup.

How do you confirm Claude Desktop is connected?#

You confirm the connection by checking that Claude lists the server, then logging one test action and finding it on your WaveBrain timeline.

  1. In a new chat, click the "+" (Add files, connectors, and more) button at the bottom left of the message box, hover over Connectors and choose Manage connectors. wavebrain should be in the list with its tools: log_action, start_session, end_session and list_actions.
  2. Ask: "Log a test action to WaveBrain titled Connected Claude Desktop to WaveBrain, type other, project test."
  3. Claude asks for permission before it uses the tool. Check the arguments, then allow it. Claude's connector docs advise choosing Always allow only for servers you trust.
  4. Open your WaveBrain activity log. The entry appears at the top within seconds, under the agent name Claude reported.

Then try a real task with an outside effect, such as sending an email through a connected mail tool. WaveBrain's server instructions tell agents to call log_action right after anything with external effects (emails or messages sent, posts, payments, config changes) without being asked, and to skip pure reads and research. A chat that only answers questions creates no entry, which is expected.

Why isn't Claude Desktop logging to WaveBrain?#

Most Claude Desktop setup problems come from the JSON file, Node.js or the key. Check these in order.

  • The server isn't listed. Check that the file is valid JSON and that wavebrain sits inside mcpServers, then quit and reopen Claude completely.
  • The server shows an error or never starts. Read the logs: the MCP docs put them in ~/Library/Logs/Claude on macOS and %APPDATA%\Claude\logs on Windows. mcp.log covers connections, and mcp-server-wavebrain.log holds the bridge's own output.
  • npx isn't found or fails. Install Node.js 18 or newer from nodejs.org and restart Claude, since it uses the system Node.
  • Calls fail with an authentication error. WaveBrain returns 401 for a missing or invalid key. Check that AUTH_HEADER reads Bearer followed by the full key, or create a new key on the Setup page.
  • Claude finishes tasks without logging. Add the logging rules to the project instructions, and check that the task actually changed something outside the chat.
  • Logging stops mid-month. The free plan rejects new actions after 1,000 in a month and resumes the next month.

For deeper debugging, the mcp-remote README describes a --debug flag that writes detailed logs to ~/.mcp-auth. If WaveBrain is unreachable, the log_action call returns an error in the chat and Claude can carry on with the task.

What does WaveBrain record from Claude Desktop?#

WaveBrain records only what Claude reports through log_action: an agent name, a type, a title, details, a project, a link, a status and optional metadata. It never receives your prompts, responses or conversations, never reads your files, stores API keys as hashes and keeps data in the United States.

Be clear about the limits. Claude Desktop has no WaveBrain plugin or hooks, so an action Claude forgets to report leaves no entry. WaveBrain is not a tamper-proof audit log, and it is not LLM tracing, so there are no token counts, costs, latency numbers or performance charts. Text Claude writes into an entry is not filtered for secrets on the server, so treat entries like notes a colleague could read.

If you also run coding agents, follow how to connect Claude Code to WaveBrain and both apps land on one timeline. For the non-technical side of running several AI workers, read how to keep track of what your AI employees are doing, or see which agents WaveBrain supports.

Frequently asked questions#

Does Claude Desktop support remote MCP servers?#

Through its config file it runs local servers, so a hosted server like WaveBrain goes through the mcp-remote bridge. Claude's custom connectors add remote servers by URL, but sending an API key header there is in beta for a limited set of organizations.

Where is claude_desktop_config.json?#

On macOS it's ~/Library/Application Support/Claude/claude_desktop_config.json, and on Windows %APPDATA%\Claude\claude_desktop_config.json. Settings, then Developer, then Edit Config opens it for you.

Do I need Node.js to connect Claude Desktop to WaveBrain?#

Yes. Claude starts mcp-remote with npx, and the mcp-remote README asks for Node.js 18 or newer.

Will Claude Desktop log to WaveBrain without being asked?#

Mostly. WaveBrain's server instructions tell Claude to log actions with outside effects without being asked. Adding the logging rules to your project instructions makes it more consistent.

How do I remove WaveBrain from Claude Desktop?#

Delete the wavebrain entry from claude_desktop_config.json and restart Claude. You can also delete the API key in the WaveBrain dashboard, which stops it working everywhere.

Sources#