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.

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.

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.

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. Complete the Typeroll consent screen with the API key and select Grant access.
4. Return to the client and confirm that Typeroll’s tools are available.

Client menus and supported authentication methods vary. Use your client’s MCP instructions for adding a server. The hosted endpoint supports organization and site keys; the underlying key’s permissions continue to apply after consent. Revoking it also invalidates the issued authorization on subsequent checks.

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. Hosted multi-site connections select a Site 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	Call list_sites and confirm the selected site is accessible to this key.
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.