> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notifly.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Notifly Remote MCP server

> Connect Notifly Remote MCP to MCP clients such as Claude Code and Codex.

Notifly Remote MCP is a remote MCP endpoint that clients such as Claude Code and Codex call over the internet. You do not need to install a local server. Add the URL below to your client.

```text theme={null}
https://api.notifly.tech/mcp
```

> [!NOTE]
>
> This guide covers the hosted Remote MCP service. Add the URL to your client, then sign in with your Notifly account.

> [!NOTE]
>
> Notifly has three AI tools. The [AI Assistant](https://docs.notifly.tech/en/user-guide/analytics/ai-agent.md) runs in the console and requires Pro or above. [Remote MCP](https://docs.notifly.tech/en/devtools/notifly-remote-mcp.md) connects external AI clients such as ChatGPT and Claude. [Agent Skills](https://docs.notifly.tech/en/devtools/notifly-agent-skills.md) helps AI coding agents integrate the SDK. The AI Assistant and Remote MCP support data lookups and drafting. Campaign and user journey tools do not send messages, activate resources, or delete campaigns or user journeys. Remote MCP also includes segment and CSV write tools, including saved segment deletion. Review each tool's permissions before use. Agent Skills changes SDK integration code in your project, so review the generated code and configuration.

## How it works

Remote MCP connects your client to the Notifly API through a standard interface. The client reads the tool list and calls the tools needed for your request. Project access follows the permissions of the Notifly account you sign in with.

| Item | Description |
| - | - |
| URL | `https://api.notifly.tech/mcp` |
| Transport | Remote MCP over Streamable HTTP |
| Authentication | OAuth sign-in with a Notifly account |
| Access | Products and projects available to the signed-in account |
| Write operations | Campaign and user journey draft creation and replacement, segment changes, and CSV uploads |

When authentication is required, the client opens the Notifly sign-in page. After sign-in, the client uses the granted access to query projects, campaigns, user journeys, and user status.

## Connect Claude Code

Add a remote HTTP MCP server in Claude Code.

```bash theme={null}
claude mcp add --transport http notifly https://api.notifly.tech/mcp
claude mcp list
claude mcp get notifly
```

Before authentication, `claude mcp list` or `claude mcp get notifly` may show `Needs authentication`. In a Claude Code session, ask a question that requires Notifly tools or start MCP authentication. This opens the browser OAuth flow. Sign in with your Notifly account. Claude Code then calls `/mcp` with the issued MCP token.

```text theme={null}
Show my Notifly projects.
```

If the connection works, Claude Code first calls `list_products` or `list_projects` to find the products and projects you can access.

> [!NOTE]
>
> Some Claude Code versions also let you configure `.mcp.json` directly. Use a remote `url`, not a local `command`. A server added through `.mcp.json` may initially show `Pending approval`. Approve it in a Claude Code session before use.

```json theme={null}
{
  "mcpServers": {
    "notifly": {
      "type": "http",
      "url": "https://api.notifly.tech/mcp"
    }
  }
}
```

## Connect Codex

Add a Streamable HTTP MCP server to Codex CLI with `--url`.

```bash theme={null}
codex mcp add notifly --url https://api.notifly.tech/mcp
```

Recent Codex CLI versions may display a browser authentication URL immediately after `codex mcp add`. Sign in with your Notifly account in the browser. Codex saves the connection settings.

If `codex mcp add` finishes without authentication, or you need a new token, run this command to sign in through OAuth.

```bash theme={null}
codex mcp login notifly --scopes mcp:read,mcp:tools
```

To manage the settings file directly, add the following to `~/.codex/config.toml`.

```toml theme={null}
[mcp_servers.notifly]
url = "https://api.notifly.tech/mcp"
```

Check the settings.

```bash theme={null}
codex mcp get notifly
codex mcp list
```

For an authenticated connection, the `Auth` column in `codex mcp list` shows `OAuth`.

## Capabilities

The main Notifly MCP capabilities fall into six categories.

| Category | Example tools | Purpose |
| - | - | - |
| Product and project discovery | `list_products` and related tools | Find products and projects the signed-in account can access. |
| Project catalog | Event, property, and channel lookup tools | Check event names, user properties, and channel settings. |
| Campaigns | Campaign lookup, statistics, and draft tools | Read campaign lists, details, and performance, and create or replace campaign drafts. |
| User diagnostics | `identify_user` and related tools | Check a user's identifiers, channel status, events, campaign eligibility, and delivery history. |
| User journeys | Journey lookup and draft tools | Read journey lists, details, and performance, and create or replace inactive drafts. |
| Documentation search | Official documentation search tools | Search Notifly documentation and read the pages you need. |

> [!WARNING]
>
> `create_campaign` and `replace_campaign` only create or replace campaign drafts. `create_user_journey` and `replace_user_journey` only create or fully replace inactive user journey drafts. During journey replacement, existing nodes keep their stored `id`. New nodes use a request-local `ref`, and the server generates their IDs. These campaign and journey tools do not activate resources, send messages, or delete resources. Other Remote MCP tools can change segments, upload CSV files, and delete saved segments. Keep write tools subject to approval when required by your organization.

### Replace a user journey

When you modify an existing journey, use this order.

`describe_user_journey_payload(operation: "replace")` → `describe_user_journey_node_payload(operation: "replace", ...)` for each selected node schema → `get_user_journey` → `replace_user_journey`

`replace_user_journey` replaces the entire journey. Build the request from the latest `get_user_journey` result. Send the stored `id` for each existing node and a request-local `ref` only for new nodes. To link to an existing node, use `*_node_id`. To link to a new node, use `*_node_ref`. The server does not persist `ref` values. Only inactive drafts can be replaced. Active journeys cannot be replaced.

## Example prompts and responses

These examples illustrate response formats. They do not contain real account data.

### Find accessible projects

```text theme={null}
Show the Notifly products and projects I can access.
```

```text theme={null}
I found 1 accessible product and 2 projects.

- Product A
  - Project: commerce-prod (`project_id: ...`)
  - Project: commerce-stage (`project_id: ...`)

You can next check campaigns, the event catalog,
and channel settings.
```

### Summarize campaign performance

```text theme={null}
Summarize sends, clicks, and conversions for the 5 most recent app push campaigns.
```

```text theme={null}
I retrieved the 5 most recent campaigns
and called the statistics tool for each campaign.

- June retention notification: active, 12,340 sends, 820 clicks, 113 conversions
- Cart reminder: draft, no delivery statistics yet

I excluded draft campaigns from the performance summary because they have no delivery statistics.
```

### Diagnose a user's missing message

```text theme={null}
Check why user@example.com did not receive campaign A yesterday.
```

```text theme={null}
I checked the following.

1. Used `identify_user` to resolve the email to a canonical Notifly user ID.
2. Checked campaign eligibility with `get_campaign_user_eligibility`.
3. Checked delivery records with `list_campaign_user_deliveries`.

Conclusion: The user met the campaign targeting conditions.
They were excluded from delivery because app push notifications were disabled for them.
```

### Create a campaign draft

```text theme={null}
Create an app push campaign draft for users who signed up 3 days ago. Do not send it yet.
```

```text theme={null}
I created a campaign draft.

- Campaign ID: `...`
- Status: `draft`
- Channel: app push
- Sent: no

Open the draft in the Notifly console.
Review the message and conditions before activating it.
```

### Modify an inactive user journey

```text theme={null}
Add a delay node to an existing inactive user journey. Do not activate it or send any messages.
```

```text theme={null}
I use the following sequence.

1. Read the full replacement schema with `describe_user_journey_payload(operation: "replace")`.
2. Read the schema for each node to add or retain with `describe_user_journey_node_payload(operation: "replace", ...)`.
3. Read the latest full journey and existing node IDs with `get_user_journey`.
4. Call `replace_user_journey`, retaining each existing node's `id` and linking the new delay node with a request-local `ref`.

Only the inactive draft was fully replaced. Existing node IDs were preserved, and the server generated the new node ID.
```

## Troubleshooting

| Symptom | What to check |
| - | - |
| The sign-in window does not open | Check that your client version supports Remote MCP and OAuth sign-in. |
| Authentication errors continue | Sign in to Notifly again, or remove the Notifly connection from your client and reconnect. |
| A project is missing | Check that the signed-in Notifly account has access to the product and project. |
| The client requests approval before a write tool call | This is expected. The client may require separate approval to create or replace campaign and user journey drafts. Review other write tools' effects before approval. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.