Skip to main content
Glama
Sign In
Ruddur MCP Server

Ruddur MCP Server

by chadsly
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Ruddur MCP Server

MCP server for the Ruddur creator API. The public marketplace uses the hosted Streamable HTTP endpoint and browser OAuth; a local stdio mode remains available for development.

Marketplace installation

The Codex and Claude plugin manifests connect to https://mcp.ruddur.com/mcp. Users do not create an environment file or paste an API token. On first use, the host discovers Ruddur's OAuth metadata, opens the Ruddur login/consent page, and stores the resulting scoped token.

The service operator must deploy the included Docker image and publish /mcp over HTTPS. See docs/PUBLIC_MCP_ARCHITECTURE.md.

Coaches can grant relationships.assign separately from relationships.read. With that write grant, ruddur_assign_heading takes the relationshipId from ruddur_list_coaching_clients and a creator-owned headingId from Heading search/list tools. The API derives the client from the active coaching relationship, copies the Heading and Waypoints through the same application workflow as the web UI, and returns the existing assignment on retry. Grant relationships.read as well to verify the assignment through the coaching roster and assigned-results tools. Existing read-only tokens cannot assign Headings; reconnect and approve the new grant to make the tool available.

ruddur_remove_heading_assignment uses that same assignment-write grant for a coach or other assigner to remove one of their assignments. It requires an active relationship, both IDs from the relationship roster, and confirm=true. Removal is idempotent and ends assignment-scoped result access. An untouched client copy is removed; a started copy and its saved work remain with the client.

Related MCP server: Discovery Engine MCP Server

Protocol compatibility

The HTTPS endpoint automatically supports both MCP eras:

  • MCP through 2025-11-25 uses the initialization-based SDK transport expected by current Codex and Claude clients.

  • MCP 2026-07-28 uses stateless per-request metadata, server/discover, required request headers, resultType, and cache metadata.

The endpoint detects the era from MCP-Protocol-Version and params._meta. Both handlers use the same scoped tool runtime and forward the OAuth-issued creator API token to the existing Ruddur backend APIs.

Container publishing

GitLab CI runs typechecking, tests, and compilation before Kaniko builds a linux/amd64 image. Every branch or tag publishes:

$CI_REGISTRY_IMAGE/app:$CI_COMMIT_SHORT_SHA

The default branch also publishes :latest; Git tags additionally publish an image with the same tag. GitLab's built-in CI_JOB_TOKEN authenticates the registry push, matching the other Ruddur service repositories.

Setup

cd ruddur-mcp
npm install
cp .env.stdio.example .env
npm run build

Set at least:

RUDDUR_API_BASE=https://ruddur.com
RUDDUR_CREATOR_API_TOKEN=your-token

RUDDUR_CREATOR_SCOPES is optional. When present, the server only advertises tools matching those scopes. When absent, it advertises all allowlisted creator tools and lets the Ruddur API enforce the token's actual scopes.

This token-based file is only for local stdio development. Hosted deployments use .env.example, which intentionally contains no creator token: each marketplace user's OAuth token arrives as the bearer credential on their MCP request.

Set RUDDUR_MCP_ALLOW_MUTATIONS=false to run read-only. Delete, restore, publish/status, and detach operations require confirm=true from the calling agent.

Local Codex development

For local stdio development, add this to ~/.codex/config.toml:

[mcp_servers.ruddur]
command = "npx"
args = ["-y", "git+https://gitlab.com/ruddur1/ruddur-mcp.git"]
env = { RUDDUR_MCP_ENV_FILE = "/absolute/path/to/your/.env" }

The referenced .env must define RUDDUR_CREATOR_API_TOKEN. The server defaults RUDDUR_API_BASE to https://ruddur.com.

Alternatively, for a locally cloned checkout:

Add this to ~/.codex/config.toml:

[mcp_servers.ruddur]
command = "node"
args = ["/absolute/path/to/ruddur-mcp/dist/index.js"]
env = { RUDDUR_MCP_ENV_FILE = "/absolute/path/to/ruddur-mcp/.env" }

Restart Codex after changing MCP configuration.

Local Claude Code development

For local stdio development:

claude mcp add-json ruddur '{
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "git+https://gitlab.com/ruddur1/ruddur-mcp.git"],
  "env": {
    "RUDDUR_MCP_ENV_FILE": "/absolute/path/to/your/.env"
  }
}'

