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.

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