MCP tools

The Embeddables MCP server lets MCP clients (Cursor, ChatGPT, Claude, and others) manage your projects, read analytics, run experiments, manage hosting, and operate Keepwell.

Connect

For clients configured with an mcpServers JSON file, such as Cursor, add the server URL:

{
  "mcpServers": {
    "embeddables": {
      "url": "https://mcp.embeddables.com/mcp"
    }
  }
}

For clients that add servers in their settings, such as ChatGPT, add https://mcp.embeddables.com/mcp as a custom MCP server. The client opens a browser window to sign in with your Embeddables email and a one-time code. Every tool call runs with your permissions: you can only see and change projects you are a member of, and only what your project role allows.

Conventions

Project tools take a project_id. Use admin_list_projects first to find it.
Session tools act on your own account and do not take a project_id.
Permissions: a call fails with Missing required project permission when your role does not include the permission the tool needs.
End-user data is anonymized. Tools that read end-user data return redacted values. Message bodies are only returned when you hold the bot.message_content.read permission.
Secrets are write-only. API keys and integration credentials are never returned after creation.

Projects and members

Tool	Description
`admin_list_projects`	List projects you are a member of.
`admin_get_project`	Get project metadata by id.
`admin_list_forms`	List deployed form ids and names for a project config branch.
`admin_list_form_fields`	Get the field schema of one form from the main deployed config. Fields marked `local_only` are excluded.
`admin_list_project_protocols`	List protocols granted to a project with live deploy state from the config branch (defaults to the main branch).
`admin_update_project`	Update project metadata.
`admin_disable_project`	Soft-disable a project.
`admin_enable_project`	Re-enable a soft-disabled project.
`admin_get_project_permission_catalog`	Get the permission catalog (version, keys, presets).
`admin_get_member_project_permissions`	Get one project member’s permission set.
`admin_update_member_project_permissions`	Replace one project member’s permission set.
`admin_list_field_classifications`	List HIPAA field-classification config for a form.
`admin_upsert_field_classifications`	Upsert HIPAA field-classification config for listed keys on a form.

Admin users and invites

Tool	Description
`admin_list_admin_users`	List admin users for a project.
`admin_get_admin_user`	Get an admin user by id for a project.
`admin_create_admin_user`	Create an admin user and add them to a project.
`admin_update_admin_user`	Update an admin user for a project.
`admin_disable_admin_user`	Soft-disable an admin user.
`admin_enable_admin_user`	Re-enable a soft-disabled admin user.
`admin_remove_admin_from_project`	Remove an admin user from a project without deleting their account.
`admin_list_project_invites`	List pending project member invites.
`admin_create_project_invite`	Invite an admin user to a project by email.
`admin_revoke_project_invite`	Revoke a pending project member invite.
`admin_accept_project_invite`	Accept a pending project invite for your account.

API keys

Tool	Description
`admin_create_project_api_key`	Create a project API key. The secret is returned once.
`admin_list_project_api_keys`	List project API keys. Secrets are never returned.
`admin_revoke_project_api_key`	Revoke a project API key.

Test traffic

Test traffic is a project’s list of IP addresses. Contacts seen on those addresses are flagged as test users in analytics.

Tool	Description
`admin_list_ip_disallowlist_entries`	List the project’s test-traffic IP entries.
`admin_upsert_ip_disallowlist_entries`	Create or update test-traffic IP entries.
`admin_delete_ip_disallowlist_entry`	Delete one test-traffic IP entry.
`admin_add_user_ip_to_test_traffic`	Add every distinct IP address observed for a project user to test traffic. IP values are not returned.
`admin_remove_user_ip_from_test_traffic`	Remove every distinct IP address observed for a project user from test traffic. IP values are not returned.

Analytics

Aggregates

All aggregate tools return totals for a project and date range.

Tool	Description
`analytics_list_funnel_overview`	Funnel overview KPIs.
`analytics_list_funnel_steps`	Contacts and events per funnel step.
`analytics_list_funnel_drop_off`	Drop-off counts per funnel step.
`analytics_list_page_traffic`	Page views and contacts per page key.
`analytics_list_results`	Event engagement counts.
`analytics_list_answer_breakdown`	Answer value counts for a form field (values are anonymized).
`analytics_list_contact_locations`	Contact counts by location.
`analytics_list_contact_browsers`	Contact counts by browser.
`analytics_list_contact_utm_values`	Distinct UTM values with contact counts.

Contacts

Contact tools return anonymized data.

