---
title: Step 3 · Connect the MCP
status: current
phase: 5
order: 5
---

# Step 3 · Connect the MCP

With the MCP connected, your agent manages content with tools: "publish the Open House", "show me the drafts", "upload this photo". No `curl` and no copying responses.

Every client uses the same address:

```text
https://pluma.so/mcp
```

It's a **remote MCP server over Streamable HTTP**. Always include the `/mcp` path.

## Two ways to sign in

| Way | When | What you do |
| --- | --- | --- |
| **Sign in with Pluma** (OAuth) | Chat apps and anything on your computer with a browser | Paste the URL. A Pluma screen opens: you pick the site and approve. |
| **Agent token** (`pluma_agt_…`) | Servers, CI, containers, anything with no browser | Create an agent in **Agents** ([step 2](invite-your-agent.md)) and send its token in the `Authorization` header. |

With **Sign in with Pluma**, the approval screen always works the same:

1. You sign in to Pluma (if you weren't signed in).
2. You see which client is asking for access and **choose the site**.
3. **You approve.** You go back to your app, connected.

Anyone on the site can approve. The agent can do the same as the person who approved, based on their role: if you're an editor, it creates and publishes content but doesn't touch the model. If your access is limited to some types or entries, so is the agent's. See [What the agent can do](../mcp/tools.md#what-the-agent-can-do).

Each client below has its own section. Pick yours.

## ChatGPT

This is how your clients edit their site by asking ChatGPT. It uses ChatGPT's **developer mode**, available on the web for Plus, Pro, Business, Enterprise and Education.

1. In ChatGPT, open **Settings → Security and login** and turn on **Developer mode**.
2. Go to **Plugins** (chatgpt.com/plugins) and press **+**.
3. Give it a name ("Pluma") and a short description ("Content for our website").
4. Choose **Public endpoint** and paste `https://pluma.so/mcp`.
5. For authentication, choose **OAuth**. ChatGPT registers itself with Pluma; you don't need a client ID.
6. Approve on the Pluma screen. The connector shows up under **Drafts**, ready to use in a chat.

Then ask: "Using Pluma, what pages does my site have?".

- **Business and Enterprise:** a workspace admin has to allow developer mode first (**Workspace settings → Permissions & roles**). Only admins and owners can publish the connector for the whole workspace.
- **Confirmations:** ChatGPT asks you to confirm every tool that changes something (create, publish, delete). That's expected. Reading doesn't ask.
- **No token field:** ChatGPT has no place to paste a header, so use **Sign in with Pluma**, not an agent token.

## Claude (claude.ai, desktop and mobile)

The connection runs from Anthropic's servers, so the same connector works on the web, in the desktop app and on your phone.

**Free, Pro and Max:**

1. Open **Settings → Connectors** and press **Add custom connector**.
2. Name it "Pluma" and paste `https://pluma.so/mcp`.
3. Press **Add**, then **Connect**, and approve on the Pluma screen.

**Team and Enterprise:**

1. An owner opens **Organization settings → Connectors → Add → Custom → Web** and pastes the URL.
2. Each person then goes to **Settings → Connectors**, finds Pluma and presses **Connect**.

Before using it in a chat, turn it on from the **+** menu (Connectors) in the message box.

- **Free plan:** one custom connector.
- **Leave the OAuth fields empty.** Claude registers itself with Pluma.
- **To change how it signs in,** remove the connector and add it again. Claude doesn't let you edit that later.

## Claude Code

```bash
claude mcp add --transport http --scope user pluma https://pluma.so/mcp
```

Then, inside Claude Code, run `/mcp`, choose **pluma** and **Authenticate**. Your browser opens on the Pluma screen.

`--scope user` makes it available in every project. Use `--scope project` to save it in the repo's `.mcp.json` and share it with your team.

**With a token (no browser):**

```bash
claude mcp add --transport http --scope user pluma https://pluma.so/mcp \
  --header "Authorization: Bearer $PLUMA_TOKEN"
```

**Shared in the repo** (`.mcp.json`, each person sets `PLUMA_TOKEN` on their machine):

```json
{
  "mcpServers": {
    "pluma": {
      "type": "http",
      "url": "https://pluma.so/mcp",
      "headers": { "Authorization": "Bearer ${PLUMA_TOKEN}" }
    }
  }
}
```

## Cursor

Add Pluma to `~/.cursor/mcp.json` (every project) or `.cursor/mcp.json` (this project):

```json
{
  "mcpServers": {
    "pluma": { "url": "https://pluma.so/mcp" }
  }
}
```

Open **Settings → MCP**. Pluma shows **Needs login**: press it and approve on the Pluma screen.

**With a token:**

```json
{
  "mcpServers": {
    "pluma": {
      "url": "https://pluma.so/mcp",
      "headers": { "Authorization": "Bearer ${env:PLUMA_TOKEN}" }
    }
  }
}
```

Cursor writes environment variables as `${env:NAME}`, not `${NAME}`.

## VS Code (GitHub Copilot)

Run **MCP: Add Server** from the command palette, choose **HTTP** and paste the URL. Or write `.vscode/mcp.json` yourself:

```json
{
  "servers": {
    "pluma": { "type": "http", "url": "https://pluma.so/mcp" }
  }
}
```

The first time Copilot uses it, VS Code asks you to sign in and opens the Pluma screen. Use it from Copilot Chat in **Agent** mode.

**With a token,** VS Code asks for it once and stores it safely:

```json
{
  "inputs": [
    { "type": "promptString", "id": "pluma-token", "description": "Pluma agent token", "password": true }
  ],
  "servers": {
    "pluma": {
      "type": "http",
      "url": "https://pluma.so/mcp",
      "headers": { "Authorization": "Bearer ${input:pluma-token}" }
    }
  }
}
```

- **Copilot Business and Enterprise:** the **MCP servers in Copilot** policy is off by default. An admin has to turn it on.

## Windsurf

Open **Settings → Cascade → MCP servers → View raw config** and add Pluma to `mcp_config.json`:

```json
{
  "mcpServers": {
    "pluma": {
      "serverUrl": "https://pluma.so/mcp",
      "headers": { "Authorization": "Bearer ${env:PLUMA_TOKEN}" }
    }
  }
}
```

Windsurf uses **`serverUrl`**, not `url`. Leave out `headers` to sign in with Pluma instead. On Team and Enterprise, an admin may have to add Pluma to the allowed servers.

## Gemini CLI

```bash
gemini mcp add --transport http --scope user pluma https://pluma.so/mcp
```

Then, inside Gemini CLI, run `/mcp auth pluma` and approve on the Pluma screen.

Or edit `~/.gemini/settings.json` yourself:

```json
{
  "mcpServers": {
    "pluma": {
      "httpUrl": "https://pluma.so/mcp",
      "headers": { "Authorization": "Bearer pluma_agt_…" }
    }
  }
}
```

Gemini CLI uses **`httpUrl`** for this kind of server. `url` means an older transport and won't work. Leave out `headers` to sign in with Pluma. Signing in needs a browser on the same machine, so over SSH or in a container use the token.

## Codex (CLI, IDE extension and ChatGPT desktop app)

All three read `~/.codex/config.toml`:

```toml
[mcp_servers.pluma]
url = "https://pluma.so/mcp"
```

Then sign in:

```bash
codex mcp login pluma
```

**With a token,** name the environment variable that holds it:

```toml
[mcp_servers.pluma]
url = "https://pluma.so/mcp"
bearer_token_env_var = "PLUMA_TOKEN"
```

## Zed

In Zed's `settings.json`:

```json
{
  "context_servers": {
    "pluma": { "url": "https://pluma.so/mcp" }
  }
}
```

Zed opens the Pluma screen the first time. To use a token instead, add `"headers": { "Authorization": "Bearer pluma_agt_…" }`.

## Any other client

If your client supports remote MCP servers, it works with Pluma:

- **URL:** `https://pluma.so/mcp`, transport **Streamable HTTP** (sometimes called "HTTP").
- **Sign in with Pluma:** choose OAuth and leave client ID and secret empty. Pluma supports dynamic registration, so the client registers itself. The technical details are in [MCP OAuth](../mcp/oauth.md).
- **Token:** send the header `Authorization: Bearer pluma_agt_…`. The word `Bearer` goes in the value.

If the client only runs local (stdio) servers, bridge it with `mcp-remote`:

```json
{
  "mcpServers": {
    "pluma": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://pluma.so/mcp", "--header", "Authorization:Bearer ${PLUMA_TOKEN}"],
      "env": { "PLUMA_TOKEN": "pluma_agt_…" }
    }
  }
}
```

## Check that it works

Ask your agent: "Using Pluma, describe my site". It should answer with your content types.

To see exactly what it can do, ask: "Using Pluma, what can you do on my site?". The list of tools depends on the role of whoever connected it: a viewer's agent sees only reading tools.

## Troubleshooting

| What you see | Why | What to do |
| --- | --- | --- |
| The client says it can't connect | The URL is missing `/mcp`, or the transport is SSE | Use `https://pluma.so/mcp` with Streamable HTTP. |
| "The return address isn't the one the client registered" | The client changed its callback after registering | Remove the server from the client and add it again. |
| "This server only authorizes …/mcp" | The client asked for access to a different server | Check the URL you pasted. |
| `401` with "The key is missing" | No token was sent | Sign in again, or check the `Authorization` header. |
| `401` with "The key doesn't exist or was revoked" | Someone revoked the agent in **Agents**, or the token is incomplete | Connect again, or create a new agent. |
| The agent can't publish or change the model | The person who approved doesn't have that role, or has limited access | Ask an owner to connect it, or to change your role in **Settings → Team**. |
| You don't see your site on the approval screen | You're not a member of that site | Ask an owner to invite you. |

## Revoke

Each connected client shows up in **Agents** with its name (for example "Claude Code" or "ChatGPT"). Revoking it cuts access right away. Connecting again creates a new agent.

## What you see in the dashboard

Step 3 checks itself off when the **first authenticated MCP call** from your site arrives. In the activity, what your agent does over MCP shows up with its name and the "agent" tag, same as over the API.

The available tools and what each one does are in [MCP tools](../mcp/tools.md).