Set RUDDUR_MCP_ALLOW_MUTATIONS=false for read-only use. Set RUDDUR_MCP_ALLOW_MUTATIONS=true when Claude should see create/update tools such as ruddur_create_heading and ruddur_create_waypoint.

Security

  • Use the narrowest creator-token scopes needed.

  • Keep .env out of source control.

  • The server never exposes a generic URL/path request tool.

  • Token management is excluded because Ruddur requires session authentication for issuing and revoking API tokens.

  • Only local stdio mode reads .env; the public remote server uses OAuth and never receives a user's local environment.

Development

npm run typecheck
npm test
npm run build

Available Tools

53 tools
ruddur_add_heading_collaboratorA

Add a collaborator to a Heading. The MCP server accepts collaborator aliases such as userId, collaboratorId, permission, access, and accessLevel. Requires scope: content.manage.

Inputs: pathParams (required), body, query.

ruddur_apply_heading_templateA

Create a Heading from a template. Requires scope: content.manage.

Inputs: pathParams (required), body, query.

ruddur_attach_media_assetA

Attach a media asset to Ruddur content. The MCP server accepts media aliases such as title/name, mimeType/contentType, size/fileSize, and heading/waypoint/listing identifiers. Requires scope: media.manage.

Inputs: pathParams (required), body, query.

ruddur_attach_waypointB

Attach a Waypoint to a Heading. The MCP server accepts placement aliases such as heading, index, state, and sortOrder. Requires scope: content.manage.

Inputs: pathParams (required), body, query.

ruddur_clone_headingA

Clone a creator-owned Heading. Requires scope: content.manage.

Inputs: pathParams (required), body, query.

ruddur_create_couponA

Create a marketplace coupon. The MCP server accepts coupon aliases such as promoCode, percentOff, amountOff, expires, usageLimit, and marketplaceListingId. Requires scope: marketplace.manage.

Inputs: body, query.

ruddur_create_headingA

Create or import a creator-owned Heading. Omit assessmentConfig for ordinary waypoints; include it only for explicit assessment-style waypoints. The MCP server maps creatorAssessmentConfig to assessmentConfig when provided. Requires scope: content.manage.

Inputs: body, query.

ruddur_create_heading_snapshotB

Create a named Heading snapshot. Requires scope: content.manage.

Inputs: pathParams (required), body, query.

ruddur_create_heading_templateA

Create a reusable template from a Heading. Requires scope: content.manage.

Inputs: pathParams (required), body, query.

ruddur_create_marketplace_listingA

Create a marketplace listing. The MCP server accepts natural marketplace payloads, including marketplace details, title/name aliases, comma-separated tags, lowercase status/currency, and top-level waypoints converted into a heading payload. Ordinary waypoints should not include assessmentConfig. Keep marketplace descriptions outcome-focused and buyer-facing. Do not add question-format, free-text, PII/data-handling, or generic educational/non-diagnostic boilerplate unless explicitly requested or specifically required; place necessary disclosures in a dedicated assessment introduction, help, or consent surface when available. Requires scope: marketplace.manage.

Inputs: body, query.

ruddur_create_media_transformB

Create or register a media transform. The MCP server accepts media aliases such as title/name, mimeType/contentType, size/fileSize, and heading/waypoint/listing identifiers. Requires scope: media.manage.

Inputs: pathParams (required), body, query.

ruddur_create_media_uploadA

Create a presigned creator-media upload. The MCP server accepts media aliases such as title/name, mimeType/contentType, size/fileSize, and heading/waypoint/listing identifiers. Requires scope: media.manage.

Inputs: body, query.

ruddur_create_waypointA

Create a creator-owned Waypoint. Omit assessmentConfig for ordinary waypoints; include it only for explicit assessment-style waypoints. The MCP server maps creatorAssessmentConfig to assessmentConfig when provided. Requires scope: content.manage.

Inputs: body, query.

ruddur_create_waypoint_noteA

Create a note on a Heading Waypoint. Requires scope: content.manage.

Inputs: pathParams (required), body, query.

ruddur_delete_headingA
DestructiveIdempotent

Delete a creator-owned Heading. Requires scope: content.manage.

Inputs: confirm (required), pathParams (required), body, query.

ruddur_delete_marketplace_listingA
DestructiveIdempotent

Delete a marketplace listing. Requires scope: marketplace.manage.

Inputs: confirm (required), pathParams (required), body, query.

ruddur_delete_media_assetA
DestructiveIdempotent

Delete a creator media asset. Requires scope: media.manage.

Inputs: confirm (required), pathParams (required), body, query.

