Storyly Integration MCP Guide
The Storyly Integration MCP gives a developer's AI coding assistant access to Storyly's currently published documentation, API reference, SDK versions, and release notes. This document isn't about how the server works — it's about how to get the best results from it: which tool answers which question, what to ask, and how to steer the assistant.
If you just want Storyly running in your app, start with the Quickstart below. The numbered sections after it explain how to keep getting good results once you're past the basics.
Quickstart
We suggest pasting these prompts into your AI coding assistant one at a time, in the order below. Each prompt does one job and ends with a check you can see, so it's worth confirming that check before going on to the next one.
Before you start
These are the things the assistant can't do for you:
- The Integration MCP is connected in your assistant (Claude Code, Cursor, etc.), and your app's project is open in it.
- You have a placement token. Log in to the Storyly Dashboard, open your placement, and copy its token.
- That placement has at least one published widget. If there's no live content, the SDK correctly hides the placement view and the integration looks broken even though it works. Most "nothing shows up" reports come from this.
Prompt 1: Set up the assistant
This saves the Storyly rules into your project, so the assistant uses the MCP instead of answering from memory, and it finds your platform and SDK version by itself.
Add the following section to this project's persistent instructions file (CLAUDE.md for Claude Code, .cursor/rules for Cursor; create it if it doesn't exist):
## Storyly SDK
- For any question or code involving the Storyly Placement SDK, use the Storyly Integration MCP first; don't answer from memory.
- Before calling the MCP, determine this project's platform, UI framework, and Storyly SDK version from its dependency files and source.
- Always pass that platform as the `platform` parameter in tool calls.
- Before using an API that isn't in the guide, verify it with `get_api_reference`.
- If unsure whether a feature exists in the current version, use `get_release_notes` with `sinceVersion`.
Then tell me this project's platform, UI framework, package manager, and current Storyly SDK version (or "not installed").
✅ Done when: the assistant names the correct platform and UI framework (e.g. iOS / UIKit / SPM, Android / Jetpack Compose / Gradle) and the correct SDK version or "not installed". If it gets any of these wrong, correct it before continuing.
Prompt 2: Install the SDK
Using the Storyly Integration MCP, add the latest Storyly Placement SDK to this project with our existing package manager. Follow the initial setup guide for our platform. Don't write any UI code yet. Build the project and fix anything that breaks.
✅ Done when: the project builds and the Storyly modules import without errors.
Prompt 3: Show a placement
Replace <SCREEN> with the screen where Storyly should appear (e.g. the home screen, HomeViewController, HomeFragment) and <YOUR_PLACEMENT_TOKEN> with the token from the Dashboard.
Using the Storyly Integration MCP initial setup guide for our platform and UI framework, add a Storyly placement to the top of <SCREEN> with the placement token <YOUR_PLACEMENT_TOKEN>.
- Resize the placement view when onWidgetReady reports a new ratio.
- Handle onActionClicked by logging the URL for now.
- Add a log line to each of these callbacks.
Build the project when you're done.
✅ Done when: you run the app, open that screen, and a Storyly widget appears.
Prompt 4: Check it works
Check the Storyly integration in this project against the best-practices list in the MCP's initial setup guide for our platform, and fix anything missing. Then tell me exactly which log lines I should see when the placement loads and when I tap an action in the content.
✅ Done when: the logs you see match what the assistant told you to expect: the widget-ready log when the placement loads, and the action-clicked log with a URL when you tap a story's action. Storyly is now running in its basic form.
What's next
From here, you can ask the assistant to add the features you need, one at a time. These are the most common ones, each backed by its own guide in the MCP:
| Feature | Ask |
|---|---|
| Deep links | "Using the Storyly Integration MCP, handle Storyly deep links in this app, including opening a story from a push notification." |
| Shoppable content | "Using the Storyly Integration MCP, connect Storyly's add-to-cart and wishlist actions to our existing cart." |
| Targeting with labels | "Using the Storyly Integration MCP, show Storyly content only to <segment, e.g. premium users> using labels." |
| Audience targeting | "Using the Storyly Integration MCP, set up Storyly audience targeting for this app." |
| Personalization | "Using the Storyly Integration MCP, pass the user's <properties, e.g. name and city> to Storyly as user properties." |
| Analytics | "Using the Storyly Integration MCP, forward Storyly events to <our analytics tool>." |
For more examples, such as upgrading the SDK or checking whether your version supports a feature, see section 3.
1. Which tool answers which question?
The assistant picks the tool itself, but knowing which question lands on which tool helps you phrase the question well and read the answer correctly.
| Question type | Tool | What it returns |
|---|---|---|
| "How do I integrate X?" | get_feature_guide | The full published guide for that platform (steps, listener setup, code samples), with <latest-version> placeholders filled in with the current SDK version |
"What is STRPlacementView, what's its signature?" | get_api_reference | Android/iOS/Web signatures, fully-qualified name, integration.storyly.io links, and the features that use that API |
| "What's there about this?" (topic unclear) | search_knowledge | A ranked list of matches across guides and API references |
| "What's the latest SDK version?" | get_latest_sdk_version | The latest published version from Maven Central (Android) or SPM tags (iOS) |
| "What changed after version X?" / "Which version added this feature?" | get_release_notes | The upgrade gap with sinceVersion, a single release with version, or the most recent entries with neither |
2. Asking the right question — two rules
1. Make sure the platform is known. This is the most important rule. Guides, release notes, and SDK versions are all platform-specific, so if the assistant asks "how do I set up deep links?" for an iOS project without passing the platform, it may come back with the wrong platform's guide. Valid values: android, ios, reactnative, flutter, web.
2. Make sure the integrated version is known. Knowing that "the project uses Android SDK 1.15.0" lets the assistant call get_release_notes with sinceVersion and tell you "the feature you're looking for shipped in 1.16.0, upgrade first." Without a version, the assistant may apply the latest guide as if everything in it exists in your older version.
Note: When the codebase is open, the assistant can find both itself. Claude Code, Cursor, and similar tools can read the platform and SDK version from the project's dependency files, so just ask them to check first (or add it to the persistent instructions, see section 4). Only state them yourself when the assistant can't see the code, or when it's unclear which app you mean.
Weak vs. strong example:
"How do I add a cart with Storyly?"
✅ "Add Storyly shoppable content cart support to this app. Check our SDK version first."
✅ (no codebase access) "How do I add shoppable content cart support on iOS with Storyly SDK 1.14.0?"
3. What to ask
You don't need to name tools — describe the goal and the assistant picks the right calls.
| Goal | Ask |
|---|---|
| Integrate from scratch | "Integrate Storyly Placement into this app using the latest SDK." |
| Add a placement to a screen | "Add a Storyly placement to the home screen." |
| Upgrade the SDK | "Upgrade Storyly to the latest version and update anything that changed." |
| See what's new | "What changed in Storyly since our version?" |
| Check if a feature exists | "Does our Storyly version support wishlist? If not, which version added it?" |
| Target user segments | "Show Storyly content only to premium users using labels." |
| Target an audience | "Set up Storyly audience targeting for this app." |
| Personalize content | "Pass the user's name and city to Storyly as user properties." |
| Shoppable content | "Connect Storyly's add-to-cart and wishlist to our cart." |
| Deep links | "Handle Storyly deep links and open a story from a push notification." |
| Analytics | "Forward Storyly events to our analytics tool." |
| Understand an API | "What does STRPlacementDataProvider do and where is it used?" |
| Fix a build error | "Fix this Storyly build error: <error>" |
| Compare platforms | "What's the iOS equivalent of the Android placement listener?" |
4. Steering the assistant to the MCP — persistent instructions
Even with the connection in place, the assistant sometimes skips the MCP and answers from memory. The most effective fix is a short rule in the project's persistent instructions file (CLAUDE.md for Claude Code, .cursor/rules for Cursor). If you followed the Quickstart, Prompt 1 already added it:
## Storyly SDK
- For any question or code involving the Storyly Placement SDK, use the Storyly Integration MCP first; don't answer from memory.
- Before calling the MCP, determine this project's platform, UI framework, and Storyly SDK version from its dependency files and source.
- Always pass that platform as the `platform` parameter in tool calls.
- Before using an API that isn't in the guide, verify it with `get_api_reference`.
- If unsure whether a feature exists in the current version, use `get_release_notes` with `sinceVersion`.
With this in place, the assistant looks up the platform and version on its own and you don't have to repeat them in every question — both rules in section 2 are covered automatically. In a monorepo, name which app the file applies to (or put one in each app's folder).
Updated 1 day ago