MCP support

The Model Context Protocol (MCP) is an open standard for connecting AI models to external tools and data sources. CKEditor AI supports MCP, letting you extend its capabilities with custom tools – such as searching knowledge bases, querying databases, integrating with third-party services, or even providing your own custom AI tools – all accessible directly from the AI Chat.

When MCP servers are connected to the on-premises AI service, the AI model can use MCP tools during conversations. The general flow is:

1. The user sends a message in the AI Chat.
2. The AI model may decide to call an MCP tool based on the message and conversation context.
3. The on-premises AI service invokes the tool on the connected MCP server.
4. The tool result is returned to the AI service and may be used to improve the quality and accuracy of the response.
5. The tool result is also sent to the editor, where it can be processed and displayed.

You can connect both third-party MCP tools (such as public knowledge-base or database connectors) and your own custom tools. For third-party tools, the integration may be as simple as registering a callback to display their results. For custom tools, you have full control over what data the tool returns and how it is presented in the editor.

As an integrator, you can:

• Use MCP tools to return additional data for the main AI service agent, to make it aware of the knowledge specific to your application.
• Handle tool responses by registering callbacks that process tool notifications and results, to provide a customized rich user experience specific to your use cases.
• Pass context to MCP tools alongside user messages, to give your custom tools more input to operate on, beyond the user prompt.

MCP servers are configured on the on-premises AI service, not in the CKEditor 5 editor configuration. For server setup, connection options, and other details, refer to the on-premises MCP configuration guide.

When an MCP tool is called, progress notifications and the final result are passed to the editor. Use registerToolDataCallback() to process this data and control how it appears in the AI Chat.

const aiChat = editor.plugins.get( 'AIChat' );

aiChat.registerToolDataCallback( ( toolData, api ) => {
    // Handle tool data here.
} );

Each callback receives:

• toolData (AIToolData) – the tool name, event type, and data payload. The MCP tool is fully responsible for the contents of toolData.data.
• api (AIChatInteractionAPI) – methods for manipulating the chat feed.

Use toolData.type ('result' or 'notification') and toolData.toolName to route handling logic. Tool names are prefixed with the server name in the format {serverName}-{toolName} (for example, my-server-search-docs).

You can register multiple callbacks to handle different tools separately.

Tools may send notifications or progress updates, informing about the current state of the call, or sharing additional insight about what the tool does.

For these kinds of updates, toolData.type will be set to 'notification'.

You can use this data to show a custom loading message or even provide your own “chain-of-thought” component.

const aiChat = editor.plugins.get( 'AIChat' );

aiChat.registerToolDataCallback( ( toolData, api ) => {
    if ( toolData.type === 'notification' ) {
        api.setLoadingMessage( toolData.data.message );
    }
} );

Note that tool notifications are treated as temporary data and are not saved in the conversation history. They will not be shown when a conversation is loaded from the history.

Every tool is expected to return a result after it finishes processing.

Tool result data has toolData.type set to 'result'.

Tool results are displayed in the chat feed in the order they arrive. If a tool result comes before the AI’s proposed changes to the document, it will appear before them. If it arrives after, it will appear after. Tool results will never split the proposed changes.

Depending on your use case, you may simply show the result as text, or provide a custom, rich UI component that will display the returned data as a graph, table, or in any custom way that fits your needs.

Unlike the temporary updates from notifications, results are persistent data saved in the conversation history. The data is saved as-received. When a conversation is loaded from history, the same registered callbacks will be used to handle the saved tool data.

Use the provided API to insert the text result into the chat feed:

const aiChat = editor.plugins.get( 'AIChat' );

aiChat.registerToolDataCallback( ( toolData, api ) => {
    if ( toolData.type === 'result' ) {
        api.insertTextReply( toolData.data.summary );
    }
} );

When a tool returns structured data (for example, tabular data as JSON), you can build custom HTML and insert it into the chat feed:

const aiChat = editor.plugins.get( 'AIChat' );

aiChat.registerToolDataCallback( ( toolData, api ) => {
    if ( toolData.type === 'result' && toolData.data.rows ) {
        const headers = toolData.data.columns;
        const rows = toolData.data.rows;

        const headerHtml = headers.map( h => `<th>${ h }</th>` ).join( '' );
        const rowsHtml = rows.map( row =>
            '<tr>' + row.map( cell => `<td>${ cell }</td>` ).join( '' ) + '</tr>'
        ).join( '' );

        const tableHtml = `<table><thead><tr>${ headerHtml }</tr></thead><tbody>${ rowsHtml }</tbody></table>`;

        api.insertCustomElement( tableHtml );
    }
} );

MCP tools automatically receive the conversation context when a user sends a message. However, your application often holds additional information that can help the tool produce better results. You can attach this data to messages so that MCP tools can use it.

There are two approaches: message attributes and tool context items. The key difference is in how they are used:

• Message attributes are metadata that is always present with the message and typically invisible to the end user. They are set programmatically and intended for data that should accompany every message transparently – for example, the user’s tenant ID, department, or session information.
• Tool context items are reflected in the UI as context pills next to the prompt input (similar to attached files or URLs). They are visible to the user, who can interact with them – add, review, or remove them. Use them for data that the user should be aware of, such as a search category, a customer name, or a content tag.

Both attributes and context items are saved in the conversation history.

Use the attributes parameter of sendMessage() to attach metadata to a message. Attributes are forwarded to all connected MCP servers automatically.

const aiChat = editor.plugins.get( 'AIChat' );

await aiChat.sendMessage( {
    message: 'Find related documents about this project',
    attributes: {
        department: 'engineering',
        projectId: 'proj-123'
    }
} );

Use addToolItemToContext() to add context items that are displayed as pills in the chat UI and routed to a specific MCP server or tool. This is useful for scoping information like a search category, customer name, or content tag that the user should see and can interact with.

const aiChatController = editor.plugins.get( 'AIChatController' );
const conversation = aiChatController.activeConversation;

conversation.context.addToolItemToContext( {
    type: 'mcp-tool-context',
    mcpServerName: 'my-server',
    toolName: 'search-docs', // Optional. Omit to send context to all tools on the server.
    data: {
        category: 'compliance',
        region: 'EMEA'
    },
    id: 'search-scope-1' // Optional, 1-21 characters. Auto-generated if omitted.
} );

The following APIs are used when integrating MCP tools with the editor:

• AIChat#registerToolDataCallback() – registers a callback to handle data from MCP tools (results and notifications).
• AIChat#sendMessage() – sends a message programmatically, with optional attributes forwarded to MCP servers.
• AIChatContext#addToolItemToContext() – adds a context item targeted at a specific MCP server or tool.
• AIChatInteractionAPI – methods available inside tool data callbacks for manipulating the chat feed (insertTextReply, insertCustomElement, setLoadingMessage, clearLoadingMessage).
• AIToolData – the data object passed to tool data callbacks, containing toolName, type, data, and attributes.

• Deployment options – learn about Cloud and On-premises deployment modes.
• AI Chat – learn about the AI Chat feature.
• Integration guide – learn how to set up CKEditor AI in your application.
• On-premises documentation – server-side setup and configuration.
• REST API documentation – API reference for the AI service.