Connect your AI agent

Typeroll CMS exposes the same site-management tools through hosted MCP and a local MCP process. Use an AI agent that supports one of these transports, or integrate directly with the REST API. The visual editor also works without an agent. See Client compatibility for connection options and recorded test status.

For copy-paste setup in Claude, Claude Code, Cursor, VS Code, Codex and ChatGPT, see Connect your agent, client by client.

For project files and a smaller initial tool catalog, see Agent workspace. MCP 0.45.23 / Core 0.2.27 add optional compact discovery; existing connections keep their full catalog. Load relevant documentation sections and recipes on demand.

Let your agent read the documentation

Give your agent the documentation index. It links to a plain-text version of each page, the complete documentation, and a shorter set. All files are generated from these same docs. They include absolute links and source addresses, preserve code examples and can be fetched without JavaScript, a login or an API key.

Reading documentation is public. Managing your actual Sites through MCP or the API still requires the scoped credentials described below.

Choose credentials

In the portal, open the menu, choose the correct Organization, then go to Account → API keys. Create an organization key when the agent needs to manage multiple accessible sites or organization publishing settings. Only organization owners and admins can create, list and revoke organization keys.

For a single site, open that Site’s Settings → API keys under External access. Site keys stay within that site’s permission scope. Domain changes require site admin access; organization connections require an organization key.

Copy the key when it is shown and store it in your agent’s private credential settings. Do not commit a real key to a repository. Revoke it from the same page when you no longer want it to grant access.

An agent can list and revoke keys through MCP or the API with the same permissions: a site key manages keys for its own Site only, and only an organization key manages organization keys. See Organization, access and workflow tools.

Hosted MCP: connect with a URL

Use this option if your client supports MCP Streamable HTTP with OAuth. No local Node.js installation is required.

1. Add a remote MCP server in your agent client’s integration settings.
2. Enter https://app.typeroll.com/api/mcp for Typeroll Cloud, or https://<your-portal-host>/api/mcp for a self-hosted portal.
3. Sign in to Typeroll and select Allow access. From Core 0.2.78, all roles connect personally, with access to the same sites and permissions as in the portal. No API key needs to be copied.
4. Return to the client, tell it which site to work on, and confirm the organization, site and version before it calls select_site.

Each site tool carries the returned site_context. Search stays inside that site; switching sites or versions requires a new selection. Personal connections start in compact mode to keep the initial context small. Manual key connections keep their previous tool mode and scope.

Revoke personal connections in Account → AI connections. Connections expire after 30 days. Older OAuth grants remain in API keys until revoked or expired; reconnect to use personal access. See Personal AI connections for editor workflows, skills, site guidance and self-hosted setup.

Core 0.2.77 introduced signed-in consent for organization administrators; Core 0.2.78 / MCP 0.45.60 introduce the personal flow. Cloud requires the matching portal deployment. Updating the local stdio package alone does not update a hosted portal.

For a client that supports explicit bearer headers instead of OAuth, configure Authorization: Bearer <your-api-key> in its private connection settings. Never put the key in the server URL.

Local MCP process: stdio

Use this option if your agent can launch a local process and communicate over stdin/stdout. Install the Node.js version required by the current @typeroll/mcp-server package (Node.js 20 or later for the current standalone MCP package).

Configure these values in the client:

Setting	Value
Command	npx
Arguments	-y, @typeroll/mcp-server
Environment: TYPEROLL_API_URL	https://app.typeroll.com, or your portal origin
Environment: TYPEROLL_API_KEY	Your private API key

A stdio process targets one Site. If the key can access several Sites, set TYPEROLL_SITE_ID to the intended Site ID; a site-scoped key can discover its one Site automatically. Personal hosted connections explicitly select a context, then carry it per call.

A JSON-style client configuration can look like this. The exact configuration file and schema depend on the client; the placeholder is not a working key.

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

Use the client’s credential store or environment injection if available. Reload or restart its MCP connection after changing the configuration. Avoid duplicate Typeroll entries in different configuration scopes.

Verify the connection

Ask your agent:

List the Typeroll sites available to this connection. Do not change anything.

A hosted multi-site connection can call list_sites. A stdio connection should read its bound Site with get_site. Confirm the Site and Version before asking for edits.

Edits normally create working copies. Ask the agent to show the changes, save approved content and publish only when requested. See Drafts and saving and Deploy tools.

Optional workflow recipes

The MCP package includes Markdown recipes for tasks such as creating a site, importing content and checking SEO. Install them into a local directory:

npx @typeroll/mcp-server install-skills ./typeroll-skills

Point your agent at the relevant recipe, or adapt its installation to your client’s instructions. A directory name alone does not make every client load these files automatically. The MCP connection itself does not require recipes.

Existing files are skipped by default. --force replaces them with the bundled versions, so keep your own instructions separately if you want to preserve them. See Skills and recipes.

REST API without MCP

An agent or script can call the bearer-authenticated API under /api/v1 directly. Use an API key in the Authorization header. Choose organization or site scope for the intended operation; an AI agent with its own DNS-provider access can apply returned DNS requirements and ask Typeroll to verify the result. See Publishing with your own accounts.

Troubleshooting

Result	What to check
Missing bearer token	The key is missing from the connection headers or local process environment.
Invalid or revoked token	Use a current key from the same portal environment. Staging and production keys are separate.
Site not found	HTTP 404 site_not_found: the key works, but this Site is not in its Organization (details.organization_id) or shared with it. Call list_sites; do not switch keys.
Write permission required	A read-only share or key cannot edit or deploy. Ask the site owner to grant the needed access.
Organization key required	Site-scoped keys cannot change organization connections or domains.
No tools shown	Confirm the transport and authentication support, then reload the client’s MCP connection.
Local process exits	Verify Node.js, npx, the package installation and the two required environment variables.

A hosted client must be able to reach your portal over HTTPS. For local self-hosting development, use a client that can reach the local endpoint or use stdio. Do not assume a remotely hosted agent can reach your computer’s localhost.