MCP Server (AI agents)
Joryio is an MCP server. An AI assistant connects to it with a sign-in, then works with your workspace: lists campaigns and journeys, reads their results and Launch Review findings, queries events, checks what content performs, and - when you allow it - creates campaign drafts and segments for a person to review.
There is nothing to install and no key to copy. The agent talks to the same public REST API documented under API Reference; every tool is one documented endpoint.
Permissions - whose access does the agent get?
Yours. When you connect an AI client, Joryio sends you to a consent screen in the dashboard where you sign in as yourself and tick what the agent may do. From then on the agent acts as you, limited to what you ticked:
- It can never do more than you can. The consent screen only offers permissions you hold, and every request checks both your permissions and the ticked scopes.
- Lose a permission and every agent you connected loses it on its next request. Disconnect an agent under Settings > General and its tokens stop working at once.
- Each connection is bound to the workspace you were in when you approved it.
- Actions the agent takes are recorded as you. Make the connection for the role you mean: a colleague who connects Claude as themselves grants their own access, not yours.
There is no separate "agent user" and no API key to manage. Organisations that prefer keys can still use the REST API directly.
Contact data is off by default
People data is the sensitive part of a marketing workspace, so an AI agent does not get it unless two things are true:
- An admin has switched on Allow AI agents to read contact data under Settings > General for the organisation. Until then the consent screen does not offer the contact tools at all.
- The person connecting the agent holds the permission AI agents: contact data (
agents:contacts, an admin-tier permission) and ticks it on the consent screen.
Even then, fields the workspace marks as personal data come back masked unless that person holds the PII permission - the same rule the dashboard and the REST API apply. An API key can carry the agents:contacts scope under the same organisation switch.
Connecting a client
Your connector URL is shown under Settings > General > AI agents with a Copy button. Take it from there rather than typing it: each Joryio region has its own URL, and the card always shows the one for the region your workspace lives in. For the EU region it is:
https://api-eu1.joryio.com/api/mcp
- Claude (claude.ai, Claude Desktop, Claude Code): add a custom connector with that URL, or
claude mcp add --transport http joryio https://api-eu1.joryio.com/api/mcp. - ChatGPT: add the URL as a connector in the app's connector settings.
- Grok (xAI): see Grok below - grok.com and the Grok Build CLI connect with a sign-in; the xAI API does not.
- Cursor and other clients that support remote (Streamable HTTP) MCP servers with OAuth: add the URL; the client registers itself and opens the consent screen in your browser.
- Clients that only run local servers: use the community bridge
npx -y mcp-remote https://api-eu1.joryio.com/api/mcp.
The server uses OAuth 2.1 with dynamic client registration and PKCE; discovery is at https://api-eu1.joryio.com/.well-known/oauth-authorization-server. Access tokens last one hour and refresh silently for thirty days or until you disconnect.
Grok (xAI)
- grok.com: open grok.com/connectors, choose New Connector, then Custom, and paste your connector URL. Grok sends you to the Joryio consent screen to sign in and tick what it may do. On Grok Business and Enterprise a team admin first provisions the connector in xAI's console; members then find it in their connectors.
- Grok Build (the
grokCLI):grok mcp add --transport http joryio https://api-eu1.joryio.com/api/mcp. The sign-in opens in your browser the first time Grok uses the server; you can also start it from the MCP tab under/mcps. - xAI API (remote MCP tools in a Responses request): not supported. That route sends a fixed token in the
Authorizationheader and cannot complete a sign-in, and Joryio's MCP endpoint accepts only the tokens its sign-in issues - an API key is refused. To reach Joryio from your own code on the xAI API, call the REST API with an API key from your own function tools.
What the consent screen offers
| Group | Scopes | What the agent can do |
|---|---|---|
| Read | campaigns:read canvas:read segments:read events:read analytics:read | List and read campaigns, journeys, segments, events, reports and the catalogue |
| Create drafts | campaigns:write segments:write events:track | Create campaign drafts and segments for you to review; record events |
| Contact data | users:read users:write agents:contacts | Search and read people, update their attributes - only with the organisation switch on |
Ticked by default: what the client asked for, or the Read group.
Tools
| Tool | What it returns | Endpoint |
|---|---|---|
list_campaigns | Campaigns by status, channel or name | GET /campaigns |
get_campaign | One campaign with its variants and targeting | GET /campaigns/:id |
get_campaign_stats | Sent, delivered, opened, clicked, conversions | GET /campaigns/:id/stats |
get_campaign_failure_reasons | Delivery failures by provider code | GET /campaigns/:id/failure-reasons |
get_campaign_launch_review | Blockers and recommendations | GET /campaigns/:id/launch-review |
get_campaign_performance | Campaigns ranked by incremental conversions, each on its own conversion goal | GET /campaigns/performance |
get_journey | One journey in full: trigger, nodes with their messages, edges | GET /journeys/:id |
list_journeys, get_journey_stats, get_journey_launch_review | The same for journeys | GET /journeys… |
list_segments, get_segment_size | Saved audiences and their size | GET /segments… |
list_contact_imports | Contact imports by file name and date, for a "came from import" segment filter (needs users:read, not agents:contacts) | GET /users/import/sources |
query_events, list_recent_events, get_event_trend | Events in a range, the explorer, a trend | GET /events/query, GET /analytics/events, POST /analytics/events/trend |
get_active_users_now, get_content_performance | Live count, what content works | GET /analytics/… |
list_products, get_catalog_stats | Catalogue and its health | GET /catalog/… |
create_campaign_draft | Creates a campaign as a draft - always a draft, whatever the agent asks | POST /campaigns |
create_segment | Creates a saved segment | POST /segments |
track_event | Records an event for a person | POST /users/track |
search_contacts, get_contact, update_contact | People (contact data group only) | GET /users/search, GET /users/:id, PUT /users/by-user-id/:id |
A tool appears only when the connection carries its scope.
What the agent can never do
There is no tool that sends, schedules, activates, approves, resends, exports or deletes anything, and none that manages API keys or team members - whatever you ticked. A draft the agent creates waits in the dashboard for a person to review, run Launch Review, and send.
Managing connections
Settings > General > AI agents lists the agents connected as you, with the scopes each holds and when it was last used. Disconnect revokes it immediately. Admins find the organisation-wide contact-data switch on the same card.
Limits
Requests count against the workspace's normal API rate limits; the agent is told to wait when it hits one. Each tool call times out after 30 seconds. Lists are paginated with the same limit and page / offset parameters as the REST API.