---
title: "Journy MCP: connect your AI assistant to journy.io"
canonical: "https://help.journy.io/space/journy/4357783556/Journy+MCP%3A+connect+your+AI+assistant+to+journy.io"
format: markdown
---
> Macro (include)

# Topics

> Macro (toc)

# Overview

Your AI assistant — Claude, ChatGPT, Cursor, or any tool that supports the Model Context Protocol (MCP) — can now connect directly to journy.io and work with your customer data in plain language. Instead of clicking through the dashboard, you ask: *"Which accounts are at risk of churn this month, and why?"* — and get an answer built from your real health scores, usage data, and account history.

**MCP is an open standard** that lets AI tools securely talk to other systems. Journy's MCP server exposes your journy.io data and configuration to any MCP-compatible client, so the AI you already use becomes a working interface to journy.io.

- **No new tool to learn.** You keep using Claude, ChatGPT, or your editor of choice. journy.io becomes one more thing it knows about.
- **It reads *****and***** acts.** Beyond answering questions, your AI can tag contacts, trigger saved actions, and even build Playbooks — with you confirming every change before it happens.
- **It combines with everything else you've connected.** Because your AI assistant can also reach your CRM, email, Slack, and hundreds of other MCP-connected tools, it can pull journy.io data together with those sources in one place — enriching journy.io insights with context from elsewhere, or the other way round.
- **Your permissions travel with you.** The AI can never do more than *you* can. Reads need only membership of your business; changes need Owner or Admin rights, the right scope, and your explicit confirmation.

**Typical use cases:**

- Getting a churn-risk briefing on your account base, with the reasons behind each score
- Comparing a single user's behaviour against your healthiest users to see what's missing
- Spotting usage trends — which features are growing, which are fading, which events have stopped
- Identifying champions at an account before a renewal conversation
- Drafting a Playbook in a sentence and having the AI set up the conditions for you

> ℹ️ **Example**: connect Claude to journy.io, ask *"Which Enterprise accounts dropped from Good to Average health in the last 30 days, and what changed in their usage?"* — then follow up with *"Create a tag called Renewal watch and apply it to those accounts"* and confirm.

# What your AI can do

Once connected, your assistant sees a set of **tools** — the things it can do in journy.io. What it sees depends on your role and the scopes you approved at connection.

## Read: ask anything about your accounts and users

Available to any member of the business.

| **What you ask** | **What journy.io answers** |
| --- | --- |
| Which businesses am I in? | Your businesses and your role in each |
| Find accounts / users matching … | Search by name, segment, saved view, health bucket, minimum score, or any condition you'd build in a filter |
| How many accounts / users match …? | A count, without listing them |
| Tell me about *account X* / *user Y* | The full profile: properties, health, lifecycle stage, activity |
| Who are the champions at *account X*? | The most engaged users at that account |
| Why is *account X* at risk? | How the health, expansion, or churn score was calculated, down to the individual signals |
| What has *user Y* been doing? | Events and feature usage over a period |
| Which pages and screens are being used? | Content and screen statistics |
| When did *account X* change stage? | Lifecycle stage history |
| What segments is *user Y* in? | Segment membership and size |
| What actions could I run? | Your saved quick actions (reading only — see below to run one) |
| How is my business configured? | Your stages, health profiles, signs, segments, Playbooks, and properties |

## Act: make changes, with confirmation

Available to **Owners and Admins**, and only if you approved the matching scope when connecting. Every change is put in front of you to confirm before it's applied, and every applied change is logged.

