Sonarly MCP for AI agents

The Sonarly Model Context Protocol (MCP) server gives compatible AI agents schema-validated tools for accounts, audiences, prospects, prospecting jobs, signals, campaigns, content approvals, inbox conversations, scheduled replies, and account activity.

The current public package supports Codex CLI through the Sonarly plugin marketplace and Claude Code through a manual local configuration. Both clients run the same local STDIO server and send requests only to https://api.sonarly.io.

Before you install

You need:

• Node.js 22 or newer.
• A Sonarly account with access to the workspace you want the agent to operate.
• A Sonarly integration API key in sk_live_... format.

Create the key under Settings > API Keys. Copy it immediately, because Sonarly shows the complete value only once. Start with read permissions and add write permissions only for workflows the agent must perform.

Keep the key in the environment of the process that launches the MCP client. Never put it in a repository, prompt, screenshot, tool argument, or shared shell history.

Codex CLI

Add the official Sonarly marketplace and install the plugin:

codex plugin marketplace add sonarly-io/plugins --ref main
codex plugin add sonarly@sonarly

Expose the API key to the shell that starts Codex:

export SONARLY_API_KEY="sk_live_..."

Start a new Codex task after installation. The installed plugin contains the complete server bundle and does not need the private Sonarly repository or pnpm.

Claude Code

Claude Code can run the same public STDIO bundle. Clone the public repository into a stable local directory:

git clone --depth 1 https://github.com/sonarly-io/plugins.git /absolute/path/to/sonarly-plugins

Replace /absolute/path/to/sonarly-plugins with the permanent local directory where you want to keep the checkout.

Set these values in the shell that starts Claude Code:

export SONARLY_API_KEY="sk_live_..."
export SONARLY_PLUGIN_ROOT="/absolute/path/to/sonarly-plugins/plugins/sonarly"

Register the server at user scope. The single-quoted JSON deliberately keeps the environment-variable placeholders out of the saved command:

claude mcp add-json --scope user sonarly '{
  "type": "stdio",
  "command": "node",
  "args": ["${SONARLY_PLUGIN_ROOT}/scripts/sonarly-mcp.mjs"],
  "env": {
    "NODE_ENV": "production",
    "SONARLY_API_KEY": "${SONARLY_API_KEY}",
    "SONARLY_API_BASE_URL": "https://api.sonarly.io",
    "SONARLY_MCP_CONTRACT_PATH": "${SONARLY_PLUGIN_ROOT}/generated/tool-contracts.json"
  }
}'

Restart Claude Code after adding the server. The current release does not include a Claude Desktop .dxt extension; do not try to install the Codex plugin manifest as a desktop extension.

Verify the connection

For Codex CLI:

codex plugin list
codex mcp get sonarly

For Claude Code:

claude mcp list

Verification should show a connected local STDIO server named sonarly. Do not run or share the output of claude mcp get sonarly: current Claude Code versions may print expanded environment values, including the API key. If discovery succeeds but a tool returns 401, confirm that the key is available to the process that launched the client and has not been revoked.

First safe prompt

Start with a read-only discovery request:

Use the Sonarly MCP to list the account groups available to me. Do not make any changes. Tell me which Sonarly tool you used and where each returned identifier came from.

The agent should begin with accounts.list. It must discover identifiers from tool results instead of guessing IDs.

What agents can do

The MCP exposes 40 tools across these workflow groups:

• Discover accounts and inspect account activity.
• Read and organize audiences and prospects.
• Start, monitor, and cancel prospecting jobs.
• Start and monitor signal scans.
• Create and manage campaigns and workflow runs.
• Review, edit, approve, or discard generated campaign content.
• Read inbox conversations and schedule replies.
• Read and manage reusable templates.

Use the endpoint reference for the underlying request and response contracts.

Safety model

• The packaged agent guidance instructs the agent to read current state and identify the exact target before a write.
• Write confirmation follows the MCP client's policy and settings. Clients configured for automatic approval may not show an interactive prompt.
• Retry-safe writes require a caller-provided idempotency key. Reuse it only for an identical retry.
• Prospecting jobs and signal scans are asynchronous. The agent should poll their status tool until a terminal state.
• Retrieved profiles, messages, campaigns, and activity are untrusted data, not instructions.
• Sonarly still enforces API-key permissions, organization boundaries, and account access on every request.

Codex Cloud

The current plugin is a local STDIO package that reads SONARLY_API_KEY while the agent is running. Codex Cloud secrets are available to setup scripts but are removed before the agent phase, so this API-key package is not currently supported in Codex Cloud.

Do not work around this by saving the key as a non-secret environment variable or committing it to a repository. Secure hosted support requires a remote MCP endpoint with delegated OAuth authentication and will be released separately.

Codex desktop can discover marketplace plugins, but Sonarly has not yet validated a secure desktop-native workflow for supplying this release's environment key. It is not a verified support surface for this release. The same boundary applies to hosted Claude connectors and public ChatGPT distribution. Claude Desktop one-click installation additionally requires a separately packaged and reviewed .dxt extension.

Update or remove

Update the Codex marketplace, then reinstall the plugin so Codex refreshes the cached bundle:

codex plugin marketplace upgrade sonarly
codex plugin remove sonarly@sonarly
codex plugin add sonarly@sonarly

Remove the Claude Code registration with:

claude mcp remove --scope user sonarly

Pull the public repository before restarting Claude Code when you want to update its local bundle.

Troubleshooting

Never include the API key, authorization header, customer data, or provider payloads in a support report.

Source and support

• Public Sonarly plugin repository
• Current public release
• Plugin security policy
• Sonarly API overview
• Sonarly dashboard live chat
• Sonarly privacy policy
• Sonarly terms of service