Tool	Description
`analytics_list_contacts`	List contacts for a date range.
`analytics_list_contact_answer_values`	Distinct answer values with contact counts.
`analytics_get_contact_activity`	Event timeline for one contact: event names and page, button, form, and field keys, without answer values.
`analytics_get_contact_entries`	Form answer entries for one contact.
`analytics_list_contact_shared_ip_peers`	List other contacts that share network history with one contact.

Experiments

Tool	Description
`experiments_create`	Create an experiment with variants.
`experiments_list`	List experiments for a project.
`experiments_get`	Get an experiment definition by id.
`experiments_change_variant_weights`	Update variant weightings.
`experiments_add_variant`	Add a variant to an experiment.
`experiments_rename_variant`	Rename a variant.
`experiments_change_status`	Change status: running, paused, completed, or cancelled.

Integrations

Tool	Description
`integrations_get_tellescope_settings`	Read Tellescope connection status and whether an API key is set. The key is never returned.
`integrations_update_tellescope_settings`	Update the Tellescope API key. Omit it to keep the stored key.
`integrations_get_mdi_settings`	Read MDI connection status and whether a client secret is set. The secret is never returned.
`integrations_update_mdi_settings`	Update the MDI client secret. Omit it to keep the stored value.
`integrations_disconnect_tellescope_settings`	Disconnect Tellescope by clearing its stored credentials. An optional `environment` selects which credentials (default production).
`integrations_disconnect_mdi_settings`	Disconnect MDI by clearing its stored credentials. An optional `environment` selects which credentials (default production).

Gorgias

Tool	Description
`integrations_get_gorgias_settings`	Read Gorgias connection status, subdomain, account email, and whether an API key is set. The key is never returned.
`integrations_update_gorgias_settings`	Update Gorgias connection settings. Omit `api_key` or pass it empty to keep the stored key.
`integrations_disconnect_gorgias_settings`	Disconnect Gorgias by clearing its stored credentials and account settings.
`integrations_get_user_gorgias_tickets`	List Gorgias ticket summaries linked to a Keepwell end user. Requires a connected Gorgias integration.
`integrations_create_user_gorgias_ticket`	Create a Gorgias ticket for a Keepwell end user. Requires a connected Gorgias integration and exactly one matching Gorgias customer.

GitHub

Tool	Description
`integrations_get_github_connection`	Get GitHub connection status for a project.
`integrations_disconnect_github_connection`	Disconnect the project’s GitHub repository.
`integrations_list_github_pulls`	List open pull requests on the connected repository.
`integrations_get_github_pull`	Get one open pull request.
`integrations_list_github_pull_files`	List changed files for a pull request, optionally between two commits.
`integrations_list_github_pull_checks`	List check runs for a pull request head commit.
`integrations_merge_github_pull`	Merge a pull request. Experimental.
`integrations_list_pr_reviews`	List PR reviews for the connected repository.
`integrations_list_pull_pr_reviews`	List PR reviews for one pull request.
`integrations_get_pr_review`	Get one PR review.
`integrations_run_pr_review`	Start a manual PR review of one pull request.

Hosting

Tool	Description
`hosting_get_project`	Read a project’s hosting slug, whether it is enrolled, and how many apps it has.
`hosting_list_apps`	List hosting apps for a project.
`hosting_get_production`	Read the production alias currently served for a hosting app.
`hosting_list_deploys`	List commit builds of a hosting app, newest first, with the branch previews that serve each one.
`hosting_list_promotions`	List production promotions for a hosting app, newest first.
`hosting_list_domains`	List custom domains for a hosting app.
`hosting_list_deploy_keys`	List deploy key ids and prefixes. Never returns the secret or its hash.
`hosting_list_previews`	List a project’s branch preview URLs for one git branch.

Changes

Tools that change what a live hostname serves, or stop it serving, require confirm: true.

Tool	Description
`hosting_enroll_project`	Set the project’s hosting slug. It is part of every `embd.co` hostname the project serves, and it can only be set once.
`hosting_create_app`	Create a hosting app. Its next deploy starts serving on new `embd.co` hostnames for the project.
`hosting_update_app`	Update an app’s `repo_path` or `production_branch`. Changing `production_branch` immediately promotes that branch’s latest deploy, so it requires `confirm: true`.
`hosting_delete_app`	Delete a hosting app and its domains. Its hostnames and custom domains stop serving, and the allowed origins its active domains granted are removed. Requires `confirm: true`.
`hosting_add_domain`	Register a custom domain for an app as pending. It serves nothing until Embeddables staff attach it and mark it active.
`hosting_remove_domain`	Delete a custom domain. If it is active, it stops serving the app and the allowed origin it granted is removed. Requires `confirm: true`.
`hosting_promote_preview`	Point an app’s production alias at a preview label, including an older commit to roll back. Changes what production and every active custom domain serve. Requires `confirm: true`.
`hosting_create_deploy_key`	Create a project deploy key. Anyone holding it can deploy to the project. The `edk_` secret is returned once; store it as a CI secret.
`hosting_revoke_deploy_key`	Revoke a project deploy key. CI using it can no longer deploy. Requires `confirm: true`.

