---
title: Getting started with the Joyous Model Context Protocol (MCP)
description: Manage creation and execution of Joyous campaigns with AI agents through the Model Context Protocol (MCP) server.
---

[Skip to content](https://help.joyoushq.com/getting-started-with-the-joyous-model-context-protocol#main-content)

[![Joyous-logo-colour](https://help.joyoushq.com/hubfs/Joyous-logo-colour.svg)](https://help.joyoushq.com/?hsLang=en)

Open main navigation

Close main navigation

- [Go to bejoyous.ai](https://bejoyous.ai/)

[Go to bejoyous.ai](https://bejoyous.ai/)

 How can we help?

- There are no suggestions because the search field is empty.

1. [Help Center](https://help.joyoushq.com/?hsLang=en)
2. [Setting up Joyous](https://help.joyoushq.com/setting-up-joyous?hsLang=en)
3. [Other Integrations](https://help.joyoushq.com/setting-up-joyous?hsLang=en#other-integrations)

# Getting started with the Joyous Model Context Protocol (MCP)

## An interface for your AI agents to work with Joyous campaigns.

A Model Context Protocol (MCP) gives AI agents a structured way to interact with a system. The Joyous MCP server allows your AI agents to manage campaign creation.

### About this integration

Agents can:

- Create campaigns by searching for templates or by providing a goal statement.
- Refine campaign questions by interacting with the Joyous Campaign Assistant.
- Retrieve campaign participant links to distribute and gather feedback.

### Prerequisites

- Admin access to your Joyous instance.
- An MCP-compatible client or agent, such as an AI agent framework or desktop/client tool that can connect to an MCP server over HTTP.
- MCP is only available on paid plans.

### Create an MCP API Key

1. Navigate to [Settings \> Integrations](https://go.joyoushq.com/configure/integrations) in Joyous.
2. Click **Add new key**.
3. Select the *AI agent integration (MCP)* scope.
4. Copy the key to a safe location. You won't be able to view it again.
5. Copy the **MCP URL** for your region.

### Connect your agent or MCP client

1. Configure your MCP-compatible agent or client with: 
     1. The MCP URL for your region
     2. Bearer token authentication with your MCP API Key
2. Call `tools/list` to check configuration and return the tools available to your agent.

1. 1. Example request:  
        `curl -X POST https://mcp1.joyoushq.com/mcp \`  
        `  -H "Authorization: Bearer <prefix>.<plainKey>" \`  
        `  -H "Content-Type: application/json" \`  
        `  -H "Accept: application/json, text/event-stream" \`  
        `  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'`
     2. Ensure the URL reflects the correct `mcp{N}` prefix for your region.
     3. Replace `<prefix>.<plainKey>` with your MCP API key.

### Campaign creation workflow

Once your agent is connected and has access to the list of available tools, it is possible to manage campaigns in a variety of ways depending on your requirements. Joyous recommends the following workflow as a starting point.

1. Provide a goal statement to your agent about what you are trying to achieve with your feedback campaign: 
     1. Examples:  
            1. We need to reduce the number of repeat visits caused by failed installations by getting feedback from technicians.
            2. We need to progress deals faster by improving sales support and collateral for B2B by getting feedback from sales representatives and retail staff.
            3. We'd like to talk to our field techs to ensure new hires are onboarded efficiently and that our training is effective.
            4. We'd like to learn how to avoid repeat calls for the same customer issue and resolve issues faster by getting feedback from customer agents.
2. Your agent can contact the Campaign Assistant to generate a draft campaign based on Joyous methodology and best practice.
3. Your agent can review the draft questions, check their suitability against the goal statement, and either accept them to create the campaign or refine the goal statement to redraft.
4. After a campaign has been created, your agent can retrieve a participant link to distribute as needed. Anyone who clicks the link can leave feedback on the campaign.

### Appendices

#### Tools

| **Type** | **Tool** | **Description** |
| --- | --- | --- |
| Read | `search_templates` | Search the Joyous gallery for a template similar to a stated goal. |
| Read | `list_planning_boards` | List available boards containing campaigns. |
| Read | `list_campaign` | Paginated list of campaigns, optional filters: `Source: 'MCP'` and `planningBoardId`. |
| Read | `get_campaign` | Full campaign structure including conversation schema. |
| Create | `create_campaign` | Create a campaign with a specified template. |
| Create | `create_campaign_from_goal` | Generate a draft campaign with a goal statement using the Campaign Assistant. |
| Edit | `edit_campaign` | Rename campaign or replace conversation schema. Only MCP-sourced campaigns can be edited. |

#### URL endpoints

Your MCP URL endpoint is listed in [Settings \> Integrations](https://go.joyoushq.com/configure/integrations) when you create an API key with MCP scope. Contact your Joyous representative if you are unsure which URL to use.

| URL | Region | Serves |
| --- | --- | --- |
| `https://mcp1.joyoushq.com/mcp` | Sydney | AU, NZ |
| `https://mcp5.joyoushq.com/mcp` | Oregon | US |
| `https://mcp6.joyoushq.com/mcp` | Frankfurt | EU |
| `https://mcp8.joyoushq.com/mcp` | London | GB |
| `https://mcp18.joyoushq.com/mcp` | Montreal | CA |

#### Limits

`create_campaign_from_goal` is subject to a daily quota rate limiting.

If the quota is reached, the response includes information about when the quota resets.

- [Setting up Joyous](https://help.joyoushq.com/setting-up-joyous?hsLang=en#main-content)

    - [Overview](https://help.joyoushq.com/setting-up-joyous?hsLang=en#overview)
    - [People data integrations](https://help.joyoushq.com/setting-up-joyous?hsLang=en#people-data-integrations)
    - [Contact methods](https://help.joyoushq.com/setting-up-joyous?hsLang=en#contact-methods)
    - [Other Integrations](https://help.joyoushq.com/setting-up-joyous?hsLang=en#other-integrations)
    - [Dashboard sign-on](https://help.joyoushq.com/setting-up-joyous?hsLang=en#dashboard-sign-on)
    - [Privacy & security](https://help.joyoushq.com/setting-up-joyous?hsLang=en#privacy-security)
    - [Matrix relationships](https://help.joyoushq.com/setting-up-joyous?hsLang=en#matrix-relationships)
    - [Resources](https://help.joyoushq.com/setting-up-joyous?hsLang=en#resources)
- [Campaign stakeholder resources](https://help.joyoushq.com/campaign-stakeholder-resources?hsLang=en#main-content)

    - [Understanding notifications](https://help.joyoushq.com/campaign-stakeholder-resources?hsLang=en#understanding-notifications)
    - [Understanding the Live Feed & Inbox](https://help.joyoushq.com/campaign-stakeholder-resources?hsLang=en#understanding-the-live-feed-inbox)
    - [Understanding filters](https://help.joyoushq.com/campaign-stakeholder-resources?hsLang=en#understanding-filters)
    - [Understanding the Dashboard](https://help.joyoushq.com/campaign-stakeholder-resources?hsLang=en#understanding-the-dashboard)
    - [Understanding the Campaign Setup](https://help.joyoushq.com/campaign-stakeholder-resources?hsLang=en#understanding-the-campaign-setup)
    - [Understanding the Board](https://help.joyoushq.com/campaign-stakeholder-resources?hsLang=en#understanding-the-board)
    - [FAQs](https://help.joyoushq.com/campaign-stakeholder-resources?hsLang=en#faqs)
- [Audience resources](https://help.joyoushq.com/audience-resources?hsLang=en#main-content)

    - [Giving feedback](https://help.joyoushq.com/audience-resources?hsLang=en#giving-feedback)
    - [Changing your feedback](https://help.joyoushq.com/audience-resources?hsLang=en#changing-your-feedback)
    - [FAQs](https://help.joyoushq.com/audience-resources?hsLang=en#faqs)
- [The HR Engagement Model](https://help.joyoushq.com/the-hr-engagement-model?hsLang=en#main-content)

    - [The Joyous HR Engagement Model](https://help.joyoushq.com/the-hr-engagement-model?hsLang=en#the-joyous-hr-engagement-model)
- [Release notes](https://help.joyoushq.com/release-notes?hsLang=en)
- [Integrations](https://help.joyoushq.com/integrations?hsLang=en#main-content)

    - [ServiceNow](https://help.joyoushq.com/integrations?hsLang=en#servicenow)

- [Joyous status](https://status.joyoushq.com/)
- [Privacy](https://www.joyoushq.com/privacy)

[![Joyous](https://help.joyoushq.com/hubfs/Joyous-logo-colour.svg "Joyous")](http://joyoushq.com)

Joyous help center

Copyright © 2025, Joyous Ltd