# MCP tools

CKEditor AI can call tools on MCP (Model Context Protocol) servers you connect to an environment. Connect the systems your organization already uses, and CKEditor AI looks up current information in them or acts in them during a conversation. This page covers what connected tools do, where they apply, and how to register a server for an environment.

> **Note**
>
> This page covers the **tools** a connected MCP server exposes. A server’s **resources** can be read into a context as files instead. See [Load files from an MCP server](context-library.md#load-files-from-an-mcp-server).

<a id="when-to-use-it">

## When to use it

* **Draft from current customer data:** a sales manager asks for an account review. With the Salesforce MCP server connected, CKEditor AI looks up the account, its open opportunities, and recent cases, and drafts the summary from them.
* **Create a Jira issue from the document:** a product manager spots a missing requirement and asks for an issue. With the Atlassian MCP server connected, CKEditor AI creates it with the document as context and returns a link.
* **Use decisions recorded in Slack:** a writer asks for the latest rollout decision to be reflected in the brief. With the Slack MCP server connected, CKEditor AI searches the workspace and edits the section from the discussion it finds.

Chat and [Document Processing](../document-processing.md) use the servers you register through the admin API. On-premises, they also use the servers defined in the service configuration. Actions and reviews do not use MCP tools. See [Usage](../../../onpremises/ckeditor-ai-onpremises/mcp-tools.md#usage).

For a live example, see the [CKEditor AI demo connected to Airtable](https://ckeditor.com/ckeditor-5/demo/ai/?userId=dljgfyvtimmpghqkub\&channelId=6f28nha81jbmpghqkub\&channelIdBalloon=0apvk1yr9iiimpghqkv7\&channelIdChat=8wtk45soitnmpghqkvs\&channelIdQuickActions=e8kzoisu43mpghqkw6\&channelIdReview=7jjhamjm7ycmpghqkwc\&channelIdTranslate=ahf8g9aky3mpghqkwj#ckeditor-ai-with-mcp).

<a id="set-it-up">

## Set it up

Administrators register servers for one environment through the admin REST API. No deployment step is needed. This method works on SaaS and on-premises, and the rest of this page describes it. An on-premises deployment can define servers in the service configuration instead. See [MCP tools](../../../onpremises/ckeditor-ai-onpremises/mcp-tools.md). A server connected either way behaves the same.

Each environment keeps its own servers, so you can try a server in staging before you register it in production.

The server must be reachable over HTTPS and use the Streamable HTTP transport. The public servers for platforms such as Notion and Slack meet both conditions.

To register a server, send its name, its HTTPS URL, and any headers it expects, such as an `Authorization` token:

```bash
curl -s -X POST "https://ai.cke-cs.com/v1/admin/mcp-servers" \
	-H "Authorization: Bearer $ADMIN_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{
		"name": "product-catalog",
		"url": "https://mcp.example.com/mcp",
		"headers": {
			"Authorization": "Bearer <TOKEN>"
		}
	}'
```

```json
{
	"name": "product-catalog"
}
```

The `name` identifies the server in later requests and prefixes the names of its tools. Use letters, digits, hyphens, and underscores, and keep it unique within the environment. Names of servers defined in the service configuration are reserved.

Two fields are optional. `disabledTools` lists the tools CKEditor AI must not call. `callToolTimeout` sets the timeout of one tool call, in seconds. The default is 60 seconds.

<a id="choose-how-it-authenticates">

### Choose how it authenticates

A server authenticates in one of two ways:

* **Shared header:** a token, usually a bearer token, that CKEditor AI sends with every request to the server. Use it when the server does not need to know which of your users is asking.
* **OAuth:** each user authorizes the connection with their own account. Use it when the server must act as the signed-in user.

The two are mutually exclusive. Send `headers` for a shared token or an `oauth` block for per-user sign-in. You cannot change the method after you register the server. To switch, delete the server and register it again.

<a id="register-an-oauth-server">

### Register an OAuth server

Replace `headers` with `oauth`:

```bash
curl -s -X POST "https://ai.cke-cs.com/v1/admin/mcp-servers" \
	-H "Authorization: Bearer $ADMIN_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{
		"name": "support-desk",
		"url": "https://mcp.example.com/mcp",
		"oauth": {
			"callbackUrl": "https://your-app.example.com/oauth/callback",
			"clientId": "<CLIENT ID>",
			"clientSecret": "<CLIENT SECRET>",
			"scopes": ["tickets:read", "tickets:write"]
		}
	}'
```

Only `callbackUrl` is required. It is the page in your application that receives the OAuth redirect. Your application completes the flow through the `/v1/mcp/oauth/` endpoints. See [Authorization flow](../../../onpremises/ckeditor-ai-onpremises/mcp-tools.md#authorization-flow). Omit `clientId` and `clientSecret` for servers that support [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591), and omit `scopes` to use the server’s defaults. Secrets are never returned when you read a server back.

Each user then signs in with their own account before the server’s tools are available to them:

* **Access is the user’s own:** the server applies that user’s permissions in the connected system.
* **Actions are attributed:** the connected system sees the user who asked.
* **Tools appear after sign-in:** a user sees the server’s tools only after that user authorizes the server. Other connected servers stay available to the user.

<a id="api-and-options">

## API and options

<a id="list-registered-servers">

### List registered servers

To list the servers of an environment:

```bash
curl -s "https://ai.cke-cs.com/v1/admin/mcp-servers" \
	-H "Authorization: Bearer $ADMIN_TOKEN"
```

```json
{
	"items": [
		{
			"name": "product-catalog",
			"url": "https://mcp.example.com/mcp",
			"createdAt": "2026-06-01T09:12:00.000Z",
			"updatedAt": "2026-06-01T09:12:00.000Z"
		}
	]
}
```

The response includes `oauth`, `disabledTools`, and `callToolTimeout` only when they are set on the server.

<a id="update-or-remove-a-server">

### Update or remove a server

> **Note**
>
> If you change a server’s URL or its OAuth settings, every user must authorize the server again. Deleting the server has the same effect.

An update replaces the whole definition. `url` is required. If you omit `disabledTools` or `callToolTimeout`, the update clears them. If you omit `headers` or `oauth`, the stored values stay, so you do not need to send secrets again. For example, to move a server and rotate its token:

```bash
curl -s -X PUT "https://ai.cke-cs.com/v1/admin/mcp-servers/product-catalog" \
	-H "Authorization: Bearer $ADMIN_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{
		"url": "https://mcp.example.com/mcp-updated",
		"headers": {
			"Authorization": "Bearer <NEW TOKEN>"
		}
	}'
```

To delete a server:

```bash
curl -s -X DELETE "https://ai.cke-cs.com/v1/admin/mcp-servers/product-catalog" \
	-H "Authorization: Bearer $ADMIN_TOKEN"
```

Tool calls arrive in the streamed reply as events of their own, alongside the text. The CKEditor AI plugin shows tool use in progress by default. If you build your own UI, read those events to show which tools ran. See [Streaming protocol](../streaming-protocol.md) for the events.

> **Warning**
>
> CKEditor AI calls tools without asking the user. Every tool a connected server exposes can run during a reply unless you disable it. Disable the tools that must not run unattended before you connect the server: `disabledTools` for a server registered through the admin API, `tools.disabled` for a server defined in the on-premises configuration.

<a id="next-steps">

## Next steps

* **[MCP tools](../../../onpremises/ckeditor-ai-onpremises/mcp-tools.md)** covers how to define servers in an on-premises deployment: tool filtering, environment allowlists, connection pooling, and the OAuth flow.
* **[Fetch data from your systems](../fetch-data-from-your-systems.md)** connects a study registry so that writers draft reports from current data.
* **[Permissions](../permissions.md)** describes the `ai:admin` scope you need to manage servers.
* **[MCP Server Admin API reference](https://ai.cke-cs.com/v1/docs#tag/MCP-Server-Admin)** lists the endpoints with request and response schemas and error codes.

---

Full index of the Cloud Services documentation: [llms.txt](../../../../llms.txt)