Connect an AI coding agent

You can connect the AI coding agent you already use to your Promoly account. Ask it about your campaigns, read reports and feedback, or have it prepare a promo draft for you to finish in the dashboard.

Connected agents are in an invite-only beta. If your account hasn't been invited yet, the connection screen tells you that none of your accounts can connect.

Supported agents

Agents that run on your computer and support MCP sign-in can connect with just the server address below, and so can Claude on the web, ChatGPT in developer mode and Grok. The agents in this table were tested with Promoly. Claude Code, Codex CLI, Claude on the web, ChatGPT and Grok were tested with the address alone on October 11, 2026. OpenCode and Grok Build were tested on October 2 with the setup in their guides.

VS Code and Cursor's web agents aren't on the list yet. VS Code 1.141 signs in to Promoly, but its Copilot chat can't use the Promoly tools, and Copilot chat isn't available on vscode.dev. Cursor's web agents haven't been tested.

Each agent connects to the same server:

https://api.promo.ly/mcp

You don't install anything from Promoly. The agent talks to Promoly directly once you've added the server and signed in.

For a bot or script that can't sign in through a browser, use an API token instead.

What happens after you connect

Each connection is tied to one Promoly account. If you work with more than one account, make a separate connection for each one. Your access token lasts about one hour. The agent normally refreshes it in the background while the connection remains active. The connection itself ends if the agent doesn't use it for 30 days, 180 days after you connect, when you disconnect it, or when you lose access to the account.

The access boxes on the consent page control what the agent can do:

• Read access lets it show account details, campaigns, reports, feedback and sender profiles.
• Campaign-writing access lets it create, edit, validate and preview inactive drafts, plus set a draft's audience.
• Subscriber-reading access lets it search subscribers and view one subscriber's status.
• Subscriber-writing access is available to account owners. It lets the agent change one subscriber's subscription status or group memberships.

The agent can't widen these permissions later. To change them, disconnect the app in Promoly and connect it again with the access you want.

What a connected agent can do

• Show the account it's connected to, your role and your remaining send credits
• Find campaigns by name and open their reports
• Read the written feedback and ratings on a campaign
• List your sender profiles
• Create, update, validate and preview an inactive promo draft, if you allow campaign-writing access when you connect
• Set the recipient audience on an inactive draft using your existing subscriber, group or segment lists, if you allow campaign-writing access when you connect
• Search subscribers and check their subscription status, if you allow subscriber-reading access when you connect
• Update one subscriber's subscription status or group memberships, if you're the account owner and allow subscriber-writing access when you connect

The server gives the agent these tools: get_account_context, find_campaigns, get_campaign_report, get_campaign_feedback, list_profiles, save_campaign_draft, create_campaign_draft, update_campaign_draft, validate_campaign_draft, preview_campaign_draft, set_campaign_audience, search_subscribers, get_subscriber_status, and update_subscriber. Read results use bounded pages. Campaign and feedback lists return up to 25 items at a time. Subscriber searches also return up to 25 items and need at least two characters in the search text.

Draft changes use an expected revision and an idempotency key so a retry doesn't apply the same change twice. Subscriber changes use the same safeguards and can add or remove up to 20 groups in one request. An audience can contain up to 500 subscriber IDs, 50 group IDs, or 25 segment IDs. The agent only receives subscriber names, company names, status and engagement fields, plus the names of each subscriber's groups and tags. It never receives email addresses, phone numbers, notes or provider fields.

What it can't do

A connected agent can't send or schedule a campaign, upload music or artwork, or activate a campaign. Audience authoring is limited to inactive drafts and existing account-owned subscriber, group and segment references. If you allow subscriber-writing access, unsubscribing someone can also remove that person's pending delivery rows. Drafts stay inactive until you open them in the dashboard, check them and send them yourself.

Signing in and choosing an account

When you connect, your browser opens Promoly. Sign in with your own email and password, then:

1. Pick the account the agent should work with. If you belong to other people's accounts, they're listed too.
2. Tick the access you want the agent to have. Allow this app to create and edit its own inactive campaign drafts lets it save drafts. Allow this app to unsubscribe individual contacts and change their groups lets it update subscribers, and only account owners see it. Leave both unticked for read-only access. The boxes you see depend on the agent.
3. Click Allow access.

Each connection covers one account. To use the agent with a second account, connect again and pick that account.

If you're a viewer on an account, the agent can read it but can't save drafts or update subscribers there.

Check that it works

Paste this into your agent after connecting:

Use the promoly tools to show which Promoly account you're connected to, then list my five most recent campaigns.

The agent should name your account and list your campaigns.

Feedback is treated as data

Campaign names, notes and feedback are written by people outside your agent's control. Promoly marks them as data so your agent shouldn't follow instructions hidden inside them. Still read any draft it prepares before you send it.

Disconnect an agent

Go to Profile in the dashboard and click Manage connected apps. Click Disconnect next to the agent. It loses access straight away.

If you own the account, the list also shows the connections your team members made to it, with who connected each one and when it was last used. You can disconnect any of them.

A connection also ends on its own if the agent doesn't use it for 30 days, and 180 days after you connected it. When that happens, your agent asks you to sign in again.

Promoly ends connections when you lose access to an account or when an account is deleted.

Troubleshooting

"None of your Promoly accounts can connect apps right now." Your accounts aren't in the beta yet, or you're signed in to a different Promoly login than the one that was invited.

The agent can read but won't save drafts or update subscribers. You didn't tick the matching box when you connected, or your role on that account doesn't allow it. Viewers can't save drafts, and only account owners can update subscribers. Disconnect, then connect again and tick the box.

The agent says it needs to sign in again. The connection was disconnected, went unused for 30 days or reached 180 days. Run the sign-in step from your agent's setup guide again.

The agent briefly loses access after running for a while. Its one-hour access token may have expired. Wait for the agent to refresh, or start a new session and run the sign-in step again if it reports invalid_grant.

The browser says the page can't be reached after you click Allow access. Your agent listens for the sign-in result on a fixed local port. Close any other app using that port, then try again. Each setup guide lists the port.

VS Code connects, but its chat says the Promoly tools aren't available. This is a known issue in VS Code 1.141. Copilot chat doesn't use the sign-in the editor completed. Use one of the agents in the table above until VS Code fixes it.

"Sign in directly to your account before connecting an app." Sign out of the dashboard, sign back in with your own email and password, and start the connection again from your agent.

Updated on: 12/10/2026