Skip to content

How Do I Connect Claude Code to WaveBrain?

Connect Claude Code to WaveBrain in about two minutes: create an API key, run one claude mcp add command, test it, and fix the usual setup problems.

Reviewed by WaveBrain Operations TeamReviewed 6 min readPublished

The short answer

To connect Claude Code to WaveBrain, create an API key on the WaveBrain Setup page, then run claude mcp add --transport http --scope user wavebrain https://getwavebrain.com/api/mcp with an Authorization: Bearer header carrying your key. Start a new session, ask Claude to log a test action, and check that it appears on your WaveBrain timeline.

You have Claude Code shipping changes across three repositories, and you want one place that says what it deployed, pushed and merged without opening each terminal. WaveBrain is that place, and Claude Code talks to it over MCP, so setup is one command and a test.

This guide walks through the steps in order, shows how to confirm everything works, and covers the problems people hit most often. It assumes Claude Code is installed and you can run claude in a terminal.

What do you need before you start?#

You need a WaveBrain account, a WaveBrain API key and Claude Code. The free plan includes 1,000 actions a month, 7-day history and 2 API keys, with no credit card, so you can test everything before deciding anything.

WaveBrain is a hosted MCP server at https://getwavebrain.com/api/mcp that uses stateless Streamable HTTP and a bearer token. Claude Code's MCP docs call remote HTTP servers "the recommended option for connecting to remote MCP servers", so no local process or Node.js install is needed.

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

You connect Claude Code to WaveBrain by adding it as a user-scoped HTTP MCP server with your API key in the Authorization header. The whole process takes about two minutes.

  1. Create a free WaveBrain account and open the Setup page in the dashboard.
  2. Pick Claude Code, then create an API key. Copy it right away, because the page shows it only once.
  3. Run this command in your terminal, replacing <YOUR_API_KEY> (the Setup page fills it in for you).
claude mcp add --transport http --scope user wavebrain https://getwavebrain.com/api/mcp \
  --header "Authorization: Bearer <YOUR_API_KEY>"
  1. Optional, for non-interactive runs. If you start Claude Code with claude -p or a narrow --allowedTools list, add "mcp__wavebrain__*" to permissions.allow in ~/.claude/settings.json, keeping anything already in the list.
{
  "permissions": {
    "allow": ["mcp__wavebrain__*"]
  }
}
  1. Optional, for consistent logging. Add WaveBrain's logging rules from the Setup page to ~/.claude/CLAUDE.md, which Claude Code's memory docs describe as your personal instructions for all projects.
  2. Start a new Claude Code session so it loads the server.

The --scope user flag matters. Claude Code's MCP docs say user-scoped servers are stored in ~/.claude.json and are available across all projects on your machine, while the default local scope only applies to the current project.

Is there a plugin instead of the MCP command?#

Yes, WaveBrain has an open source Claude Code plugin that adds the MCP server, a skill that tells Claude when to log, and auto-capture hooks. Install it with two commands.

claude plugin marketplace add tambo-ai-labs/wavebrain
claude plugin install wavebrain@wavebrain

The plugin asks for your API key and keeps it in the system keychain. Its hooks queue high-stakes tool calls such as deploys, pushes and merges in ~/.wavebrain/queue and send them at the end of each turn, after redacting secrets on your machine. Our guide on how to log every action Claude Code takes explains how hooks and the MCP server work together. Use either the plugin or the claude mcp add command, not both, so you don't end up with two wavebrain servers.

How do you confirm Claude Code is connected?#

You confirm the connection by checking that the server is listed, then logging one test action and finding it on your timeline. The MCP docs list three checks.

  1. Run claude mcp list in a terminal. You should see wavebrain with its URL.
  2. Run claude mcp get wavebrain to see its details.
  3. Inside a Claude Code session, type /mcp to check the server's status.

Then ask Claude Code something like "Log a test action to WaveBrain titled Connected Claude Code to WaveBrain, type other, project test." Claude calls the log_action tool, and the entry should appear at the top of your WaveBrain activity timeline within a few seconds, with claude-code (or whatever agent name Claude chose) as the agent. Agent names are stored in lowercase.

For a real test, give Claude a task with an outside effect, such as pushing a branch. The server's instructions tell Claude to log actions with external effects (posts, emails, deploys, config changes and similar) right after they happen without being asked, and to skip pure reads, so a session that only reads code will not create entries.

Why isn't Claude Code logging to WaveBrain?#

Most setup problems come from the key, the scope or an old session. Work through these in order.

  • The server is missing from claude mcp list. You probably ran the command without --scope user in a different directory, which adds a project-local server. Run it again with --scope user.
  • /mcp shows the server as failed or the tool returns an authentication error. WaveBrain answers 401 for an invalid key. Check that the header reads Authorization: Bearer <key> with no extra quotes, or create a new key and re-add the server with claude mcp remove wavebrain first.
  • Nothing appears after a task. Start a new session after adding the server, check that the task had an outside effect, and add the logging rules to ~/.claude/CLAUDE.md if Claude skips logging.
  • claude -p runs never log. Add "mcp__wavebrain__*" to permissions.allow as in step 4.
  • Logging stopped mid-month. The free plan rejects new actions after 1,000 in a month (the REST API returns 402) and resumes next month, and your history is kept.

If WaveBrain is unreachable for any reason, Claude Code keeps working. The log_action call returns an error and the task continues.

What does WaveBrain record from Claude Code?#

WaveBrain records only what Claude Code reports and what the plugin hooks capture: a title, details, project, link, status and optional metadata for each action. It never reads your repository or files and never receives your prompts, responses or conversations. API keys are stored as hashes, and data is stored in the United States.

Text that Claude writes into an entry is not filtered for secrets on the server, so treat entries like commit messages. WaveBrain is also not a tracing tool, so you won't see tokens, costs or latency. See what gets logged for the full list. Once Claude Code is connected, Codex connects the same way, and all agents share one timeline. If you also use Cursor, see how to connect Cursor to WaveBrain. For email, docs and other non-coding work in the Claude app, see how to connect Claude Desktop to WaveBrain.

Frequently asked questions#

Where does Claude Code save the WaveBrain MCP server?#

With --scope user, Claude Code stores the server in ~/.claude.json in your home directory, which makes it available in every project on that machine.

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

No. WaveBrain is a remote HTTP MCP server, so Claude Code connects to it directly with --transport http and no local bridge.

Does Claude Code log every tool call to WaveBrain?#

No. Claude logs actions with outside effects, such as deploys, pushes, merges, emails and config changes, and skips reads. The plugin's hooks add high-stakes tool calls the agent forgot to log.

Can I connect Claude Code on several machines to one WaveBrain account?#

Yes. Run the same command on each machine with a key from the same workspace, and every machine's actions land on one timeline. The free plan allows 2 API keys.

How do I disconnect Claude Code from WaveBrain?#

Run claude mcp remove wavebrain, or uninstall the plugin if you used it. You can also delete the API key in the WaveBrain dashboard.

Sources#