Keepwell

User-scoped reads return anonymized data. The one exception is message bodies, which are returned unredacted only when you hold the bot.message_content.read permission (see keepwell_list_user_messages and keepwell_get_user_message).

Configuration

Tool	Description
`keepwell_list_playbooks`	List playbooks for a project.
`keepwell_get_playbook`	Get one playbook by id.
`keepwell_create_playbook`	Create a playbook.
`keepwell_update_playbook`	Update a playbook.
`keepwell_get_settings`	Read bot instruction settings.
`keepwell_update_settings`	Update bot instruction settings.
`keepwell_list_knowledge`	List knowledge chunks.
`keepwell_search_knowledge`	Semantic search over knowledge chunks.
`keepwell_upsert_knowledge`	Create or update knowledge chunks in a batch, matched by optional chunk id.
`keepwell_delete_knowledge`	Delete a knowledge chunk by id.

Aggregates

All aggregate tools return project totals for a UTC date range.

Tool	Description
`keepwell_list_new_enrollments`	List initial live-user enrollments by UTC calendar day, including zero-count days.
`keepwell_get_opt_in_out_summary`	Initial live enrollments and opt-out transition totals for a range, with opt-outs grouped by channel.
`keepwell_get_engagement_summary`	Conversation engagement totals: replied user count and average inbound/outbound messages per enrolled user.

End users

Tool	Description
`keepwell_list_users`	List end users (anonymized).
`keepwell_get_user`	Get one end user (anonymized detail).
`keepwell_list_user_messages`	List messages for an end user. Requires `bot.message_content.read`.
`keepwell_get_user_message`	Get one message by id. Requires `bot.message_content.read`.
`keepwell_list_usage_logs`	List usage logs for an end user (payload omitted).
`keepwell_get_shopify_context`	Get redacted Shopify commerce context for an end user.
`keepwell_list_scheduled_runs`	List scheduled pipeline runs for an end user (redacted).
`keepwell_get_scheduled_run`	Get one scheduled pipeline run (redacted).
`keepwell_list_response_labels`	List response labels for one end user (no message body or notes).
`keepwell_list_project_response_labels`	List response labels across a project (redacted).
`keepwell_create_user`	Create a sandbox end user.
`keepwell_bulk_create_users`	Bulk-create end users from a natural-language prompt.
`keepwell_update_user`	Update a sandbox end user.
`keepwell_update_user_engagement_status`	Update a live end user’s engagement status.
`keepwell_delete_user`	Delete an end user.

Conversations

Tool	Description
`keepwell_simulate_inbound`	Simulate an inbound message from an end user.
`keepwell_reach_out`	Start a reach-out pipeline run for an end user.
`keepwell_regenerate`	Regenerate the latest draft for an end user.
`keepwell_approve_send`	Approve sending the latest draft message.
`keepwell_send_manual_message`	Send a manual operator message to an end user.
`keepwell_rollback_messages`	Roll back an end user’s messages from a timestamp.
`keepwell_fork_conversation`	Fork an end user’s conversation from a message.
`keepwell_create_message_response_label`	Label an outbound AI message with feedback.

Get Started

Hosting

MCP

SDKs

Connect

Conventions

Projects and members

Admin users and invites

API keys

Test traffic

Analytics

Aggregates

Contacts

Experiments

Integrations

Gorgias

GitHub

Hosting

Changes

Keepwell

Configuration

Aggregates

End users

Conversations

​Connect

​Conventions

​Projects and members

​Admin users and invites

​API keys

​Test traffic

​Analytics

​Aggregates

​Contacts

​Experiments

​Integrations

​Gorgias

​GitHub

​Hosting

​Changes

​Keepwell

​Configuration

​Aggregates

​End users

​Conversations

Connect

Conventions

Projects and members

Admin users and invites

API keys

Test traffic

Analytics

Aggregates

Contacts

Experiments

Integrations

Gorgias

GitHub

Hosting

Changes

Keepwell

Configuration

Aggregates

End users

Conversations