Connecting external AI tools

Brightspot can expose an organization's content to external AI tools—chat assistants, IDE assistants, custom agents—so people can search, read, and even create or edit content from the tools they already use, without getting a separate login or a copy of the content. This works over the Model Context Protocol (MCP), an open standard that lets AI tools call a defined set of actions ("tools") against a system, the same way Ask Esca and Create with Esca already do inside the CMS.

Every action a connected tool takes runs under Brightspot's normal permission model. A request is always tied to a specific person or a dedicated service account, and it can only see or change what that person or account is allowed to see or change in the CMS. Connecting an AI tool does not open a new door into the content—it puts a controlled door where the administrator decides who holds the key.

note

This page covers what connecting an AI tool means and how to set it up as a CMS administrator. For the technical reference—implementation details, custom tool development, and the API-key/OAuth protocols—see MCP.

What you can connect

Any MCP-compatible client can connect once an endpoint is set up, including:

• IDE assistants (for example, a developer's coding assistant that also needs to look up CMS content).
• Chat apps and hosted AI assistants.
• Custom agents an organization or a partner builds.

A connected tool can search and read content, and—if the connecting user or service account has permission—create, update, and delete it too. It cannot do anything the connecting user or account could not already do by signing in to the CMS directly.

How access and permissions work

Every request from a connected tool runs as a specific user, the same way every action in the CMS does:

• A signed-in person—when someone connects a tool using their own Brightspot sign-in, the tool acts with that person's roles and permissions. If they cannot publish articles in the CMS, the tool cannot either.
• A service account—when a tool connects using a shared credential instead of a personal sign-in, it acts as whichever dedicated CMS user an administrator assigns to that credential. Scope this account narrowly (see Limiting what a connected tool can do).

Sites and content types the connecting user or service account cannot access are invisible to the tool—it is not just blocked from editing them, it does not know they exist.

Setting up access

Access is configured the same way as any other Brightspot API integration: by creating an API endpoint.

To connect an AI tool:

1. From the left navigation, under Admin, click APIs.
2. Create a new API endpoint and select Custom API as the type.
3. In the Paths field, add one or more URL paths to serve requests at (for example, /mcp).
4. Add one or more Authenticators, depending on how the tools connecting to this endpoint sign in (see the following sections). An endpoint with no authenticators rejects every request.
5. From the Handler list, select MCP.
6. Click Save.

The endpoint is now reachable at the configured paths. Share the full URL, including scheme and host, with whoever is configuring the connecting tool.

Letting people connect with their own sign-in

Add the OAuth authenticator to let people connect a tool using their own Brightspot sign-in—the recommended option whenever an individual person, rather than an automated integration, is the one using the tool. The tool prompts them to sign in and approve access the first time they connect, the same way approving a third-party app on a personal account works. From then on, the tool acts with that person's own permissions and every action is attributed to them.

note

OAuth requires the cms-oauth-server module to be installed. Confirm with your development team that it is available before selecting this option.

Connecting an automated tool with a shared credential

Add the API Key authenticator for tools that connect on their own—automated integrations without a person actively signing in each time. This requires setting up a dedicated service account for the tool to act as.

To connect an automated tool with a shared credential:

1. From the left navigation, under Admin, click APIs.
2. Create or open an API Client.
3. Generate a token for the client and grant it access to the MCP endpoint.
4. Set the Service User field to the dedicated CMS user this client should act as (see Limiting what a connected tool can do).
5. Click Save.
6. Share the token with whoever is configuring the connecting tool. Treat it like a password—anyone with the token can act as the service user.

Limiting what a connected tool can do

Before connecting a tool with a shared credential, create a CMS user and role specifically for it, with only the sites and content types it actually needs.

To create a scoped role for a connected tool:

1. From the left navigation, under Admin, click Users & Roles.
2. In the Roles widget, click Add Item and create a new role.
3. Grant only the sites, content types, and actions (for example, Publish) the connected tool needs.
4. Click Save.
5. Create a CMS user assigned to this role, and set it as the Service User on the API client (see Setting up access).

tip

Do not point a connecting tool at an existing administrator account, even temporarily. A tool inherits everything its assigned user can do, so a narrowly scoped user limits the damage a compromised credential or a misbehaving tool can cause.

Each API client can have its own service user, so different tools can run with different levels of access and show up separately in Version History and the AI Audit log.

Content created or edited through a connected tool

Content created or changed by a connected tool goes through the same publishing rules as content created in the CMS UI:

• If the content type is governed by a workflow, the change is saved as a draft in the workflow's starting state and moves through the same stages as anything else in that workflow—a connected tool does not bypass the configured workflow unless its user specifically holds the Publish permission for that type.
• Every change is attributed to the connecting person or service user, so Version History shows who—or what—made it.

Fields written by a connected tool are also flagged as AI-generated, the same tracking Create with Esca uses. Search using the Contains AI? filter, or add the AI Fields column to a search result list, to see what came from an AI tool versus a person. See AI Audit for organization-wide usage tracking.

Turning off access

To stop a tool from connecting:

Remove or disable its authenticator on the API endpoint, or delete the API client it was using.

To limit what an already-connected tool can do going forward:

Edit the permissions on its service user's role—the change applies to every subsequent request.