# AgentPort MCP setup

Connect your coding agent once. Prefer browser sign-in (OAuth); a manually created API key is optional. Settings persist across restarts.

## Instructions for coding agents

- Follow only the section for the current coding agent. Use persistent user-level settings that survive restarts, not a temporary shell export.
- Back up the config and merge only the AgentPort entry. Preserve other servers and settings; update an existing entry rather than creating duplicate JSON keys or TOML tables.
- Prefer the browser sign-in instructions below. Do not create a key or add an Authorization header for OAuth. Remove only an obsolete AgentPort auth header or `bearer_token_env_var` when switching, with the user's approval. Never read or print existing secrets.
- Keep the response short: what changed, where the user signs in, and the connection check. Do not deploy anything during setup.
- Once authenticated, call `account:check` yourself to verify access. Do not ask the user to write another prompt for this check. If the client needs a restart before tools are available, give that single next action and explain that verification must resume afterwards. Only report a successful connection after the tool responds successfully; never deploy an app or spend credits as part of verification.
- If OAuth is unavailable in the installed client, offer the API-key fallback later in this document. Prepare its placeholder and let the user enter the key locally, never in chat.

## Recommended: browser sign-in

Use `https://mcp.agentport.cloud` with Streamable HTTP. Sign in to AgentPort in the browser and approve the connection. A claimed beta seat is required to use deployment tools. Never disable certificate checks or extract another app's credential store.

### Codex

Run once if the server is not already registered:

```sh
codex mcp add agentport_cloud --url https://mcp.agentport.cloud
codex mcp login agentport_cloud
```

Codex saves the server in its user config and manages OAuth separately. Do not add `http_headers` or an environment variable for this path. If needed, request persistent authorization explicitly with `codex mcp login agentport_cloud --scopes agentport:manage,offline_access`. Restart the session and check `/mcp`.

### Claude Code

```sh
claude mcp add --transport http --scope user agentport-cloud https://mcp.agentport.cloud
```

Run `claude mcp login agentport-cloud`, or select AgentPort in `/mcp` and authenticate. Existing installations may need only the login step.

### Cursor

Merge into the user `mcp.json` at the path in the table below, then choose Connect in MCP settings:

```json
{ "mcpServers": { "agentport-cloud": { "url": "https://mcp.agentport.cloud" } } }
```

### Windsurf Cascade

Open MCP settings and edit the raw configuration. Merge this entry, save, refresh and sign in:

```json
{ "mcpServers": { "agentport-cloud": { "serverUrl": "https://mcp.agentport.cloud" } } }
```

This is the legacy Cascade configuration, not the newer Devin Local agent configuration. Use the config file opened by the installed app when its path differs from the table.

### Gemini CLI

```sh
gemini mcp add --transport http --scope user agentport-cloud https://mcp.agentport.cloud
```

Inside Gemini, run `/mcp auth agentport-cloud` and follow the browser sign-in.

### OpenCode

Check the installed major version first. For v1, merge this into its user configuration, then run `opencode mcp auth agentport-cloud`:

```json
{
  "mcp": {
    "agentport-cloud": { "type": "remote", "url": "https://mcp.agentport.cloud", "enabled": true }
  }
}
```

OpenCode v2 uses `mcp.servers` instead. Its CLI can save the entry globally:

```sh
opencode mcp add agentport-cloud --global --url https://mcp.agentport.cloud
opencode mcp auth agentport-cloud
```

### VS Code / GitHub Copilot

Open the Command Palette, choose **MCP: Add Server**, select HTTP and enter `https://mcp.agentport.cloud`. Save to your user profile for all projects. Authenticate when prompted, then enable the tools in agent chat. **MCP: Open User Configuration** opens the actual saved file; workspace `.vscode/mcp.json` settings apply only to that project. Managed company devices may require administrator approval.

If editing that user configuration instead, merge into `servers`, preserving other entries:

```json
{ "servers": { "agentport-cloud": { "type": "http", "url": "https://mcp.agentport.cloud" } } }
```

These instructions target interactive VS Code / Copilot, not GitHub's cloud agent or code review, which do not currently support OAuth remote MCP. Do not promise that a VS Code connection also installs the server in those environments.

### Grok Bot

Grok Bot manages custom MCP connectors through chat, not Cursor's editor config. Ask:

```text
Add this MCP server: https://mcp.agentport.cloud. Use browser sign-in. After connecting, run AgentPort's account:check. Do not deploy anything or spend credits.
```

