Developer & advanced setup

Connect the Real Wave MCP server

One MCP connection brings your Real Wave AI agents into Claude, ChatGPT, Cursor, VS Code, Codex and other MCP-capable clients. This page has the endpoint, auth (OAuth 2.1 sign-in or token), the available tools, a raw verification flow and troubleshooting. Non-technical? The simple overview is a friendlier read.

Endpoint
https://mcp.realwave.com/mcp
Transport
Streamable HTTP
Auth
OAuth 2.1 sign-in · or Bearer token
Two ways to connect. Sign-in (OAuth 2.1) is the easy path — point your client at the endpoint and sign in with your Real Wave account; no token, no client ID. Or send a Bearer token from realwave.com/settings/api-keys for apps that don't sign in (e.g. Manus) or for CI/scripts. A paid Real Wave plan is required either way.
Step 1

Add the server to your AI client

Pick your client below. Most connect by sign-in (just the URL); where a token is shown, replace YOUR_API_TOKEN with one from your Real Wave settings.

Sign-in connect (OAuth 2.1) — nothing to configure. Point your client at https://mcp.realwave.com/mcp and sign in. The server implements the current MCP auth spec: it advertises a protected-resource + authorization-server, mandates PKCE (S256), and issues scoped, revocable reference tokens. Clients register automatically — Claude and ChatGPT via client-ID metadata documents (CIMD), VS Code / Cursor / Codex via dynamic client registration (RFC 7591) — so there's no client ID to paste. Manage or revoke any connection from your Real Wave settings. The token setups below still work for every client, unchanged.

Sign in (recommended) — Claude Code registers automatically via CIMD; nothing to paste:

terminal
claude mcp add --transport http realwave https://mcp.realwave.com/mcp
# then run /mcp in Claude Code and sign in

Or with a token: append --header "Authorization: Bearer YOUR_API_TOKEN". Verify with claude mcp list.

Sign in (recommended)Settings → Connectors → Add custom connector, paste https://mcp.realwave.com/mcp, leave the OAuth fields blank, click Connect and sign in.

Or bridge with a token via mcp-remote in claude_desktop_config.json:

claude_desktop_config.json
{
  "mcpServers": {
    "realwave": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp.realwave.com/mcp",
        "--header",
        "Authorization: Bearer YOUR_API_TOKEN"
      ]
    }
  }
}

Restart Claude Desktop. The Real Wave tools appear under the connectors / tools menu.

Sign in — ChatGPT custom connectors are OAuth-only (it registers via CIMD):

  1. Open Settings → Apps & Connectors and enable Developer mode (Advanced). Requires a plan that allows custom connectors (Pro/Team/Enterprise/Edu).
  2. Create a custom connector, paste https://mcp.realwave.com/mcp, and choose OAuth.
  3. Click Connect, sign in with your Real Wave account, and press Allow.

No client ID or secret needed — leave the Advanced OAuth fields blank.

Sign in (recommended) — add the URL with no headers; Cursor auto-registers via DCR and opens a browser to sign in:

~/.cursor/mcp.json · sign-in
{
  "mcpServers": {
    "realwave": { "url": "https://mcp.realwave.com/mcp" }
  }
}

Or pin a token with a headers block:

~/.cursor/mcp.json · token
{
  "mcpServers": {
    "realwave": {
      "url": "https://mcp.realwave.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_TOKEN" }
    }
  }
}

Open Settings → MCP and confirm realwave shows a green/connected status.

Sign in (recommended) — add the URL with no headers; VS Code auto-registers via DCR and prompts you to sign in:

.vscode/mcp.json · sign-in
{
  "servers": {
    "realwave": { "type": "http", "url": "https://mcp.realwave.com/mcp" }
  }
}

Or add a token header (store it as a secret input, not inline):

.vscode/mcp.json · token
{
  "servers": {
    "realwave": {
      "type": "http",
      "url": "https://mcp.realwave.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_TOKEN" }
    }
  }
}

Start the server from the MCP view and use it in Copilot Chat (Agent mode).

Sign in (recommended) — add the server, then log in; Codex auto-registers via DCR:

~/.codex/config.toml
[mcp_servers.realwave]
url = "https://mcp.realwave.com/mcp"
# some builds: experimental_use_rmcp_client = true
terminal
codex mcp login realwave  # opens the browser to sign in

Prefer a token? Set bearer_token_env_var = "REALWAVE_TOKEN" under the server and export that variable.

Manus doesn't run the OAuth sign-in flow for custom servers — connect it with a token.

In Manus: Settings → Connectors → Add custom MCP server → Direct configuration. Set Transport HTTP, Server URL https://mcp.realwave.com/mcp, and add a custom header:

custom header
Authorization: Bearer YOUR_API_TOKEN

Get the token at realwave.com/settings/api-keys, then Test the connection to load the tools.

Sign in — Hermes Agent (Nous Research) registers itself via dynamic client registration. Add the Real Wave MCP server to its MCP config with the HTTP transport and this URL:

Hermes MCP config
url: https://mcp.realwave.com/mcp

Trigger the server in Hermes — it opens your browser to sign in (OAuth 2.1 + PKCE, loopback callback) and caches the token. No client ID to configure.

Sign in — in Lovable, open Chat → Connectors → Add custom MCP server, give it a name, and paste the Server URL, then Add & authorize:

server URL
https://mcp.realwave.com/mcp

Lovable registers itself and opens the OAuth sign-in — approve, and the Real Wave tools appear in chat. Newly supported; if the connector doesn't complete, let us know and we'll tune it.

