Typeroll CMS

Typeroll CMS MCP server

The @typeroll/mcp-server package connects MCP-compatible AI clients to the Typeroll CMS public API. Manage sites through tools to read and write pages, partials, content types, media, redirects, versions; trigger deploys; mint preview links.

The server is a thin transport adapter — tools call the Typeroll REST API, with a few workflow tools composing consecutive API calls such as config plus deploy. Auth happens at the API layer with a site- or org-scoped key; the MCP just carries the bearer through.

Website starter workspace

Run npx @typeroll/mcp-server@latest init ./my-site to generate a project folder for your own repository. It keeps owner rules in brief/rules.md, search strategy in brief/seo.md, a migration brief, task entry points under workflows/, decisions and QA. MCP 0.45.77 adds the rules/SEO/routines files. Use init ./my-site --update to add them to an existing workspace; edited files are preserved for manual review.

This is separate from the generated publication repository. The CMS owns current content and settings. Hosted MCP does not require a local workspace. Read the workspace guide and guided-start documentation. Kickoff prompts live only in the starter files: workflows/new-site.md and workflows/migration.md. workflows/interview.md guides missing decisions one question at a time and resumes from brief/interview.md. Migrations choose text and design/image preservation independently. Load task recipes on demand instead of copying the complete manual into context.

One Page model

Core 0.2.0 and MCP 0.45.0 use one content entity: Page. Every article, checklist, product, directory entry and ordinary page uses the same API, editor, blocks, history, preview and status. content_type selects a schema, URL pattern and default Page template. Custom values belong in fields; title, slug, path, body, SEO and status are built-in Page properties. Use page_ref/page_ref_list for references and a blank type route pattern for records without detail URLs.

Use create_page, list_pages content_type=... and the Content type/Page template tools. Use the Page ID and the same site version throughout editing, references, previews and builds. Existing installations must migrate before running this release. See the model guide and upgrade procedure.

Two ways to connect

• Remote MCP — enter a URL. Use a client with Streamable HTTP support and OAuth or bearer-header authentication. The Cloud endpoint is https://app.typeroll.com/api/mcp; self-hosted portals use https://<your-portal-host>/api/mcp. On Core 0.2.78+, sign in and approve personal access with any role. No API key copying is needed. Confirm a site and version, use select_site, and carry its site_context on site calls. Revoke access in Account → AI connections. Permissions are checked live; the connection expires after 30 days. Legacy OAuth grants remain scoped as before until reconnecting. Manual bearer keys remain supported.
• Local stdio — launch the npm package. Use a client that can run a local command with environment variables. Instructions below.

See client compatibility and verification status for Claude Desktop, Claude Code, Cursor, VS Code, ChatGPT, Cline and Zed. MCP support alone is not proof of a tested Typeroll integration.

This npm package is the stdio transport. The hosted endpoint ships as part of the Typeroll portal itself — same tool surface, same package under the hood.

Key scopes

• Org-scoped key (created at /app/settings/api-keys) — one credential covers every site in your org and every site shared into your org. Suitable for hosted multi-site connections. Stdio works too if you set TYPEROLL_SITE_ID so the install binds to one site.
• Site-scoped key (created at /app/sites/{siteId}/settings/api-keys) — tighter blast radius for a single-site credential, e.g. one you'd hand to a customer for a self-managed site.

Both look like typeroll_live_…; revoke either from the portal and any client using it stops working immediately. Keys can also be listed and revoked through MCP (list_api_keys, revoke_api_key, list_organization_api_keys, revoke_organization_api_key). New keys and other new credentials are created only in the portal, so a secret is shown once to the person creating it and never lands in an agent conversation or log.

Stdio quick start

1. Create an API key in your Typeroll portal — see the two scope options above. Org-scoped is the right default.