ruddur_delete_waypointA
DestructiveIdempotent

Delete a creator-owned Waypoint. Requires scope: content.manage.

Inputs: confirm (required), pathParams (required), body, query.

ruddur_delete_waypoint_noteA
DestructiveIdempotent

Delete a Waypoint note. Requires scope: content.manage.

Inputs: confirm (required), pathParams (required), body, query.

ruddur_delete_waypoint_placementA
DestructiveIdempotent

Delete a Waypoint placement. Requires scope: content.manage.

Inputs: confirm (required), pathParams (required), body, query.

ruddur_detach_media_assetA

Detach a media asset from Ruddur content. The MCP server accepts media aliases such as title/name, mimeType/contentType, size/fileSize, and heading/waypoint/listing identifiers. Requires scope: media.manage.

Inputs: confirm (required), pathParams (required), body, query.

ruddur_export_headingA
Read-onlyIdempotent

Export a Heading as JSON. Requires scope: content.read.

Inputs: pathParams (required), body, query.

ruddur_get_creator_analyticsA
Read-onlyIdempotent

Get creator analytics summary. Requires scope: analytics.read.

Inputs: body, query.

ruddur_get_creator_billingB
Read-onlyIdempotent

Get creator billing summary. Requires scope: billing.read.

Inputs: body, query.

ruddur_get_creator_profileA
Read-onlyIdempotent

Get the authenticated creator profile. Requires one of scope: marketplace.read, marketplace.manage.

Inputs: body, query.

ruddur_get_headingA
Read-onlyIdempotent

Get a creator-owned Heading by id. Requires scope: content.read.

Inputs: pathParams (required), body, query.

ruddur_get_marketplace_licenseB
Read-onlyIdempotent

Get creator license details for a purchase. Requires one of scope: marketplace.entitlements, marketplace.manage.

Inputs: pathParams (required), body, query.

ruddur_import_headingsA

Import one or more Headings from JSON. Omit assessmentConfig for ordinary waypoints; include it only for explicit assessment-style waypoints. The MCP server maps creatorAssessmentConfig to assessmentConfig when provided. Requires scope: content.manage.

Inputs: body, query.

ruddur_list_couponsB
Read-onlyIdempotent

List creator marketplace coupons. Requires one of scope: marketplace.read, marketplace.manage.

Inputs: body, query.

ruddur_list_heading_collaboratorsA
Read-onlyIdempotent

List collaborators on a Heading. Requires scope: content.read.

Inputs: pathParams (required), body, query.

ruddur_list_headingsA
Read-onlyIdempotent

List creator-owned Headings. Requires scope: content.read.

Inputs: body, query.

ruddur_list_heading_snapshotsA
Read-onlyIdempotent

List snapshots for a Heading. Requires scope: content.read.

Inputs: pathParams (required), body, query.

ruddur_list_heading_templatesA
Read-onlyIdempotent

List creator Heading templates. Requires scope: content.read.

Inputs: body, query.

ruddur_list_media_assetsA
Read-onlyIdempotent

List creator media assets. Requires scope: media.read.

Inputs: body, query.

ruddur_list_my_marketplace_listingsB
Read-onlyIdempotent

List marketplace listings owned by the creator. Requires one of scope: marketplace.read, marketplace.manage.

Inputs: body, query.

ruddur_list_waypoint_notesA
Read-onlyIdempotent

List notes on a Heading Waypoint. Requires scope: content.read.

Inputs: pathParams (required), body, query.

ruddur_list_waypointsA
Read-onlyIdempotent

List creator-owned Waypoints. Requires scope: content.read.

Inputs: body, query.

ruddur_record_creator_eventA

Record a creator analytics event. The MCP server accepts event/type/name as aliases for eventType and timestamp/time/createdAt as aliases for occurredAt. Requires scope: events.write.

Inputs: idempotencyKey (required), body, query.

ruddur_remove_heading_collaboratorA
DestructiveIdempotent

Remove a Heading collaborator. Requires scope: content.manage.

Inputs: confirm (required), pathParams (required), body, query.

ruddur_restore_heading_snapshotA

Restore a Heading snapshot. Requires scope: content.manage.

Inputs: confirm (required), pathParams (required), body, query.

ruddur_search_headingsA
Read-onlyIdempotent

Search creator-owned Headings using query parameter q. Requires scope: content.read.

Inputs: body, query.

ruddur_update_couponA

