Nosto MCP Server Beta is now available to help out with documentation and implementation of GraphQL onsite sessions
When a new user comes to the app, you can use this method to get a new session. It will return you a customer-id that can save on the device and use for future requests. This would be ideal.
When a customer logs in, you can update the existing customer with the customer-reference. This would merge the online and mobile sessions. If not needed, I would omit this for now.
In order to use the GraphQL session mutation to fetch recommendations for your search page, the event, in this case, must be VIEWED_PRODUCT and you should specify the product-identifier of the current product being viewed.
In order to use the GraphQL session mutation to fetch recommendations for your category page, the event, in this case, must be VIEWED_CATEGORY and you should specify a fully qualified category path of the current category. For example, if you have a category called "Dresses" under the category "Women", the FQCN would be "/Women/Dresses".
In order to use the GraphQL session mutation to fetch recommendations for your search page, the event, in this case, must be SEARCHED_FOR and you should specify the search term of the query.
In order to use the GraphQL session mutation to fetch recommendations for your cart or checkout page, the event, in this case, must be VIEWED_PAGE and you should specify a fully qualified URL of the page as the target.
In order to use the GraphQL session mutation to fetch recommendations for your home or front page, the event, in this case, must be VIEWED_PAGE and you should specify a fully qualified URL of the page as the target
Recommendation results can be attributed to events by setting a session event's ref to the recommendation result's resultId.
Here is an example of some recommendations for a front page. You can see recommendation result's resultId is "frontpage-nosto-1".
If a customer selects to view the Cool Kicks product, you can generate the following request. Note that the event's ref is set to "frontpage-nosto-1".
When making GraphQL queries from mobile applications, it's essential to define the user agent string in your HTTP headers. Ideally, the user agent should represent the mobile environment, including details such as the platform, device type, and application version. Avoid using terms like "bot" in the user agent string, as this might lead to unintended behavior or rejection of the query/session. Sending an empty user agent will also lead to be catch by the bot detection mechanism.
mutation {
newSession(referer: "https://google.com?q=shoes")
}mutation {
updateSession(by: BY_CID, id: "5b1a481060b221115c4a251e",
params: {
event: {
type: VIEWED_PRODUCT
target: "11923861519"
ref: "front-page-slot-1"
}
}
) {
pages {
forProductPage(params: {
isPreview: false, imageVersion: VERSION_8_400_400
}, product: "11923861519") {
divId
resultId
primary {
productId
}
}
}
}
}mutation {
updateSession(by: BY_CID, id: "5b1a481060b221115c4a251e",
params: {
event: {
type: VIEWED_CATEGORY
target: "/Shorts"
}
}
) {
pages {
forCategoryPage(params: {
isPreview: false, imageVersion: VERSION_8_400_400
}, category: "Shorts") {
divId
resultId
primary {
productId
}
}
}
}
}mutation {
updateSession(by: BY_CID, id: "5b1a481060b221115c4a251e",
params: {
event: {
type: SEARCHED_FOR
target: "black shoes"
}
}
) {
pages {
forSearchPage(params: {
isPreview: false, imageVersion: VERSION_8_400_400
}, term: "black shoes") {
divId
resultId
primary {
productId
}
}
}
}
}mutation {
updateSession(by: BY_CID, id: "5b1a481060b221115c4a251e",
params: {
event: {
type: VIEWED_PAGE
target: "https://example.com/cart"
}
}
) {
pages {
forCartPage(params: {
isPreview: false, imageVersion: VERSION_8_400_400
}, value: 100) {
divId
resultId
primary {
productId
}
}
}
}
}mutation {
updateSession(by: BY_CID, id: "5b1a481060b221115c4a251e",
params: {
event: {
type: VIEWED_PAGE
target: "https://example.com"
}
}
) {
pages {
forFrontPage(params: {
isPreview: false, imageVersion: VERSION_8_400_400
}) {
divId
resultId
primary {
productId
}
}
}
}
}{
"data": {
"updateSession": {
"pages": {
"forFrontPage": [
{
"resultId": "frontpage-nosto-1",
"primary": [
{
"productId": "9497180547",
"name": "Cool Kicks",
"url": "https://example.com/products/cool-kicks"
},
{
"productId": "9497180163",
"name": "Awesome Sneakers",
"url": "https://example.com/products/awesome-sneakers"
},
{
"productId": "4676165861430",
"name": "Free gift",
"url": "https://example.com/products/free-gift"
},
{
"productId": "2188051218486",
"name": "Furry Dice",
"url": "https://example.com/products/furry-dice"
},
{
"productId": "9497180611",
"name": "Gnarly Shoes",
"url": "https://example.com/products/gnarly-shoes-1"
}
]
}
]
}
}
}
}mutation {
updateSession(by: BY_CID, id: "5b1a481060b221115c4a251e",
params: {
event: {
type: VIEWED_PRODUCT
target: "9497180547"
ref: "frontpage-nosto-1"
}
}
) {
pages {
forProductPage(params: {
isPreview: false, imageVersion: VERSION_8_400_400
}, product: "9497180547") {
divId
resultId
primary {
productId
}
}
}
}
}This MCP server provides a comprehensive set of GraphQL tools for integrating Nosto's personalization and recommendation engine into commerce applications.
Nosto MCP Server is in Beta state, and any generated code should be reviewed.
MCP (Model Context Protocol) is a standardized protocol that allows AI assistants like Claude to connect to external tools, databases and services. Think of it as a bridge that extends AI assistants capabilities with specialized functionality.
The Nosto MCP server exposes 7 main GraphQL tools that handle different aspects of Nosto Integration:
Session Managing - Creating and managing user sessions
Event Tracking - Tracking user interactions and behaviour
Recommendations - Fetching personalized product recommendations
Complete Workflows - End-to-end integration patterns
There are also 2 Documentation tools
Feature Documentation - RAG-powered feature documentation search
Technical Documentation - RAG-powered code/technical documentation search
Server URL
Nosto MCP server specializes in:
Nosto GraphQL API Integration
Multi-framework support (React, Next Js, Shopify Hydrogen, etc.)
Production-ready code generation
Best practives enforcement
Nosto MCP server can be used with any AI Assistant that support Model Context Protocol. Claude code is used in the documentation below.
Prerequisites: You need access to Claude Code (Anthropic's IDE integration) to use Nosto MCP servers.
Step 1
Configure MCP
Add the Nosto MCP server to your Claude Code configuration:
Step 2
Verify Connection
Test the connection by asking Claude:
Claude should respond with the 7 GraphQL specific tools and 2 (RAG) documentation tools.
Step 3
Start Building
Now you can request complete integrations:
Claude will automatically use the MCP tools to generate complete, production-ready code, including the creation of Nosto specific service, creating a newSession request, storing the sessionId, and calling updateSession and retrieve recommendations.
MCP server is aware of the step by step workflow of how Nosto should be implemented and how graphQL mutations should look. This means that asking AI assistant such as:\
Will look through multiple tools exposed by the Nosto MCP Server
And will generate the Nosto service code which is aware of creating a new session, storing sessionId in the cookie, and using the sessionId for update session mutations and getting recommendations.
End result is visible Nosto recommendations on home and product pages within minutes.
The MCP server provides 7 specialized graphql tools that can be combined. to create complete e-commerce solutions.
Common usage patters:
Homepage integration "Add Nosto Recommendation to my React homepage" -> Uses generate_nosto_service + generate_complete_workflow tools
Product page setup "Set up Nosto on my Shopify Hydrogen product page" -> Uses generate_nosto_service + generate_complete_workflow tools + Includes Shopify GID handling
Explanation of the Nosto "Explain how Nosto can be integrated on my store" -> Uses generate_complete_workflow + concept_explainer
If you have found MCP server useful, or if you found some issues or would like MCP server to support more use-cases please don't hesitate to contact us at [email protected]
\
Service Layer - Clean architecture with service classes
Cookie Management - Session persistence via cookies
Concept Explanation - Educational content about Nosto GraphQL concepts
Technical documentation from https://docs.nosto.com
{
"mcpServers": {
"nosto-graphql": {
"type": "http",
"url": "https://dev.mcp.nosto.com/mcp",
"env": {}
}
}
}
Can you list the available Nosto GraphQL tools?Add Nosto product recommendations to my home page