Confirm the server details and complete AgentPort sign-in. If authentication is still pending, open **Connect apps**, select AgentPort and authenticate. Tools may become available only in the next message; then call `account:check` before reporting success. Do not paste API keys into chat or edit a Cursor config for Grok Bot.

The connector uses a public HTTPS endpoint. Connecting does not give the bot your local files or a working Docker installation. For source builds, confirm an accessible build environment and registry login separately; never extract protected OAuth credentials. Grok Bot native-client validation and directory listing are pending.

### Verify, without deploying

Use the dashboard's installation panel to copy the setup message or view manual instructions. After authorization, the agent should call `account:check` and report the result in your coding tool. There is no dashboard setup wizard.

If the agent has not checked yet, ask: "Use AgentPort's account:check tool to verify my connection. Do not deploy anything or spend credits." Installing a config or approving sign-in alone is not proof of a working connection. The check confirms access to your AgentPort account, not which coding tool you use. Connect multiple tools or switch at any time; no preferred tool is saved. If the check fails, inspect the client's MCP status, confirm the AgentPort account, and retry authentication. **Connected apps** in the installation panel can revoke OAuth access. No sample app or deployment is required.

Building custom source code still requires a local coding agent and Docker. Browser-only builders must export their code first. A ready-made image can be deployed without a local build. The MCP cannot read local files or build your code. OAuth tokens may be inaccessible to the agent's shell: reuse an existing registry login, or have the user authenticate Docker locally with an existing AgentPort key. Do not extract protected client tokens or ask for credentials in chat. See [Docker setup for each OS](https://agentport.cloud/resources/connect-your-coding-agent).

## API-key fallback

Use the following sections only if browser sign-in is not suitable. Do not combine static Authorization headers and OAuth for the same server.

## Before you start

- Use the remote **Streamable HTTP** endpoint `https://mcp.agentport.cloud`.
- Create a key in **Dashboard → API keys** after completing beta entry. This is an AgentPort key, not an OpenAI, Anthropic, or Google key.
- Replace `YOUR_AGENTPORT_API_KEY` locally. Never paste a real key into a chat, screenshot, repository, or shared log.
- These examples save the key in plaintext in private user-level configuration. Keep that file out of Git and restrict access to your OS account. Commands containing a real key can also be saved in shell history.

## Where settings are saved

`~` means your home directory. On Windows, paste the `%USERPROFILE%` path into File Explorer. For a client running inside WSL, use its Linux home, not the Windows file.

| Agent                   | macOS / Linux                         | Windows                                           |
| ----------------------- | ------------------------------------- | ------------------------------------------------- |
| Codex                   | `~/.codex/config.toml`                | `%USERPROFILE%\.codex\config.toml`                |
| Claude Code, user scope | `~/.claude.json`                      | `%USERPROFILE%\.claude.json`                      |
| Cursor                  | `~/.cursor/mcp.json`                  | `%USERPROFILE%\.cursor\mcp.json`                  |
| Windsurf Cascade        | `~/.codeium/windsurf/mcp_config.json` | `%USERPROFILE%\.codeium\windsurf\mcp_config.json` |
| Gemini CLI, user scope  | `~/.gemini/settings.json`             | `%USERPROFILE%\.gemini\settings.json`             |
| OpenCode                | `~/.config/opencode/opencode.json`    | `%USERPROFILE%\.config\opencode\opencode.json`    |

Custom config directories override these defaults. If a file is missing, create its parent directory and file. For existing JSON, merge the indicated server into the existing object, not a second top-level object.

## Codex: persistent CLI and IDE setup

Register the server once, unless `agentport_cloud` already exists:

```sh
codex mcp add agentport_cloud --url https://mcp.agentport.cloud
```

Then open the user-level `config.toml` from the table. If `CODEX_HOME` is customized, use `config.toml` in that directory. Update or add this single entry and replace the key placeholder locally:

```toml
[mcp_servers.agentport_cloud]
url = "https://mcp.agentport.cloud"
http_headers = { Authorization = "Bearer YOUR_AGENTPORT_API_KEY" }
```

If you followed the old guide, remove this server's `bearer_token_env_var` setting and any old environment-backed Authorization header. Keep unrelated settings. A saved static header does not depend on `export`, shell startup files, or whether the IDE was launched from a terminal.

On macOS/Linux, protect the saved file:

```sh
chmod 600 ~/.codex/config.toml
```

Use your actual path if customized. On Windows, keep the file in your private user profile and review its Security permissions rather than using `chmod`.

Restart Codex or the IDE extension. Run `codex mcp list`, then `/mcp` inside Codex to check connectivity. Registration alone is not proof of a working authenticated connection.

