How Do I Connect Cursor to WaveBrain?
Connect Cursor to WaveBrain for MCP logging: add the server to ~/.cursor/mcp.json with your API key, approve log_action, and fix common setup problems.
Reviewed by WaveBrain Operations TeamReviewed 6 min read
The short answer
To connect Cursor to WaveBrain, add a wavebrain server with the URL https://getwavebrain.com/api/mcp and an Authorization: Bearer header holding your API key to ~/.cursor/mcp.json, or click Add to Cursor on the WaveBrain Setup page. Start a new chat, approve the log_action tool when Cursor asks, and your test entry appears on the WaveBrain timeline.
Cursor's agent can run a migration, push a branch and call a deploy script in one long chat. Two days later you know something went out, but not which chat did it or whether it worked. Connecting Cursor to WaveBrain gives each of those outside actions its own line on a timeline you can search after the chat is closed.
Cursor supports remote MCP servers with custom headers, so the setup is one JSON entry and a quick test. This guide covers the config, the one-click button, how to confirm a first log_action call, and what to check when nothing shows up.
What do you need before you start?#
You need the Cursor app, 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, and it needs no credit card. Pro is coming for bigger workloads.
WaveBrain is a hosted MCP server at https://getwavebrain.com/api/mcp, served over Streamable HTTP and authenticated with a bearer token. Cursor's MCP docs list Streamable HTTP among its three supported transports and show remote servers configured with a url and headers, so nothing has to run on your machine.
How do you connect Cursor to WaveBrain step by step?#
You connect Cursor by adding WaveBrain to your global mcp.json as a remote server that sends your key in an Authorization header. It takes about two minutes.
- Create a free WaveBrain account, open the Setup page in the dashboard and pick Cursor.
- Click "Create a key for Cursor". The page fills the key into the snippet below. Copy it now, because it is shown only once and isn't kept after you leave the page.
- Open
~/.cursor/mcp.json(create it if it doesn't exist) and merge this entry intomcpServers.
{
"mcpServers": {
"wavebrain": {
"url": "https://getwavebrain.com/api/mcp",
"headers": {
"Authorization": "Bearer <YOUR_API_KEY>"
}
}
}
}
- Save the file and start a new chat in Cursor.
- Optional, for consistent logging. Paste WaveBrain's logging rules from the Setup page into your Cursor User Rules or an
AGENTS.mdfile.
Cursor's docs give two places for this file. ~/.cursor/mcp.json in your home directory makes a server available in every project, and .cursor/mcp.json inside a project limits it to that project. Use the global file, because the project file usually ends up in Git and would carry your key with it.
Is there a one-click Add to Cursor button?#
Yes. Once you create a key on the Setup page, an "Add to Cursor" button appears next to the config. It opens Cursor, which asks you to confirm before it adds the server.
The button is a standard Cursor MCP install link. Cursor's install-link docs describe it as a cursor://anysphere.cursor-deeplink/mcp/install URL with the server name and the same JSON configuration that mcp.json uses, base64 encoded. WaveBrain builds the link from your new key, which is why the button only shows up after you create one.
A one-command Cursor installer that also adds auto-capture hooks is coming but is not open yet. Until it is, the MCP config above is the supported setup.
Can you keep the API key out of mcp.json?#
Yes, Cursor can read the key from an environment variable instead of the file. Cursor's MCP docs say it resolves variables in the url and headers fields, with ${env:NAME} for environment variables.
"Authorization": "Bearer ${env:WAVEBRAIN_API_KEY}"
Set WAVEBRAIN_API_KEY in your shell profile or system environment, as Cursor's docs suggest for remote servers, then restart Cursor so it picks the variable up. Remote servers do not support Cursor's envFile option, which only works for local stdio servers. If the variable is empty when Cursor starts, the header goes out as Bearer with no key and WaveBrain rejects the call, so paste the key directly if you are unsure.
How do you confirm Cursor is connected?#
You confirm the connection by checking that Cursor lists the server, then logging one test action and finding it on your WaveBrain timeline.
- Open Customize in Cursor's sidebar and check that
wavebrainis listed and switched on. Cursor's docs say disabled servers don't load or appear in chat. - In a new chat, ask: "Log a test action to WaveBrain titled Connected Cursor to WaveBrain, type other, project test."
- Cursor asks for approval before using MCP tools by default. Expand the call to see the arguments, then approve it.
- Open your WaveBrain activity log. The entry appears at the top within seconds, under an agent name like
cursor.
Then try a task with an outside effect, such as pushing a branch. WaveBrain's server instructions tell agents to call log_action right after anything with external effects (deploys, pushes, posts, emails, config changes) without being asked, and to skip pure reads. A chat that only reads and edits files will not create an entry, which is expected.
If you don't want to approve every log call, Cursor's docs say MCP tools follow the same Run Modes as terminal commands, so you can allowlist WaveBrain's tools there.
Why isn't Cursor logging to WaveBrain?#
Most Cursor setup problems come from the config file or the key. Check these in order.
- The server isn't listed in Customize. Check that the JSON is valid and that
wavebrainsits insidemcpServers, then restart Cursor. - The server shows an error. Open the Output panel (Cmd+Shift+U on macOS), pick "MCP Logs" from the dropdown and look for connection or authentication errors, as Cursor's FAQ describes.
- Calls fail with an authentication error. WaveBrain returns 401 for a missing or invalid key. Check that the header reads
Bearerfollowed by the full key, or create a new key on the Setup page and replace it. - The agent finishes tasks without logging. Add the logging rules to User Rules or
AGENTS.md, 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, and your history is kept.
If WaveBrain is unreachable, Cursor keeps working. Cursor's docs say a failed MCP call shows an error in chat and is marked as failed, and other servers keep running, so your task continues.
What does WaveBrain record from Cursor?#
WaveBrain records only what Cursor's agent reports through log_action. Each entry has an agent name, a type, a title, details, a project, a link, a status and optional metadata. It never reads your repository or files, never receives prompts, responses or conversations, stores API keys as hashes and keeps data in the United States.
Be clear about the limits. With the MCP config alone, Cursor has no WaveBrain hooks, so an action the agent forgets to report leaves no entry. WaveBrain is not a tamper-proof audit log, and it is not LLM tracing either, so there are no token counts, costs or latency numbers. Text the agent writes into an entry is not filtered for secrets on the server, so treat entries like commit messages.
To see how this compares with Cursor's checkpoints, Git and hooks, read the best ways to track Cursor agent changes. If you also use Claude Code, follow how to connect Claude Code to WaveBrain and both agents land on one timeline, or see which agents WaveBrain supports. For the bigger picture, read how to see what your AI agent did.
Frequently asked questions#
Where does Cursor store the WaveBrain MCP server?#
In ~/.cursor/mcp.json for every project, or .cursor/mcp.json inside one project. WaveBrain's Setup page uses the global file.
Does Cursor support remote MCP servers with an API key?#
Yes. Cursor's MCP docs show remote servers configured with a url and a headers object, and WaveBrain uses an Authorization: Bearer header with your API key.
Does Cursor log to WaveBrain automatically?#
Mostly. WaveBrain's server instructions tell the agent to log actions with external effects without being asked. Adding the logging rules to Cursor's User Rules or AGENTS.md makes it more consistent.
Can Cursor and Claude Code log to the same WaveBrain account?#
Yes. Connect each agent with a key from the same workspace and their actions land on one timeline, filterable by agent and project.
How do I remove WaveBrain from Cursor?#
Delete the wavebrain entry from ~/.cursor/mcp.json, or switch it off in Customize. You can also delete the API key in the WaveBrain dashboard.