Sutra MCP Server

An MCP server that connects AI agents to the Sutra Admin API. Manage spaces, members, contacts, content, discussions, surveys, plans, broadcasts, and more — all through your AI tools.

Quick Start

npm install -g @sutraspaces/mcp-server

Or run directly with npx:

SUTRA_API_TOKEN="sutra_live_sk_..." npx -y @sutraspaces/mcp-server

You can get an API token from your Sutra account settings or by contacting [email protected].

Usage

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "sutra": {
      "command": "npx",
      "args": ["-y", "@sutraspaces/mcp-server"],
      "env": {
        "SUTRA_API_TOKEN": "sutra_live_sk_..."
      }
    }
  }
}

Claude Code

claude mcp add sutra -- env SUTRA_API_TOKEN=sutra_live_sk_... npx -y @sutraspaces/mcp-server

Cursor / Windsurf / Other MCP Clients

Point your MCP client at npx -y @sutraspaces/mcp-server with the SUTRA_API_TOKEN environment variable set. The server communicates over stdio.

Configuration

| Variable | Required | Description | |---|---|---| | SUTRA_API_TOKEN | Yes | Your Sutra Admin API token (sutra_live_sk_...) | | SUTRA_BASE_URL | No | Override the API URL (default: https://api.sutra.co/api/admin/v1) |

Available Tools

Deep Traversal

• get_space_deep — Recursively fetch a space and all its nested content in one call: content blocks, discussion messages, reflections, and child spaces. Rich text is converted to plain text. Configurable depth, item limits, and whether to include reflections. Best for exploring an entire course, community, or discussion hierarchy.

Spaces

• list_spaces — List all spaces the API token can access
• list_membership_spaces — List basic read-only information about spaces where the API token owner is a member
• get_space — Get details for a single space
• list_child_spaces — List direct child spaces
• create_space — Create a new space (top-level or child)
• update_space — Update space name, description, type, privacy, or state
• delete_space — Delete/archive a space
• reorder_child_spaces — Reorder children within a parent

Members

• list_members — List space members with optional email, user_id, search, role, state, and custom property filtering
• get_member — Get member details
• add_member — Add a member by email or user ID
• update_member — Update role or notification settings
• remove_member — Remove a member (cascades to descendant spaces)
• approve_member — Approve a pending member
• bulk_add_members — Add up to 100 members at once
• bulk_remove_members — Remove up to 100 members at once

Contacts

• list_contacts — List CRM contacts from the Contacts/Interested layer with optional email, search, and custom property filtering
• get_contact — Get contact details
• get_contact_property_values — Read property values for a contact
• update_contact_property_values — Set or clear property values for a contact
• bulk_update_contact_property_values — Set or clear property values for up to 100 contacts at once

Content & Discussions

• list_content / get_content_block / create_content / update_content / delete_content — Manage content blocks
• reorder_content — Reorder content blocks within a space
• list_messages / get_message / create_message / update_message / delete_message — Manage discussion messages
• list_reflections / get_reflection / create_reflection / update_reflection / delete_reflection — Manage threaded replies

Properties

• list_member_properties / create_member_property / update_member_property / delete_member_property — Manage custom member property definitions
• get_member_property_values / update_member_property_values / bulk_update_member_property_values — Read, set, and bulk set property values for members
• get_contact_property_values / update_contact_property_values / bulk_update_contact_property_values — Read, set, and bulk set property values for contacts
• list_space_properties / create_space_property / update_space_property / delete_space_property — Manage custom space property definitions
• get_space_property_values / update_space_property_values — Read and set property values per space

Invitations

• list_invitations / get_invitation / create_invitation / update_invitation / delete_invitation — Manage invitations
• resend_invitation — Resend an invitation email
• bulk_create_invitations — Create up to 100 invitations at once

Surveys

• list_surveys / get_survey / create_survey / update_survey / delete_survey — Manage surveys
• get_survey_submissions — Read survey responses

Plans & Enrollments

• list_plans / get_plan / create_plan / update_plan / delete_plan — Manage plans
• list_enrollments / get_enrollment — Read enrollments
• list_payments / get_payment — Read payment history

Coupons

• list_coupons / get_coupon / create_coupon / update_coupon / delete_coupon — Manage discount codes

Broadcasts

• list_broadcasts / get_broadcast / create_broadcast / update_broadcast / delete_broadcast — Manage broadcasts
• send_broadcast — Send a broadcast to space members
• get_broadcast_delivery_status — Check delivery progress

Available Resources

• sutra://admin-api/overview — Core Admin API concepts, public ID prefixes, scopes, pagination, and filtering
• sutra://admin-api/membership-spaces — Difference between admin-manageable spaces and limited membership-space inventory
• sutra://admin-api/contacts-properties — Contact listing and member/contact property value workflows
• sutra://admin-api/people-filtering — Member and contact search, email, state, role, and custom property filtering

API Concepts

Spaces are the core building block — they can be courses, communities, forums, or any structured container. Spaces form hierarchies through parent-child relationships.

Membership spaces are spaces where the API token owner is enrolled as a member. Use list_membership_spaces for basic read-only inventory. Use list_spaces for spaces where the token has admin access; membership-only spaces may still return 404 or 403 from admin subresource tools.

Members belong to spaces. They have roles (member, editor, moderator) and can have custom properties attached.

Contacts are CRM people in a space who are not enrolled members. Contacts use the same member property definitions as members, so AI agents can tag imported contacts before they join.

Content blocks are structured content created by facilitators. Messages are discussion posts from participants. Reflections are threaded replies to messages.

All IDs use readable prefixes: sp_ (space), mem_ (member), contact_ (contact), usr_ (user), blk_ (block/message), reply_ (reflection), surv_ (survey), plan_ (plan), enr_ (enrollment), pay_ (payment), cpn_ (coupon), bcst_ (broadcast), inv_ (invitation), mprop_ / sprop_ (property definitions).

Pagination is cursor-based. List endpoints return { data, pagination: { next_cursor, has_more } }. Pass cursor to get the next page.

Filtering & Search — most list endpoints accept optional query parameters to narrow results:

• q — case-insensitive text search (spaces by name, members/contacts by name/email when scoped, surveys/broadcasts/plans by title/name, coupons by code)
• state / status — exact-match enum filters (e.g. state=active for spaces, status=sent for broadcasts)
• role — filter members or invitations by role
• type / privacy / frequency — filter by type, privacy level, or billing frequency
• user_id — filter messages or payments by author/user
• email — filter members, contacts, or invitations by email (requires members.email:read scope)
• property_key / property_value — filter members or contacts by one custom member property (requires member_properties:read scope)
• property_filters — filter members or contacts by multiple custom member properties

Scopes control what the API token can access. Tokens have read/write scope pairs like spaces:read, members:write, etc. membership_spaces:read is required for read-only membership-space inventory. Operations that exceed the token's scopes will return 403.

Architecture

AI Agent → MCP Protocol (stdio) → sutra-mcp → Sutra Admin API → Sutra Platform

The server is a thin, stateless wrapper. All data flows through the Sutra Admin API with Bearer token authentication. No data is cached or stored locally.