2. Add a local MCP server in your agent client. This example uses the mcpServers schema; adapt it to your client’s documented configuration:

   {
     "mcpServers": {
       "typeroll": {
         "command": "npx",
         "args": ["-y", "@typeroll/mcp-server"],
         "env": {
           "TYPEROLL_API_URL": "https://app.typeroll.com",
           "TYPEROLL_API_KEY": "typeroll_live_REPLACE_WITH_YOUR_KEY"
         }
       }
     }
   }
   

   For a self-hosted portal, point TYPEROLL_API_URL at it (e.g. https://cms.example.com). The stdio server and the typeroll extension CLI require HTTPS, except on loopback hosts.

   For an optional agent-neutral workspace, run npx @typeroll/mcp-server init ./my-site. It creates project instructions, briefs, decisions and QA files. Local client configuration is opt-in with --client claude|cursor|vscode; recipes are opt-in with --recipes. Use --update to upgrade unchanged generated files while preserving edits. See Agent workspace.

3. Tell the agent what kind of work you want. A good first message:

   "Connect to Typeroll and tell me what you find — site name, number of pages, what global blocks exist, what content types are defined. Then I'll give you a task."

   The agent can call get_site, get_site_capabilities, list_pages, list_partials, list_content_types, and list_block_types in sequence and report back. The capabilities + block palette are mandatory before it chooses HTML mode or reports a missing site-building feature.

Environment variables (stdio)

Var	Required	Description
TYPEROLL_API_URL	yes	Base URL of your Typeroll portal. Must use HTTPS; plain HTTP is accepted only for localhost, 127.0.0.1 or [::1].
TYPEROLL_API_KEY	yes	A typeroll_live_… bearer token.
TYPEROLL_SITE_ID	sometimes	Pin to a specific site. Required when the key can access multiple sites; each stdio process targets one site. A single accessible site is auto-detected.

Extension developer CLI

The package also installs typeroll. With an organization-scoped API key, an external Extension repository can use the same developer and installation APIs as the portal:

typeroll extension validate
typeroll extension push --draft
typeroll extension install --site test-site --config local-extension-config.json
typeroll extension configure --site test-site --installation install-abc \
  --config local-extension-config.json
typeroll extension promote 1.0.0

The manifest defaults to typeroll-extension.json; use --manifest to select another file. For a private Extension, install adds the site to the Extension's allowed_site_ids. A bare site id only matches a site of your own developer organization; to install on another organization's site, pass --site <organization-id>/<site-id>, which is written to the allow-list in that form. Local validation is a fast preflight. The portal always performs the complete schema, compatibility, origin and asset-hash validation. extension configure queues a production deploy by default; pass --no-deploy only when batching updates and deploy once afterwards.

What the agent should read first

The package ships AGENTS.md, a self-contained briefing that explains Typeroll conventions, common operations, and the safety boundaries an agent needs to respect. Point your agent at it or use the read_guide tool with sections_only: true, then request relevant sections. Follow the client’s own instructions for loading local recipes.

Tool surface

More than 100 tools across these families. See AGENTS.md for the full reference + concrete operation recipes.

• Skills + guide (self-describing playbook) — read_guide, list_skills, read_skill. The server advertises its own operating guide and bundled recipes at runtime without requiring local copies. read_guide supports a section index and individual sections; use the full manual only when the task needs it. list_skills then surfaces the task recipes (tr-new-site, tr-migrate-wp, tr-brand, tr-responsive, …); read_skill name=… loads one. All pure local reads — no API key or site context — so they work identically on the hosted connector and over stdio.
• Discovery — get_site, create_site (bootstrap a new site — org-scoped key only), create_site_and_migrate / create_site_and_plan (new site plus a WordPress migration or AI site plan — org-scoped key only), update_site (name/slug/domain/language, and ai_scripts_enabled for admins), list_versions, read_site_settings, update_site_settings (admin; every field the portal Settings form accepts, including default_og_image, twitter_handle, organization JSON-LD and staging_url).
• Site lifecycle — archive_site, restore_site and purge_site_media (media of an archived site; irreversible). Owner-organization admin, as in the portal.
• Access — list and revoke site API keys (list_api_keys, revoke_api_key; revoking needs site admin) and organization API keys (list_organization_api_keys, revoke_organization_api_key), cross-organization sharing (list_site_shares, share_site, update_site_share, revoke_site_share; site admin) and editor invite links (create_organization_invite, list_organization_invites, revoke_organization_invite; organization key). A share never reaches further than the caller. New API keys are created only in the portal, so the secret never passes through an agent conversation.
• Portal AI assistant — read_organization_ai_settings, set_organization_ai_key, remove_organization_ai_key and set_organization_ai_site_access: the Organization's own Anthropic key (verified, encrypted, never returned) and the Sites that show the built-in AI chat. Organization key, owner/admin. MCP itself never depends on it.
• Workflows — list_workflows, start_workflow (migration, site planning, SEO/link/performance audits, content generation and improvement, schema markup, URL parity, rebuild & deploy), get_workflow, approve_workflow. Starting needs write; rebuild_deploy publishes and needs admin. Approve a review gate only with the user's consent.
• Organization publishing connections — read_organization_publishing_connections (status, revisions and connect_urls for the browser-only OAuth steps), diagnose_organization_github_connection (why GitHub is not connected, every account with the App, and who must act with one fix each), diagnose_organization_cloudflare_connection (why a Hosting Group's Cloudflare connection is not working, who must act and one fix each, and which optional permissions for Analytics and redirect rules it is missing), disconnect_organization_publishing_provider, connect_organization_cloudflare (customer API token), prepare_organization_media_storage, save_organization_media_access. Organization key only.
• Pages — list, read, batch-read, create, update (PATCH), replace (PUT), batch-update, delete, clone, get-preview, set_page_mode (flip between blocks/html; HTML is never converted into blocks).
• Blocks (instances) — get_page_blocks, add_block, update_block, move_block, remove_block, duplicate_block, set_block_responsive. All take a target (page, partial, page template), so one tool family edits every block container.
• Global blocks (partials) — list (summary mode by default), read, create free block (blocks or HTML), update, replace, delete, set_partial_mode, find-pages-using-block, make_block_global, detach_global_block. Block pages reference one with core/global_block.
• Block templates — list_block_templates, read_block_template, save_block_template, update_block_template, delete_block_template, insert_block_template (inserts an independent copy).
• Styles — list_styles, create_style, update_style, delete_style, apply_standard_styles. New header/footer work should use the native template/site_logo + core/navigation recipe in tr-header-footer.
• Block types — list, read, create, update, delete, find-pages-using-block-type, plus .tcblocks export/import. Custom client-side JS (script) is accepted under your API key's authority and audit-logged, like the portal's block-type editor. The site's "Allow AI to write block scripts" setting (update_site ai_scripts_enabled) governs only the in-portal chat assistant, never API keys or MCP.
• Content types — list_content_types, read_content_type, create_content_type, update_content_type, delete_content_type. Every record is a Page; list_pages filters by content_type. change_page_content_type reclassifies a Page without changing its identity or existing URL. page_completeness reports missing and stale values.
• Page templates — list/read/create/update/delete reusable block layouts, including article/checklist starters. Set a default per content type or an override per Page. The body remains the Page's own editable block tree.
• Media — get_import_readiness, get_media_upload_status (the portal's upload pre-flight), list/read, signed upload URLs, upload_media_from_url, upload_media_batch_from_urls (1–50 sources, max 25 MiB each, with partial-success results), upload_media_inline, metadata updates and deletion. Imports require verified Organization storage. With Core 0.1.97, URL imports use the customer's Cloudflare transfer Worker; neither the portal nor MCP downloads the image body. For local files, create_upload_url grants a direct R2 PUT, followed by finalize_media to verify and freeze the original. Responsive variants are prepared separately by the Organization's selected build provider. Ordinary authored uploads may use draft storage before connection; import tools must not bypass readiness that way. Legacy maintenance includes finalize_all_media and generate_image_variants. suggest_alt_text_context returns a prompt for the agent's vision model. See the media API and tool guide.
• Rendering controls — semantic core/navigation, mapped core/post_card, core/table_of_contents, per-site trailing_slash, exact iframe_allowed_hosts, icon_192, and per-page append_seo_suffix=false. The block editor supports labelled enums, line-based lists, nested repeating arrays, responsive values in block data, and an internal-page URL picker.
• Redirects — list, create, delete. Plus automatic 301 on slug change.
• Forms — list, read, create, update, delete, list submissions. Place forms with core/form blocks or an HTML-mode <x-form id="…" /> reference; preview/build expands both server-side to the same complete, signed form shell. With an admin key, read_form returns the form's email notifications and allowlisted, signed webhooks (actions, secrets masked) and create_form/update_form set them, as the portal's Forms editor does.
• Extension installations — list/read installed Extensions and update manifest-defined installation config through the API key with update_extension_installation_config; omitted and masked secrets are preserved. Use this for frontend config such as consent copy and policy links. It queues a production deploy by default; pass deploy: false only when batching changes and deploy once afterwards. The same admin key also covers the rest of the portal's installation actions: install_extension, set_extension_installation_status (enable/disable), uninstall_extension, pair_extension_issuer, read_extension_diagnostics, and launch_extension_admin_page (a single-use launch grant to POST to the page's launch_url; approved native pages use call_extension_admin). Installation server credentials are rotated in the portal, so the new credential is never shown to an agent.
• Extension development — with an organization-scoped key: list_developer_extensions, read_developer_extension, update_developer_extension, save_extension_version, publish_extension_version, set_extension_version_lifecycle and list_developer_extension_installations — the same developer API as the typeroll extension CLI. Registering an Extension and rotating its client secret return a secret, so they stay in the portal and the CLI.
• Settings — read + patch, including shallow-merged cookie_consent, scripts_head / scripts_body_end / custom_css (trusted because the caller holds an API key; the in-portal chat AI does NOT get these).
• Core modules — list the legacy apps registry, read schema + masked state, and enable, configure, or disable any module with the same admin API key used for content and deploys. Secret fields are encrypted server-side and never returned; Analytics provisioning runs on the platform. Deploy after updates whose response has affects_build: true. list_organization_analytics and set_organization_analytics show and change Analytics for chosen Sites across the Organization (organization key).
• Search + link integrity — search_pages plus check_internal_links, which resolves saved database content against pages, Page/facet routes, media and redirect chains without crawling the public site.
• Bulk — bulk_replace_text with dry-run across pages, partials, block data and custom Page fields.
• Migration inventory — bulk add/update decisions, recursive import_sitemap, direct or CSV-fallback import_gsc_performance, and compact verify_migration_urls (successful rows omitted unless requested), plus repair_migration_plain_text for dry-run-first cleanup of legacy WordPress entities and markup in allowlisted plain-text fields.
• Branches — create, read, delete, merge, diff_version (what a branch adds, modifies and deletes relative to main) and reset_version (discard all of a branch's changes, keeping the branch). Creating, merging, deleting and resetting need site admin permission, as in the portal. A deployed branch gets its own stable address, reported as deploy_url by list_versions / read_version.
• Deploy — trigger (with dry_run to build without publishing), list, get status. A finished job reports cost: what the build consumed in server time, broken down per phase. Estimates from a rate card, not billing records.
• Preview — get_preview_link (signed URL for browser navigation; supports page_id, slug, or path; pass include_working_copy: true to also render unsaved drafts).
• Drafts (the buffer model) — every content write lands in a per-doc unsaved draft (working copy); deploys and plain previews see saved content only. Save explicitly with commit_working_copy or save: true on the write call; inspect/discard with read_working_copy / discard_working_copy. Status changes and structural operations apply immediately.
• History — list_page_revisions, read_page_revision and restore_page_revision (to a draft, or saved with save: true) undo page changes from earlier saves; preview_page_revision renders a saved state as the full preview document first. list_partial_revisions, read_partial_revision and restore_partial_revision do the same for the header, footer and global blocks.

Direct REST API access

If you don't want the MCP wrapper, the same surface is reachable directly with curl:

curl -H "Authorization: Bearer typeroll_live_..." \
  https://app.typeroll.com/api/v1/sites/<siteId>/pages

The MCP server is purely an ergonomics layer on top of that. The complete v1 contract, including payload envelopes and Page IDs and content-type routing, is documented in docs/v1-api.md.

Security model

• API keys are site-scoped or org-scoped (see "Key scopes" above) — enforced server-side. A site-scoped key cannot touch any other site; an org-scoped key reaches the org's own sites plus sites explicitly shared into the org, with the share's permission level applied.
• Managing keys, shares, invites, workflows and publishing connections uses the same permission checks as the portal. A key can never create a key or share that reaches further than itself; organization-level routes refuse site-scoped keys.
• All write calls (POST, PUT, PATCH, DELETE) are audit-logged with the key prefix, IP, method, path, and status. Reads are not logged (cost vs. value).
• Rate limits: 600 reads/min, 60 writes/min per key. 429 responses carry Retry-After headers.
• HTML sanitization happens at save time on the server — <script>, event handlers, and javascript: URLs are stripped from page/partial content (including core/html block output). The scriptable surfaces are deliberate exceptions, and all of them are writable with an API key under the key holder's own authority: scripts_* and custom_css on the site settings, script on a block type, and the js field of a core/embed block instance. Those writes are audit-logged like every API write. Only the in-portal chat assistant is additionally gated, on a per-site opt-in (ai_scripts_enabled) that site admins can set in the portal or with update_site.
• Same permissions as the portal. Each tool applies the role the corresponding portal action requires: settings, the AI-scripts toggle, apps, publishing and domains need admin; archiving, restoring and purging media need an admin of the organization that owns the site.
• Keys can be revoked at any time from the portal. Revocation takes effect on the next request (no in-flight requests get cancelled, but the next one returns 401).

More

• Full end-to-end production setup recipe with troubleshooting: docs/claude-code-mcp-setup.md
• Agent operations briefing: AGENTS.md
• Boilerplate skills (site building, brand, forms, SEO, blog, content types, migration, image generation, redesign, …): skills/

License

MIT — see LICENSE.

Use read_app_documentation to discover instructions for the selected site’s enabled modules and Extensions. Private app guides are fetched only for enabled installations using the provider’s authenticated documentation contract; they are not bundled in MCP. Generic discovery requires Core 0.2.8; protected guides require the app-separation release.

Agent workspace and compact discovery

MCP 0.45.23 introduces an agent-neutral typeroll init workspace, optional client adapters, safe hash-based init --update, and read-only typeroll doctor. Use workspace-mcp to bind local calls to typeroll.json; no credentials are stored there. Because typeroll.json is committed, its portal receives the API key only when it is https://app.typeroll.com or matches a privately set TYPEROLL_API_URL. Recipes are optional rather than automatically injected.

Compact mode exposes five discovery/execution tools instead of every schema. Choose ?tools=compact on the hosted endpoint (Core 0.2.27+), tool_mode in the workspace, or TYPEROLL_MCP_TOOL_MODE=compact for legacy stdio. Full mode remains available. Read/write/admin wrappers share normal validation and authorization.

See Agent workspace for the folder layout, commands, version requirements and context-budget advice.

Personal connections and packaged workflows

Personal OAuth defaults to compact discovery. Read tr-edit-site for the editing workflow and fetch site/App instructions live after selecting the site. The same flow works in Cloud and self-hosted Core. Plugin package instructions describe reproducible ChatGPT/Codex and Claude bundles; no catalog submission has been made.