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.

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.
• 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.

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).

   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. | | 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. 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), update_site (name/slug/domain), list_versions, read_site_settings, update_site_settings.
• Pages — list, read, batch-read, create, update (PATCH), replace (PUT), batch-update, delete, clone, get-preview, set_page_mode (flip between blocks/html), convert_page_to_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, update, replace, delete, set_partial_mode, find-pages-using-block. 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 honoured only when the site has enabled "Allow AI to write block scripts" (a human-set portal setting) — otherwise it's stripped with a warning.
• 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, 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. Admins configure email and allowlisted, signed webhooks in the portal; action configuration stays off agent surfaces.
• 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.
• 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.
• 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. Branch deploys get their own URL at {branch}.{project}.pages.dev.
• 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.

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.
• 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 and the response carries a notice naming the stored JS. Only the in-portal chat assistant is additionally gated, on a per-site opt-in.
• 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. 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.