Reference

The four tools

Once connected, your client can call these. Run tools/list after initialize for each tool's exact input schema.

realwave_list_agents

List the Real Wave agents available to your account.

location_id (optional)

realwave_get_agent

Get one agent's details and capabilities.

agent_idlocation_id (optional)

realwave_chat_with_agent

Send a message to an agent and get its reply. Pass a conversation_id to continue a thread.

agent_idmessageconversation_idlocation_idcontact_id

realwave_clear_conversation

Reset a conversation thread so the next message starts fresh.

conversation_id
Quickstart

Your first GHL workflow, by chat

The Workflow Builder is Real Wave's flagship ability — your AI creates real, native GoHighLevel workflows (triggers, SMS/email steps, waits, if/else branches). Paste this into your connected AI client to try it:

first-workflow prompt
Using my Real Wave connection: list my agents, then ask the workflow
(GHL API) agent to build this workflow in my sub-account:

When a lead replies "YES" to my first text, send them my booking link.
Wait 2 days for an appointment. If they still have not booked, send an
internal notification to my sales manager.

Have the agent confirm the plan first, then create the workflow and
give me its name so I can open it in my GHL builder.
Workflow builds are multi-step jobs — one realwave_chat_with_agent call can take a couple of minutes while the agent creates and wires the steps. Keep the same conversation_id and ask for changes in follow-up messages ("add a Hot Lead tag after the trigger") instead of re-describing the whole workflow. Batch requests ("add these 4 steps") work great.
Reference

Conversation & scoping

Optional parameters that control memory and which account/contact an agent acts on.

ParameterApplies toWhat it does
conversation_id chat / clear Hybrid threading: pass your own id to keep a thread, or reuse the id the server returns. Omit it to start a fresh exchange. Clearing a thread resets its memory.
location_id list / get / chat Scope to a specific GoHighLevel sub-account (location), so the agent reads and acts within that account.
contact_id chat Give the agent a specific CRM contact for context, so its actions and replies are about that person.
The chat tools are non-interactive: one request returns one reply. They don't hold a live, streaming back-and-forth — continuity comes from reusing the conversation_id.
Reference

Rate limits

Requests to the MCP endpoint are limited per organization, per minute, according to your Real Wave plan.

PlanRequests / minute
Basic30
Pro60
Agency180
Going over your limit returns 429 Too Many Requests with a Retry-After header — pause briefly and retry. Need more throughput? Explore higher plans.
Verify

Raw verification with curl

Confirm auth and tools end-to-end before wiring up a client. Streamable HTTP needs an Accept header listing both JSON and SSE.

1 — Initialize

initialize
curl -sS https://mcp.realwave.com/mcp \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "curl", "version": "1.0" }
    }
  }'
The response includes an Mcp-Session-Id header. Echo it back on every following request: -H "Mcp-Session-Id: YOUR_SESSION_ID".

2 — List tools

tools/list
curl -sS https://mcp.realwave.com/mcp \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
  -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }'

3 — Call a tool

tools/call · realwave_chat_with_agent
curl -sS https://mcp.realwave.com/mcp \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "realwave_chat_with_agent",
      "arguments": {
        "agent_id": "REPLACE_WITH_AGENT_ID",
        "message": "Summarize my newest lead and suggest a next step.",
        "conversation_id": "optional-thread-id"
      }
    }
  }'

Argument names follow the schema returned by tools/list — trust that over this example if they ever differ.

Help

Troubleshooting

SymptomLikely causeFix
401 Unauthorized Missing or invalid token Check the Authorization: Bearer header; regenerate the token at /settings/api-keys.
402 / “plan required” No active paid plan Connecting requires a paid Real Wave plan. See plans.
406 Not Acceptable Missing SSE accept type Send Accept: application/json, text/event-stream.
Session / “not initialized” errors Not echoing the session id Pass the Mcp-Session-Id header returned by initialize on every request.
Tools don't show up Client cached the server / not restarted Restart the AI app, then re-check the URL and header. Re-run tools/list to confirm.
Sign-in won't complete Client can't auto-register, or wrong URL Confirm the URL is https://mcp.realwave.com/mcp and leave any OAuth client-ID field blank. Some clients (e.g. Manus) don't sign in — use a Bearer token instead.
For AI agents

Machine-readable connection brief

If you are an AI assistant helping a user connect, here is everything you need.

realwave-mcp.txt
name: Real Wave MCP
endpoint: https://mcp.realwave.com/mcp
transport: streamable-http
auth: OAuth 2.1 (authorization-code + PKCE S256) OR header "Authorization: Bearer <REALWAVE_API_TOKEN>"
oauth: live; discover via /.well-known/oauth-protected-resource then /.well-known/oauth-authorization-server
oauth_registration: CIMD (client_id metadata document) or dynamic client registration (RFC 7591 at /oauth/register); no manual client_id
token_url: https://realwave.com/settings/api-keys (token path; also for apps that can't sign in, e.g. Manus)
requires: paid Real Wave plan
accept_header: application/json, text/event-stream
session: echo the Mcp-Session-Id header returned by initialize
interaction: non-interactive (one request -> one reply)

tools:
  - realwave_list_agents:     list agents on the account; optional location_id
  - realwave_get_agent:       agent details; agent_id; optional location_id
  - realwave_chat_with_agent: message an agent; agent_id + message;
                              optional conversation_id, location_id, contact_id
  - realwave_clear_conversation: reset a thread; conversation_id

discovery: call tools/list after initialize for exact input schemas