Connect an external agent with MCP

Connect an external agent host to the hosted MCP endpoint and use the twelve tools.

Updated

Endpoints

  • Production: https://api.wavemaker.io/mcp
  • Staging: https://api-staging.wavemaker.io/mcp

The transport is Streamable HTTP. Sign-in is OAuth with the authorization code flow and PKCE (S256). Dynamic client registration and client ID metadata documents are supported, so leave the optional client ID and secret blank unless your host requires a published identity. Hosts discover the authorization server from https://api.wavemaker.io/.well-known/oauth-protected-resource/mcp.

A backend can skip OAuth and send a workspace key as Authorization: Bearer {key} on the MCP connection. Credentials.

In Wavemaker, Connections → Developer setup shows the /mcp URL for the signed-in workspace.

Scopes

Ask the host for read run write.

  • read: search, read and watch
  • write: write (files, uploads, job cancellation) and deliver
  • run: generate, edit, compose, listen, compare, review and run

A read-only grant can't generate. Reconnect after a scope change; refreshing an existing grant doesn't add scopes. The host's tool-approval prompt is not a Wavemaker receipt.

Claude

On Claude web or desktop: Customize → Connectors → + → Add custom connector.

  1. URL: https://api.wavemaker.io/mcp (or the staging URL).
  2. Leave the OAuth Client ID and Client Secret under Advanced settings blank. If the host offers a transport choice, choose Streamable HTTP.
  3. Connect and complete the Wavemaker sign-in. Consent should list read, run and write.
  4. Turn the connector on in the conversation's tools menu.

Team and Enterprise owners add the connector in organization settings first. Claude custom connectors.

ChatGPT

  1. Turn on Settings → Security and login → Developer mode.
  2. Open ChatGPT Plugins, choose +, name the connection and enter the full /mcp URL.
  3. Choose OAuth if asked.
  4. Complete the Wavemaker sign-in, review the tools, then add the connection to a new conversation.

Connect ChatGPT.

Cursor

The hosted sign-in doesn't accept Cursor's cursor:// callback. Use mcp-remote and pin the scopes:

{
  "mcpServers": {
    "wavemaker": {
      "command": "npx",
      "args": [
        "-y",
        "[email protected]",
        "https://api.wavemaker.io/mcp",
        "--static-oauth-client-metadata",
        "{\"scope\":\"read run write\"}"
      ]
    }
  }
}

Save this in ~/.cursor/mcp.json beside your other servers, restart Cursor, complete the browser consent, and start a new agent chat. Use the staging /mcp URL for staging. Tokens stay in the adapter's cache, not in this file. mcp-remote.

Grok

On grok.com: Plugins → New Connector → Custom, enter the /mcp URL, then complete the Wavemaker sign-in.

Other hosts

Any host that supports remote MCP over Streamable HTTP with OAuth connects the same way. Hosts cache tools/list: after a service update, refresh the connector and start a new conversation.

The tools

The server exposes the twelve tools: search, read, write, generate, edit, compose, watch, listen, compare, review, deliver and run. Each takes the same arguments as POST /v1/tools/{tool}, flattened, plus optional project and request_id. Each returns the core envelope {ok, data, error, job, cost, hints} as structured content and as JSON text; a refusal also sets MCP isError.

  • Find things: search with kinds (model, graph, route, card, style, format, font, node, example, past_work, web and more), then read the wm:// URI each result returns.
  • Spend safely: generate, edit, compose, listen, compare, review and run can spend. Pass a request_id; the same id again returns the original result. Price first with quote_only: true.
  • Follow jobs: long work returns a job. Read wm://job/{id} with wait_s (at most 25) until it is succeeded, failed or cancelled. A wait that times out is not a failure; read again, never resubmit. Cancel with write and {"uri": "wm://job/{id}", "cancel": true}.
  • Move bytes: small files can be written with write and content_base64. For larger files, write with upload returns a presigned PUT link; PUT the bytes, then write with the returned commit. read of wm://artifact/{sha256} returns the artifact's facts and a signed download link; verify the bytes against the sha256.
  • Deliver: deliver with an artifact under a delivery_* role and a destination checks it against that destination's spec and records the delivery.

The older MCP tools (discover_operations, execute_operation, prepare_generation, watch_job, watch_compute and the rest) no longer exist. The hosted agent session is an HTTP API, not an MCP tool: Make an ad.

Quote and run work · Errors and retries · Capability map · Credentials

Related guidance