This guide explains how to set up and use Yoodli’s MCP (Model Context Protocol) integration with Claude (Claude.ai). It covers the required admin steps in Yoodli and Claude, the user flow, and key implementation details you need to know for testing and production.
Before you start — who does what
Three roles are involved and all three steps must be completed in order before a user can connect:
Yoodli Admin — enables the MCP integration for the Yoodli org (one-time). Must happen first.
Claude.ai Admin — adds Yoodli as a connector inside the Claude.org admin settings (one-time). Must happen second.
User — connects their Claude account to Yoodli and activates the connector in the Claude conversation they want to use (done once per person per org). Happens last.
Step 1 — Yoodli Admin: Enable MCP for your org
Sign in to Yoodli as an org admin.
Go to Settings → Integrations.
Find the MCP integration toggle and enable it.
Notes
Whether the toggle appears at all is controlled by a rollout/feature gate. If the toggle is not visible, the org hasn’t been enabled for MCP rollout — contact your Yoodli account team.
Disabling the toggle immediately blocks all MCP access for that org. No re-authentication is required; existing connections stop working.
Step 2 — Claude.ai Admin: Add Yoodli as a connector
In Claude, go to claude.ai/admin-settings/connectors.
Click Add custom connector.
Name the connector (example: Yoodli).
For the connector URL, enter Yoodli’s MCP base URL:
Production: https://app.yoodli.ai/api/mcp/1.0
Leave the Advanced Settings (Client ID / Client Secret) blank — not required.
Click Add.
Why no credentials in admin settings?
Yoodli supports Dynamic Client Registration (DCR). The OAuth client registration step runs automatically during the MCP registration flow and the server issues a client_id (and optionally a client_secret). Pre-registering a client ID/secret is not required for the standard Claude integration flow.
Operational note: the server may persist a generated client_secret during registration. That secret is not normally needed or entered into the Claude admin UI for the typical DCR scenario.
Step 3 — User: Connect your Claude account
Connect your account
In Claude, go to Settings → Connectors.
Find Yoodli in the list and click Connect.
You’ll be redirected to a Yoodli consent page. Sign in with your Yoodli credentials if prompted.
The consent page shows the connecting application and the Yoodli org being authorized — confirm they’re correct.
If you belong to multiple Yoodli orgs with MCP enabled, select the org for the connection.
Click Authorize. You’ll be returned to Claude and the connector will show as Connected.
How auth works
Yoodli uses OAuth 2.1 with PKCE. Yoodli never shares your Yoodli password with Claude. Access tokens refresh automatically so users stay connected without re-authenticating frequently.
During authorization the consent page requests a Firebase authentication assertion; the consent callback binds the OAuth authorization code to the authenticated Yoodli user and the chosen org.
Full set of MCP capabilities (tools) and behaviors
Yoodli exposes a set of MCP tools. Each tool is registered on each transport request and runs with the authenticated user and org context from the OAuth access token. Tools return JSON-RPC responses. Below are the implemented tools and what each does.
1) list_user_roleplays
Purpose
Discover roleplay scenarios available to the authenticated user in the authorized org.
Behavior / Inputs
Supports search and filtering by topic, persona, goals, skills, etc.
Returns names, descriptions, AI persona details (for contextualization), metadata about scenario content, and direct launch URLs into Yoodli.
Auth / Authorization
Requires the user to be a member of the org and possess in-product permission to view scenarios.
Tool includes org enablement and RBAC checks upstream.
Typical consumer use
Populate a selection list inside Claude that lets the user choose a roleplay to launch in Yoodli.
2) check_builder_access (aka check_builder_access / registerCheckBuilderAccess)
Purpose
Check whether the current user can open the Yoodli roleplay builder, and at what scope (personal vs org-wide).
Behavior / Inputs
No heavy input. Optionally accepts a requested mode (personal vs org).
Returns boolean flags: canCreatePersonalRoleplay, canCreateOrgRoleplay, and any gating reasons.
Auth / Authorization
Uses RBAC to determine builder access levels. For org-wide builder creation, checks that the user has org-level authoring permissions.
Typical consumer use
Determine whether to present builder UI affordances in the client or ask follow-up questions.
3) launch_builder
Purpose
Produce a URL that launches the Yoodli roleplay builder, optionally pre-populated with provided context.
Behavior / Inputs
Accepts optional contextual inputs: skills, goals, counterparty role, meeting/event description, contact details, CRM/meeting context, etc.
Returns a direct URL that opens the Yoodli builder pre-configured for the scenario, or a redirect/launch object as appropriate.
Auth / Authorization
Ensures the user has builder access (personal or org-wide) and the org is MCP-enabled.
Typical consumer use
Let Claude produce a builder URL with context (e.g., meeting summary) so the user can open Yoodli and edit before practice.
4) create_contextual_roleplay
Purpose
Create a contextual roleplay (a ready-to-practice scenario) based on supplied context.
Behavior / Inputs
Accepts structured context from CRM, calendar, email, or user-provided text describing the meeting and counterparty. Also accepts desired goals and skills.
Builds a roleplay scenario mapping counterparty details to an AI persona, populates objections, goals and initial prompts, and returns a practice URL.
Auth / Authorization
Requires user to have creation rights (checked by builder access / RBAC) and the org to be enabled.
Typical consumer use
Claude composes a scenario from meeting notes and returns a direct practice link.
5) create_contextual_roleplay_via_generate (the Generate Pipeline variant)
Purpose
Same goal as create_contextual_roleplay but executes the full LLM-driven generate pipeline for richer persona and objection generation.
Behavior / Inputs
Used when feature-gated for orgs/users who should receive a richer, model-driven build process (versus a lightweight direct mapping).
The server selects between the two implementations at runtime based on feature gate (McpRoleplayViaGenerate) and/or user flags.
Auth / Authorization
Same authorization checks as the direct builder creation tool.
Typical consumer use
When higher-fidelity/customization is desired and allowed by gating, Claude triggers the generate pipeline to produce a more sophisticated scenario.
Authorization / RBAC
All MCP tool calls go through an authorization preamble that:
Validates the Bearer token and extracts userId and orgId.
Verifies the org has MCP enabled.
Verifies the user is a member of the authorized org.
Applies RBAC checks matching the in-product permissions for that user within the org.
The MCP server acts as the authorizing user; it does not use elevated, service, or org-level privileges beyond what the user has.
Transport and scaling
The MCP transport uses stateless StreamableHTTP transport: each incoming JSON-RPC request creates a fresh server/transport instance, executes the request, and tears down. All persistent data is in Firestore. This design allows horizontal scaling and no in-memory session state.
Troubleshooting / common failure modes
Toggle not visible: Feature may not be enabled for your org yet. Contact the Yoodli account team.
Consent page shows no orgs: User belongs to no MCP-enabled orgs; ask the org admin to enable MCP for the org.
Transport calls return 401 / 403: Common causes:
Invalid or expired access token (401). Ensure token exchange completed successfully.
Token missing identity context (userId/orgId) — malformed token or registration problem.
Org not enabled or user not a member of the org (403).
Where did the client secret go? If the SDK generated a client_secret during registration it is stored server side; DCR clients typically do not need a manual secret entry for Claude’s connector configuration.
Short checklist for a successful setup
Yoodli org admin enables MCP in Settings → Integrations.
Claude admin adds a custom connector with the correct MCP URL (production or local). Leave client ID/secret blank.
User connects to Yoodli in Claude via Settings → Connectors → Yoodli and completes consent.
User activates Yoodli per conversation via + → Connectors → Yoodli.
Verify by running discovery and a simple tool call (list roleplays or open builder).