| What you ask | What happens | Scope required |
| --- | --- | --- |
| Create or change a lifecycle stage | Adds/updates the stage and the condition that puts contacts in it | `configure:stages` |
| Change how health is scored | Updates the business-wide health conditions and profiles | `configure:health-scores` |
| Add or change a sign | Adds/updates a sign that scores are computed from | `configure:signs` |
| Create or change a Playbook | Sets up the Playbook's entry and goal conditions | `configure:playbooks` |
| Create a tag | Adds a new tag to your tag list (doesn't apply it to anyone yet) | `contacts:tags` |
| Tag everyone matching … | Applies (or removes) a tag on every contact matching a condition | `contacts:tags` |
| Run *action* for everyone matching … | Triggers one of your saved quick actions for matching contacts | `contacts:actions` |

Two things worth knowing about the "act" tools:

- **Bulk changes tell you the count first.** Before tagging or running an action, the AI reports how many contacts match. Check that number is the one you expect before confirming.
- **Running an action reaches real customers.** If the saved action sends an email or a Slack message, that's what fires — and it can't be recalled. Configuration scopes (`configure:…`) and contact scopes (`contacts:…`) are deliberately separate, so an assistant that can reconfigure a health score can't message your account base as a side effect.

> 📝 **Playbook actions are set in the app.** Your AI can create a Playbook and define its entry and goal conditions. The actions inside it (Slack, email, tasks, in-app messages) are configured in journy.io itself — open the new Playbook and add them there.

# How to connect

Journy MCP works with any client that supports remote MCP servers over HTTP. There is nothing to install on journy.io's side and no API key to create — you paste one URL, log in, and approve.

**Journy MCP endpoint:** `https://mcp.journy.io/mcp`

## Claude (claude.ai and Claude Desktop)

1. Open **Settings → Connectors → Custom connectors → Add**.
2. Paste `https://mcp.journy.io/mcp` and give it a name (e.g. *Journy*).
3. You'll be redirected to journy.io. Log in if prompted, **choose the business** this connection should act on, and review the permissions being requested.
4. Click **Connect**.

> 📝 ![connect Journy MCP.png](media://794dceca-ac83-4786-9e7b-95954781aaf7)

That's the whole flow. If you're on a personal or professional Claude account, the connector is active immediately. On an **organisation or Enterprise** account, an admin first adds the connector at the organisation level; each person then opens their own profile → **Settings → Connectors**, finds Journy, and clicks **Connect** to authorise it for themselves.

## ChatGPT

ChatGPT needs **Developer mode** switched on before custom MCP servers can be added:

- Personal account: **Settings → Security and login → Developer mode** → on
- Workspace: **Workspace Settings → Permissions & Roles → Connected Data → Developer mode / Create custom MCP connectors**

Then **Settings → Plugins → Browse plugins → +** and paste `https://mcp.journy.io/mcp`.

Requires a Pro, Plus, Business, Enterprise, or Education plan, and must be done **on the web** — the mobile apps can't add custom servers. If the **+** button is missing, developer mode is still off or your plan doesn't include it.

## Cursor, Claude Code, and other clients

| Client | How |
| --- | --- |
| **Cursor** and most editors | Add a URL entry to `mcp.json` (it's a remote HTTP server, not a local command) |
| **Claude Code** | `claude mcp add --transport http journy https://mcp.journy.io/mcp` |
| **Any client that takes JSON** | See below — the field name varies (`url`, `serverUrl`, `httpUrl`); check your client's docs |

```json
{
  "mcpServers": {
    "journy": {
      "url": "https://mcp.journy.io/mcp"
    }
  }
}
```

Use the endpoint URL **exactly as written**. Connecting by any other name (an IP, a proxy, a path on another host) will log you in successfully and then fail — it looks like an auth loop rather than a clear error.

## One connection per business

If you belong to more than one journy.io business, approving the connection **pins it to the one you picked**. To work with a second business, add a second connector entry and approve it separately.

# Permissions and control

Three things decide what a connected AI can do, and none of them can be widened by the AI itself:

1. **Your role on the business** — re-checked live on every call. Reads need membership; changes need Owner or Admin.
2. **The scopes you approved** — set when you connect, never changeable afterwards. Approve only the scopes you need.
3. **What your business exposes** — Owners and Admins can turn individual tools, saved questions, and resources on or off per business under **Settings → MCP access**. A disabled tool disappears from the AI's list and can't be called even by a client that cached the old list.

> 📝 ![MCP access.png](media://2a436f36-0d10-48b3-b9cf-340ac494d341)

The **MCP access** page also shows usage per tool over the last 30 days (calls, errors, last used), so "what's safe to turn off" is a question with data behind it. Every change made through MCP — and every change to the MCP access settings themselves — is recorded with before/after values.

# Example prompts

Copy these as a starting point and adapt them to your own segments, stages, and property names. Start every session with **"Which businesses am I in?"** if you belong to several, and **"How is my health score configured?"** before reasoning about risk — *at risk* means whatever *your* business defined.

## **Churn risk and account health**

- "Which accounts have Bad health right now? List them with their MRR."
- "Why is *Acme Corp* at risk? Walk me through the signals behind the score."
- "Which accounts dropped from Good to Average health in the last 30 days?"
- "Give me a churn-prevention plan for *Acme Corp* based on what's driving its score."

## **Usage and adoption**

- "What did *jane@acme.com* do in the last 30 days? Which events were tracked?"
- "Compare *Acme Corp*'s feature usage this month against last month. What increased, what decreased, what disappeared?"
- "Which features do our healthiest accounts use that *Acme Corp* doesn't?"
- "Which pages and screens are used most across accounts in the *Enterprise* segment?"

## **Champions and expansion**

- "Who are the champions at *Acme Corp*? Rank them by activity."
- "Which accounts are ready for an upsell? Show expansion scores above 70."
- "Who is the most active user across all accounts this week?"

## **Segments and lifecycle**

- "How many accounts are in the *Trial* stage and haven't triggered an activation event?"
- "When did *Acme Corp* move from Onboarding to Active?"
- "Which users belong to both the *Power users* and *Renewal due* segments?"

## **Configuration and action** *(Owner / Admin, with the right scopes)*

- "Create a Playbook for users with Average or Bad health. Goal: reach Good health within 30 days. Re-entry after 30 days."
- "Create a tag called *Q4 renewal watch* and apply it to every account in Bad health with a contract ending before December."
- "Run the *Book onboarding call* action for every Trial account that hasn't logged in for 14 days." *(check the count before you confirm)*
- "Add a lifecycle stage called *Expansion ready* for accounts with an expansion score above 75."

# Use cases in practice

## Compare a user to your healthiest users

The single most useful pattern: instead of reading one user's activity in isolation, ask the AI to hold it up against what your successful users do.

1. "Which users are in Good health and have been active for more than 90 days?" — this gives you the reference group.
2. "What features and events are most common across those users?" — the healthy profile.
3. "Now compare *jane@acme.com* against that profile. What is she not doing?" — the gap.
4. "Draft an in-app message nudging her toward those features." — the intervention, ready to send from journy.io.

This works across many accounts at once: *"Across all accounts in the Trial stage, which activation events are our converted accounts hitting that the current trials aren't?"*

## Build a Playbook from a sentence

1. Ask: "Create a Playbook for Trial accounts that haven't completed onboarding within 7 days. Goal: onboarding completed within 14 days."
2. The AI reads your existing Playbook groups and conditions, drafts the entry and goal conditions, and shows them to you.
3. Confirm. The Playbook is created (disabled by default).
4. Open it in journy.io and add the actions — Slack alert, email, in-app message, task — then enable it.

> 📝 ![Playbook created.png](media://80aeb501-816d-4c2b-aa0b-575c74331345)


> 📝 ![MCP Playbook created in Journy.png](media://99f33acb-959e-4710-855c-35d226a93317)

## Weekly usage trend report

Ask once, reuse every week: *"For every account in the Enterprise segment, show me event volume this week vs. last week. Flag any account where usage dropped more than 30% or where a key event stopped firing."* Pair it with *"Who are the champions at each flagged account?"* and you have a ready-made agenda for your CS review.

## Prepare for a renewal call

*"Give me a briefing on Acme Corp: current health and why, stage history, top three champions, usage trend over 90 days, open support tickets, and anything that changed in the last two weeks."* — one prompt, one page, and you walk in knowing the account.

# Saved questions

Journy ships twelve ready-made prompts your AI client can offer directly, covering the most common questions: contact health, accounts at risk, why an account is at risk, churn-prevention plan, expansion-ready accounts, upsell suggestions for an account, account champions, usage patterns, healthy usage patterns, recently churned, portfolio findings, and finding clients.

Owners and Admins can add their own under **Settings → MCP access → Saved questions**: give the prompt a name, title, description, and template. Any `{{placeholder}}` in the template becomes an argument the user fills in — for example `Why is {{account}} at risk, and what should we do this week?` Custom questions are listed and gated exactly like the built-in ones.

# Good to know

- **What the AI sees depends on who you are.** A tool you can't use is simply absent from the list rather than refused. If the AI says a tool doesn't exist, check your role, your approved scopes, and the MCP access settings.
- **Results are paged.** Searches return 20 results by default, up to 50 per page; ask for the next page if you need more.
- **Names, not guesses.** Segment IDs, view IDs, tag IDs, and property names come from journy.io. If the AI guesses one, it gets an empty result, not an error — ask it to list your segments or properties first.
- **API and console access** (calling Journy MCP from your own code via the Claude or OpenAI APIs, rather than from a chat client) needs a pre-issued token. Self-service token creation is not yet available — contact us if this matters for your use case.
- **Give us feedback.** This is a new surface and it improves with real use. If your AI can't do something you expected, or a tool behaves oddly, tell us — suggestions are turned directly into product work.

# Related documentation

- [Playbooks](https://releasemanagement.atlassian.net/wiki/spaces/journy/pages/2701590544) — the full anatomy of entry conditions, goal conditions, and exit actions your AI can now help you build.
- [Health Profiles](https://releasemanagement.atlassian.net/wiki/spaces/journy/pages/2709848087) — how health scores are configured; read this to understand what "at risk" means for your business.
- [Properties](https://releasemanagement.atlassian.net/wiki/spaces/journy/pages/2709258246) — the property names your AI will use in filters and conditions.
- [In-App Messaging](https://releasemanagement.atlassian.net/wiki/spaces/journy/pages/4318494721) — the native action for reaching users your AI has identified.
- [Playbook action: Triggering a webhook](https://releasemanagement.atlassian.net/wiki/spaces/journy/pages/4324589573) — orchestrating third-party systems from the Playbooks your AI creates.

> Macro (include)