Connect your agent

Choose your connection method

Choose your client below. Replace https://YOUR_WAVEFORM_HOST with your Waveform app origin and use its /mcp endpoint. Your client or organization may require an administrator to enable MCP connections.

Use a private WAVEFORM_API_KEY environment variable for clients supporting headers. Launch the client from an environment where that variable is available. The JSON/TOML below stores the variable name, not its value. Verify identity_get before any mutation.

Codex

Add this to your Codex config.toml. HTTP MCP supports a bearer-token environment variable. Restart or reconnect the server, then ask Codex to use Waveform’s identity_get tool.

[mcp_servers.waveform]
url = "https://YOUR_WAVEFORM_HOST/mcp"
bearer_token_env_var = "WAVEFORM_API_KEY"
tool_timeout_sec = 30

For OAuth instead, omit bearer_token_env_var and run the following. Use it only when the deployment advertises OAuth and Client ID Metadata Documents. Complete the browser workspace/scopes review.

codex mcp login waveform --oauth-client-registration cimd

Official Codex MCP configuration

Claude Code

Use a project .mcp.json containing this HTTP server. Claude Code expands environment variables in headers. Check the server with /mcp and call identity_get. Keep project configuration free of literal keys.

{
  "mcpServers": {
    "waveform": {
      "type": "http",
      "url": "https://YOUR_WAVEFORM_HOST/mcp",
      "headers": {
        "Authorization": "Bearer ${WAVEFORM_API_KEY}"
      }
    }
  }
}

Official Claude Code MCP configuration

Cursor

Add a server to .cursor/mcp.json for the project, or ~/.cursor/mcp.json for your user. Cursor uses ${env:NAME} interpolation in headers; remote servers do not use envFile. Enable the server in MCP settings and verify identity_get.

{
  "mcpServers": {
    "waveform": {
      "url": "https://YOUR_WAVEFORM_HOST/mcp",
      "headers": {
        "Authorization": "Bearer ${env:WAVEFORM_API_KEY}"
      }
    }
  }
}

Official Cursor MCP configuration

VS Code / GitHub Copilot

For VS Code’s MCP configuration, add this to .vscode/mcp.json. The masked input avoids a literal key in the file. Use MCP: List Servers and enable Waveform for the agent. The Agent Host does not read this file directly; follow the official reference’s portable .mcp.json guidance if you use that separate runtime.

{
  "inputs": [
    {
      "type": "promptString",
      "id": "waveform-key",
      "description": "Waveform API key",
      "password": true
    }
  ],
  "servers": {
    "waveform": {
      "type": "http",
      "url": "https://YOUR_WAVEFORM_HOST/mcp",
      "headers": {
        "Authorization": "Bearer ${input:waveform-key}"
      }
    }
  }
}

Official VS Code MCP configuration

ChatGPT remote MCP

Use a publicly reachable HTTPS Waveform origin with OAuth enabled. In ChatGPT on the web, enable Developer mode in Settings → Security and login, then create a developer-mode app from ChatGPT Plugins. Set the /mcp URL, choose OAuth and Client ID Metadata Documents (CIMD) with public-client token exchange (none). Complete Waveform’s consent screen and select the app in your conversation.

Availability depends on your ChatGPT account and organization settings. Waveform requires authentication; do not choose No Authentication or paste a workspace key into a URL. It supports CIMD and configured public clients, not open dynamic client registration. An unknown-client error means the registration mode or client metadata needs attention, not that authentication should be bypassed. Call identity_get, then name the requested tool explicitly if needed.

Official ChatGPT developer-mode setup

When OAuth is configured, discovery is at /.well-known/oauth-protected-resource/mcp on your trusted studio origin.

Troubleshoot without repeating work

• 401: check key expiry, revocation or OAuth consent, then reconnect.
• 403: check credential scopes, workspace role and client Origin behavior. Browser-only account/payment tools cannot be unlocked by adding an API-key scope.
• Tool absent: refresh discovery and confirm that the service is configured and your credential has its scope.
• A disconnected watch: reconnect and read saved state; it did not cancel the job.
• An image too large for inline delivery: fetch its authenticated artifact URL with the same workspace credential. Original bytes are never silently resized.
• A 409 after retry: keep the old intent intact, read current versions, and make a new request only for a new user action.