[Official Codex MCP documentation](https://developers.openai.com/codex/mcp)

## Claude Code: persistent CLI command

Run this with your key substituted locally. The explicit user scope saves the server and header for all projects:

```sh
claude mcp add --transport http --scope user agentport-cloud https://mcp.agentport.cloud --header "Authorization: Bearer YOUR_AGENTPORT_API_KEY"
```

No export is needed. The command updates `~/.claude.json`. If the entry already exists, update only that entry in the saved file instead of overwriting other settings. Start a new Claude Code session and check `/mcp` or run `claude mcp list`.

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

## Cursor: user config file

Edit `~/.cursor/mcp.json` (Windows path above), not a repository's `.cursor/mcp.json`. Merge this server into `mcpServers` and replace the key locally:

```json
{
  "mcpServers": {
    "agentport-cloud": {
      "url": "https://mcp.agentport.cloud",
      "headers": {
        "Authorization": "Bearer YOUR_AGENTPORT_API_KEY"
      }
    }
  }
}
```

Reload Cursor and check its MCP settings. The Cursor CLI shares the file; `agent mcp list` checks configured servers. Its documented MCP commands manage existing entries rather than providing an equivalent `mcp add` command.

[Official Cursor MCP documentation](https://cursor.com/docs/mcp) · [Cursor CLI commands](https://cursor.com/docs/cli/mcp)

## Windsurf Cascade: config file

Open Cascade's MCP settings and choose **View Raw Config** or **Open MCP config file**. Older Windsurf installations use the Windsurf path in the table. The current official docs describe these newer **Devin Desktop Cascade** paths instead:

- macOS/Linux: `~/.config/devin/mcp_config.json`, or `$XDG_CONFIG_HOME/devin/mcp_config.json` when customized.
- Windows: `%APPDATA%\devin\mcp_config.json`.

Use the file opened by your installed app. These instructions apply to Cascade, not the separate Devin Local agent. Merge this entry and replace the key locally:

```json
{
  "mcpServers": {
    "agentport-cloud": {
      "serverUrl": "https://mcp.agentport.cloud",
      "headers": {
        "Authorization": "Bearer YOUR_AGENTPORT_API_KEY"
      }
    }
  }
}
```

Save, refresh the MCP list or restart the app, and check that `agentport-cloud` is enabled and connected.

[Official Cascade MCP documentation](https://docs.windsurf.com/windsurf/cascade/mcp)

## Gemini CLI: persistent CLI command

Run once with your key substituted locally:

```sh
gemini mcp add --transport http --scope user agentport-cloud https://mcp.agentport.cloud --header "Authorization: Bearer YOUR_AGENTPORT_API_KEY"
```

This saves the HTTP endpoint and header in the user-level `~/.gemini/settings.json`; no export is needed. Keep tool approvals enabled. Restart Gemini CLI and check `/mcp list`, or run `gemini mcp list` from a terminal.

[Official Gemini CLI MCP documentation](https://geminicli.com/docs/tools/mcp-server/)

## OpenCode: add wizard and persistent API-key config

OpenCode offers an interactive add wizard:

```sh
opencode mcp add
```

Choose a remote server, name it `agentport-cloud`, and use `https://mcp.agentport.cloud`. Keep the configuration user-level. You can skip the wizard and use the complete config below; do not leave a project entry overriding your user entry.

Open `~/.config/opencode/opencode.json` (Windows path above), or your existing `opencode.jsonc` or custom config location. Merge the following under `mcp`, not `mcpServers`, and replace the key locally. Disabling OAuth selects API-key authentication:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "agentport-cloud": {
      "type": "remote",
      "url": "https://mcp.agentport.cloud",
      "enabled": true,
      "oauth": false,
      "headers": {
        "Authorization": "Bearer YOUR_AGENTPORT_API_KEY"
      }
    }
  }
}
```

Restart OpenCode and run `opencode mcp list`.

[Official OpenCode MCP documentation](https://opencode.ai/docs/mcp-servers/) · [Config locations](https://opencode.ai/docs/config/) · [CLI add wizard](https://opencode.ai/docs/cli/#add)

## Verify without deploying

After restarting your agent, check its MCP connection and ask it to call AgentPort's `billing:status`. A successful authenticated response confirms the key works. Do not create an image target or deploy during this check.

For `401` or `403`, check the locally saved key, beta access, and duplicate project-level entries. Do not paste the key into a support ticket. Docker is needed later for local image builds and pushes, not just to connect to this remote MCP server.