# Connect your AI agent

Source: [Connect your AI agent](https://typeroll.com/docs/getting-started/mcp-server/)

> Connect an MCP-compatible AI agent to Typeroll CMS through the hosted MCP endpoint or a local stdio process.

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](https://typeroll.com/docs/getting-started/client-compatibility/) for connection options and recorded test status.

## Let your agent read the documentation

[Section titled “Let your agent read the documentation”](https://typeroll.com/docs/getting-started/mcp-server/#let-your-agent-read-the-documentation)

Give your agent the [documentation index](https://typeroll.com/docs/llms.txt). It links to a plain-text version of each page, the [complete documentation](https://typeroll.com/docs/llms-full.txt), and a [shorter set](https://typeroll.com/docs/llms-small.txt). 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

[Section titled “Choose credentials”](https://typeroll.com/docs/getting-started/mcp-server/#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

[Section titled “Hosted MCP: connect with a URL”](https://typeroll.com/docs/getting-started/mcp-server/#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

[Section titled “Local MCP process: stdio”](https://typeroll.com/docs/getting-started/mcp-server/#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](https://www.npmjs.com/package/@typeroll/mcp-server) (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.

```json
{
  "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

[Section titled “Verify the connection”](https://typeroll.com/docs/getting-started/mcp-server/#verify-the-connection)

Ask your agent:

```text
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](https://typeroll.com/docs/tools/drafts-and-saving/) and [Deploy tools](https://typeroll.com/docs/tools/deploy/).

## Optional workflow recipes

[Section titled “Optional workflow recipes”](https://typeroll.com/docs/getting-started/mcp-server/#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:

```bash
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](https://typeroll.com/docs/skills/overview/).

## REST API without MCP

[Section titled “REST API without MCP”](https://typeroll.com/docs/getting-started/mcp-server/#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](https://typeroll.com/docs/guides/customer-publishing/#api-and-mcp).

## Troubleshooting

[Section titled “Troubleshooting”](https://typeroll.com/docs/getting-started/mcp-server/#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.