# Connect your agent

**Hand this page to your agent:** The quickest way to connect. Paste this into Claude Code, Codex or Cursor. Your agent reads this page and runs the setup, and you only sign in.

```text wrap
Read https://docs.promptlycms.com/mcp/connect.md, then connect yourself to the Promptly MCP server by following the steps for your app. Run the commands yourself and tell me when I need to sign in.
```

You can also select **Copy Markdown** above and paste the whole page into your chat. Every page on this site has a Markdown version: add `.md` to its address. [llms.txt](https://docs.promptlycms.com/llms.txt) lists them all.

Every agent connects to the same server URL and signs in with your Promptly account. You don't need an API key.

```
https://app.promptlycms.com/mcp
```

When you sign in, Promptly asks what the agent may do: **Read only**, **Create and edit drafts** (the default) or **Create, edit, and publish**. **Run tests** is a separate option and is off by default. The commands below request every permission, and you narrow them on that screen. See [permissions](https://docs.promptlycms.com/mcp/overview/#permissions).

**Tip:** Already signed in? [Settings → MCP connections](https://app.promptlycms.com/settings?tab=mcp) shows the same setup steps and lists every agent connected to your workspace.

## Choose your agent

**Claude Code**

1. Add the server:

   ```bash wrap
   claude mcp add-json promptly '{"type":"http","url":"https://app.promptlycms.com/mcp","oauth":{"scopes":"mcp:read mcp:write mcp:publish mcp:run"}}'
   ```

2. Open `/mcp` in Claude Code, select **promptly** and sign in to Promptly in your browser.

3. Select **Reconnect** in `/mcp` to load the tools.

If you added Promptly before, run `claude mcp remove promptly` first.

**Claude apps (web and desktop)**

1. Open **Customize → Connectors** and add a custom connector.

2. Enter `https://app.promptlycms.com/mcp` as the server URL.

3. Select **Connect** and sign in to Promptly.

On Team and Enterprise plans, a workspace owner adds the connector for the organization first. See [Anthropic's custom connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

**Codex**

1. Add the server and sign in:

   ```bash wrap
   codex mcp add promptly --url https://app.promptlycms.com/mcp
   codex mcp login promptly --scopes mcp:read,mcp:write,mcp:publish,mcp:run
   ```

2. Finish signing in to Promptly in your browser.

If Promptly is already configured, run `codex mcp logout promptly` and repeat only the login command. See [OpenAI's Codex MCP guide](https://developers.openai.com/codex/mcp).

**ChatGPT**

1. Turn on developer mode, then open **Plugins → Create app**.

2. Enter `https://app.promptlycms.com/mcp` as the server URL and select **OAuth**.

3. Under **Advanced OAuth settings**, keep the detected default (CIMD).

4. Create the app and sign in to Promptly.

If the actions list is empty, select **Refresh actions**. On Business and Enterprise plans, an administrator may need to enable workspace access. See [OpenAI's developer mode guide](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt-beta).

**Cursor**

Cursor needs a client ID, so register it with Promptly first.

1. Open [Register a client](https://app.promptlycms.com/settings/mcp/clients) in Promptly. Name it **Cursor** and enter these callback URLs, one per line:

   ```
   cursor://anysphere.cursor-mcp/oauth/callback
   http://localhost:8787/callback
   https://www.cursor.com/agents/mcp/oauth/callback
   ```

   For **Does your client require a secret?**, choose **No - public client**.

2. Add Promptly to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` for every project. Replace `YOUR_PROMPTLY_CLIENT_ID` with the client ID from step 1:

   ```json title=".cursor/mcp.json"
   {
     "mcpServers": {
       "promptly": {
         "url": "https://app.promptlycms.com/mcp",
         "auth": {
           "CLIENT_ID": "YOUR_PROMPTLY_CLIENT_ID",
           "scopes": ["mcp:read", "mcp:write", "mcp:publish", "mcp:run"]
         }
       }
     }
   }
   ```

3. Enable **promptly** in Cursor's MCP settings and sign in to Promptly.

Use `mcp.json` rather than Cursor's `--add-mcp` command, which writes an entry Cursor's settings don't pick up. See [Cursor's MCP guide](https://cursor.com/docs/mcp).

## Let your agent set it up

Want more control than the one-line prompt at the top? Paste the prompt for your agent instead. It spells out each step, and your agent tells you when to sign in to Promptly.

```text wrap title="Prompt for Claude Code"
Connect this Claude Code session to the Promptly MCP server.

1. Run this command. If a server named promptly already exists, run `claude mcp remove promptly` first.
   claude mcp add-json promptly '{"type":"http","url":"https://app.promptlycms.com/mcp","oauth":{"scopes":"mcp:read mcp:write mcp:publish mcp:run"}}'
2. Tell me to open /mcp, select promptly and sign in to Promptly in my browser. If promptly isn't listed, tell me to restart Claude Code with `claude --continue` first.
3. Once I've signed in, call Promptly's get_connection tool and tell me which workspace you're connected to and what you're allowed to do.

If anything fails, read https://docs.promptlycms.com/mcp/connect.md and help me fix it.
```

The Claude apps can't add connectors themselves, so follow the steps above for those.

```text wrap title="Prompt for Codex"
Connect Codex to the Promptly MCP server.

1. Run these commands. They write to ~/.codex, so ask me for approval if your sandbox blocks them. If promptly is already configured, skip the first command and run `codex mcp logout promptly` before logging in.
   codex mcp add promptly --url https://app.promptlycms.com/mcp
   codex mcp login promptly --scopes mcp:read,mcp:write,mcp:publish,mcp:run
2. The login command opens my browser. Wait for me to finish signing in to Promptly.
3. Tell me to start a new Codex session so the Promptly tools load, and to ask it to call Promptly's get_connection tool.

If anything fails, read https://docs.promptlycms.com/mcp/connect.md and help me fix it.
```

ChatGPT can't add apps itself, so follow the steps above for ChatGPT.

```text wrap title="Prompt for Cursor"
Connect Cursor to the Promptly MCP server.

1. Ask me for my Promptly client ID. If I don't have one, tell me to open https://app.promptlycms.com/settings/mcp/clients, name the client Cursor, enter these callback URLs one per line and choose "No - public client":
   cursor://anysphere.cursor-mcp/oauth/callback
   http://localhost:8787/callback
   https://www.cursor.com/agents/mcp/oauth/callback
2. Add this server to .cursor/mcp.json in this project under "mcpServers", keeping any servers already there. Use my client ID in place of YOUR_PROMPTLY_CLIENT_ID:
   "promptly": {
     "url": "https://app.promptlycms.com/mcp",
     "auth": {
       "CLIENT_ID": "YOUR_PROMPTLY_CLIENT_ID",
       "scopes": ["mcp:read", "mcp:write", "mcp:publish", "mcp:run"]
     }
   }
3. Tell me to enable promptly in Cursor's MCP settings and sign in to Promptly.
4. Once I've signed in, call Promptly's get_connection tool and tell me which workspace you're connected to and what you're allowed to do. If the tool isn't available yet, tell me to start a new chat.

If anything fails, read https://docs.promptlycms.com/mcp/connect.md and help me fix it.
```

## Other agents

Any agent that supports remote MCP servers over HTTP with OAuth can connect.

- If it signs in with just the server URL, enter `https://app.promptlycms.com/mcp`.
- If it asks for a client ID, [register a client](https://app.promptlycms.com/settings/mcp/clients) with the callback URLs your agent lists, then enter the client ID it returns.

## Troubleshooting

**Tools don't appear after signing in.** Reconnect the server: **Reconnect** in Claude Code's `/mcp`, **Refresh actions** in ChatGPT, or toggle the server off and on in Cursor.

**The agent says it can't publish or run tests.** The connection was granted a narrower permission. Revoke it in [Settings → MCP connections](https://app.promptlycms.com/settings?tab=mcp), then connect again and choose the permission you need. Existing connections never gain permissions on their own.

**Requests fail with `429 Too Many Requests`.** Each connection can make 120 requests a minute and each workspace 600. Wait for the time in the `Retry-After` header.

**Removing access.** Revoke any connection in [Settings → MCP connections](https://app.promptlycms.com/settings?tab=mcp). Members manage their own connections, and owners and admins can revoke anyone's.