Skip to content
Go to bejoyous.ai
  • There are no suggestions because the search field is empty.

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 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. 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 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.