# Connect your agent

Configuration recipes for Codex, Claude Code, Cursor, VS Code/Copilot and ChatGPT.

## 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.

```toml
[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.

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

[Official Codex MCP configuration](<https://learn.chatgpt.com/docs/extend/mcp?surface=cli>)

## 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.

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

[Official Claude Code MCP configuration](<https://code.claude.com/docs/en/mcp>)

## 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.

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

[Official Cursor MCP configuration](<https://cursor.com/docs/mcp>)

## 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.

```json
{
  "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](<https://code.visualstudio.com/docs/agents/reference/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](<https://developers.openai.com/api/docs/guides/developer-mode>)

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.