# Set up the built-in AI assistant Source: [Set up the built-in AI assistant](https://typeroll.com/docs/guides/ai-assistant/) > Add your Organization's own Anthropic API key, choose which Sites may use the AI chat in the portal, and keep using your own AI agent everywhere. Typeroll CMS includes an AI assistant in the portal: the **AI Chat** on a Site. Editors describe a content change in the browser and the assistant makes it within their permissions. The assistant uses your Organization’s own Anthropic API key. There is no shared platform key, so usage is billed to the Organization’s Anthropic account. The assistant is off until an Organization owner or admin adds a key and chooses the Sites that may use it. This setting only controls the built-in chat. Everyone can still use their own AI agent, such as Claude Code, ChatGPT, Codex or another MCP client, on every Site they can reach. See [Work with your usual AI assistant](https://typeroll.com/docs/guides/ai-connections/) and [Connect your AI agent](https://typeroll.com/docs/getting-started/mcp-server/). **Availability:** this applies to Typeroll Cloud and self-hosted Typeroll CMS. Starting with the Core release that introduces organization AI keys, no Organization has the built-in assistant until an owner or admin adds a key. See [Cloud and self-hosting differences](https://typeroll.com/docs/guides/ai-assistant/#cloud-and-self-hosting) below. ## Add your Anthropic API key You need the owner or admin role in the Organization. Editors do not see the settings page. 1. Create an API key in the [Anthropic Console](https://console.anthropic.com/settings/keys). Anthropic is the only supported provider. 2. In Typeroll, open **Account → AI assistant** in the sidebar (`/app/settings/ai-assistant`). The **Account** page links to it as well. 3. Paste the key into **API key** and select **Verify and save key**. 4. Choose the Sites that may use the assistant, then select **Save site access**. A new key starts with no Sites selected. Typeroll checks the key with Anthropic before saving it. A key that Anthropic rejects is not saved. If Anthropic cannot be reached, nothing is saved either; try again later. Typeroll never stores an unverified key. The key is stored encrypted and is never shown again, returned by the API or written to logs. The page shows only its last four characters, when Anthropic verified it and who set it, and when. * **Replace a key:** paste a new key under **Replace with a new key**. The Site selection is kept. * **Remove a key:** select **Remove key**. The assistant is turned off on every Site and the Site selection is reset. ## Choose Sites | Choice | Effect | | -------------------------------------------- | ----------------------------------------------------------------------------------------- | | **All sites, including sites created later** | Every Site the Organization owns can use the assistant, including Sites you create later. | | **Only selected sites** | Only the checked Sites can use it. A new Site stays off until you select it. | The list contains the Organization’s own Sites. A Site shared into another Organization follows its **owner** Organization’s key and choice. Members of the other Organization see the assistant only when the owner Organization allows that Site, and the owner’s key is used and billed. ## What editors see On a Site with access, editors with write permission see **AI Chat** in the Site sidebar, an **AI chat** button on the Site overview, and the **AI** tab in the HTML page editor. Read-only viewers never get the chat. The chat acts with the person’s own permission: changing site settings such as the name, logo, brand colors, fonts and contact details, or block types, needs site admin permission, as in **Settings**. On a Site without access, these entries are hidden. Opening the chat page redirects to the Site overview. Nothing else changes: editors can still edit in the [visual editor](https://typeroll.com/docs/guides/the-editor/) and connect their own agent. AI changes use the normal [saving and review workflow](https://typeroll.com/docs/tools/drafts-and-saving/). A chat answer is not evidence that a change has been published. AI workflows use the same key and Site access: * **Site planning, content generation, content improvement and schema markup** fail on a Site without access, with “The AI assistant is not enabled for this site” and, through the API and MCP, `failure_code: "ai_not_enabled"`. * **Plan a new site with AI** (the New site page and `create_site_and_plan`) needs the key with **All sites, including sites created later**. Otherwise the button is disabled and the API answers `403 ai_not_enabled` without creating anything. You can create a blank Site, allow it and start site planning there. * **SEO audit** still runs and returns its per-page issue list without AI prioritization. The built-in assistant has no migration tools. Migrate a website with your own agent over MCP; see [WordPress migration](https://typeroll.com/docs/guides/wordpress-migration/). ### Without the built-in assistant Your own agent gets the same help over MCP. Its recipes cover the everyday requests the chat handles (page links, images, menus, site-wide changes as shared blocks, settings and analytics), the starter design reference and URL conventions. `add_faq_schema`, `add_recipe_schema` and `add_event_schema` are MCP tools with the same inputs and validation as the chat’s, so FAQ, recipe and event structured data needs no portal AI; see [Pages tools](https://typeroll.com/docs/tools/pages/#structured-data-tools). When an AI workflow fails with `ai_not_enabled`, the agent does the same work itself and says so; see [Workflows](https://typeroll.com/docs/tools/organization/#workflows). ## Manage the setting with the API or MCP The same settings are available to scripts and agents. Use an organization API key. A personal OAuth connection must select, with the `Typeroll-Organization` header, an Organization where the person is an owner or admin. A site-scoped API key receives `403`. | Action | MCP tool | API route below `/api/v1` | | -------------------- | --------------------------------- | ---------------------------------- | | Read status | `read_organization_ai_settings` | `GET /organization/ai` | | Add or replace a key | `set_organization_ai_key` | `PUT /organization/ai/key` | | Remove the key | `remove_organization_ai_key` | `DELETE /organization/ai/key` | | Choose Sites | `set_organization_ai_site_access` | `PUT /organization/ai/site-access` | `GET /organization/ai` returns the provider (`anthropic`), whether a key is `configured`, the masked `key` (`last4`, `verified_at`, `set_at`, `set_by`, `set_by_email`) or `null`, `site_access` (`mode` and `site_ids`), every Site of the Organization with `ai_enabled`, `encryption_available` and the portal’s `settings_path`. Every route returns the same summary with `Cache-Control: no-store`. ```json { "api_key": "sk-ant-..." } ``` ```json { "mode": "selected", "site_ids": ["site-id-1", "site-id-2"] } ``` Send `{ "mode": "all" }` to allow every Site, including future Sites. Caution Prefer entering the key in the portal. A key sent through an agent passes through that conversation and the client’s history. Typeroll never returns the key in responses, audit logs or error messages. ## Cloud and self-hosting | Topic | Typeroll Cloud | Self-hosting | | ----------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | Setup | An owner or admin adds the key in the portal. Existing Organizations must add their own key. | The same portal page. The server needs `INTEGRATIONS_SECRET_KEY` to store keys. | | Server key | None. Typeroll Cloud has no platform AI key. | None. `ANTHROPIC_API_KEY` is no longer read; the self-host check warns when an old environment sets it. | | AI endpoint | Anthropic | Anthropic, or a compatible endpoint set with the optional `ANTHROPIC_BASE_URL`. | See [self-hosting](https://typeroll.com/docs/guides/self-hosting/) for the server environment. ## Troubleshooting | Code | Status | Meaning and action | | ------------------------ | ------ | -------------------------------------------------------------------------------------------------------------------- | | `ai_not_enabled` | 403 | The Site has no AI access. An owner or admin adds a key and allows the Site. Your own agent can still work over MCP. | | `api_key_required` | 400 | No key was sent. Send `api_key`. | | `api_key_invalid_format` | 400 | The value is not an Anthropic API key. Copy the whole key; it starts with `sk-ant-`. | | `ai_key_rejected` | 422 | Anthropic rejected the key. Check that it is active in the Anthropic Console and copied in full. Nothing was saved. | | `ai_key_unverified` | 502 | Anthropic could not be reached to verify the key. Nothing was saved. Try again later. | | `encryption_unavailable` | 503 | The server cannot store secrets. A self-hosting operator configures `INTEGRATIONS_SECRET_KEY`. | | `ai_key_required` | 409 | Sites were chosen before a key exists. Add a key first. | | `unknown_site` | 400 | A Site id does not belong to this Organization. Shared Sites follow their owner Organization’s setting. | | `invalid_site_access` | 400 | `mode` must be `all` or `selected`, and `selected` needs a `site_ids` array. | `ai_not_enabled` is returned by the portal’s chat route (`POST /api/sites/{siteId}/chat`). MCP tools and the public API for content are never gated by this setting.