Update a marketplace coupon. The MCP server accepts coupon aliases such as promoCode, percentOff, amountOff, expires, usageLimit, and marketplaceListingId. Requires scope: marketplace.manage.

Inputs: pathParams (required), body, query.

ruddur_update_creator_profileA

Create or update the authenticated creator profile. The MCP server accepts name, creatorName, or title as aliases for displayName. Requires scope: marketplace.manage.

Inputs: body, query.

ruddur_update_headingB
Idempotent

Update a Heading, cover asset, or canvas style. Requires scope: content.manage.

Inputs: pathParams (required), body, query.

ruddur_update_heading_collaboratorA
Idempotent

Update a Heading collaborator role. The MCP server accepts collaborator aliases such as userId, collaboratorId, permission, access, and accessLevel. Requires scope: content.manage.

Inputs: pathParams (required), body, query.

ruddur_update_heading_statusB

Update a Heading lifecycle status. Requires scope: content.manage.

Inputs: confirm (required), pathParams (required), body, query.

ruddur_update_heading_tagsA
Idempotent

Replace the tags on a Heading. Requires scope: content.manage.

Inputs: pathParams (required), body, query.

ruddur_update_marketplace_listingA
Idempotent

Update or publish a marketplace listing. The MCP server accepts natural marketplace payloads, including marketplace details, title/name aliases, comma-separated tags, lowercase status/currency, and top-level waypoints converted into a heading payload. Ordinary waypoints should not include assessmentConfig. Keep marketplace descriptions outcome-focused and buyer-facing. Do not add question-format, free-text, PII/data-handling, or generic educational/non-diagnostic boilerplate unless explicitly requested or specifically required; place necessary disclosures in a dedicated assessment introduction, help, or consent surface when available. Requires scope: marketplace.manage.

Inputs: confirm (required), pathParams (required), body, query.

ruddur_update_media_assetA

Update creator media metadata. The MCP server accepts media aliases such as title/name, mimeType/contentType, size/fileSize, and heading/waypoint/listing identifiers. Requires scope: media.manage.

Inputs: pathParams (required), body, query.

ruddur_update_waypointA
Idempotent

Update a creator-owned Waypoint. Omit assessmentConfig for ordinary waypoints; include it only for explicit assessment-style waypoints. The MCP server maps creatorAssessmentConfig to assessmentConfig when provided. Requires scope: content.manage.

Inputs: pathParams (required), body, query.

ruddur_update_waypoint_noteB
Idempotent

Update a Waypoint note. Requires scope: content.manage.

Inputs: pathParams (required), body, query.

ruddur_update_waypoint_placementA

Update a Waypoint placement. The MCP server accepts placement aliases such as heading, index, state, and sortOrder. Requires scope: content.manage.

Inputs: pathParams (required), body, query.

ruddur_verify_entitlementA
Read-only

Verify a user's entitlement to a creator listing. The MCP server accepts marketplaceListingId and customerUserId aliases. Requires one of scope: marketplace.entitlements, marketplace.manage.

Inputs: body, query.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.7/5.0

    Scored across 53 tools

    Disambiguation4/5

    Most tools have a clear resource+action mapping (headings, waypoints, media, marketplace). A few close pairs like attach_waypoint vs update_waypoint_placement and create/import/apply_template/clone for headings could cause confusion, but the descriptions help distinguish them.

    Naming Consistency5/5

    Every tool uses the consistent ruddur_verb_noun pattern with snake_case. The only minor deviation is list_my_marketplace_listings, which includes an extra 'my' but remains readable and predictable.

    Tool Count2/5

    53 tools is far beyond the typical 3-15 range and even exceeds the 25+ threshold. While the broad scope (content, media, marketplace, billing) explains the count, the sheer number makes the server heavy and likely overwhelming for agents.

    Completeness4/5

    The tool surface covers CRUD for most resources (headings, waypoints, media, marketplace listings) plus snapshots, templates, collaborators, notes, coupons, and entitlements. However, there are no direct getters for waypoints, media assets, or marketplace listings, and coupons lack a delete operation.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • Notion MCP Server

      hyunseok-ctrl
      -
      license
      Not graded
      quality
      Not graded
      maintenance
      An MCP server that enables natural language interaction with the Notion API, allowing users to search, comment, create pages, and access content within their Notion workspace.
      270,649 npm
      -

    • Discovery Engine MCP Server

      ag2-mcp-servers
      F
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables natural language interaction with Google's Discovery Engine API, allowing users to search, recommend, and manage data through conversational interfaces.
      -