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:// /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 lasts until revoked. 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.

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

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

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 / , 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, cancel_workflow. Starting needs write; rebuild_deploy publishes and needs admin. Approve a review gate only with the user's consent. Runs continue from their saved progress after a service restart; one that cannot be resumed is reported failed with failure_code `workflow_interrupted