CKEditor AI On-Premises – MCP support

The On-Premises version of the CKEditor AI provides basic functionality for connecting to MCP servers using the Streamable HTTP transport.

To integrate an external MCP server, you need to supply the appropriate configuration for the MCP client.

{
    "mcp_servers": {
        "<MCP SERVER NAME>": {
            "url": "<MCP SERVER URL>"
        }
    }
}

docker run --init -p 8000:8000 \
    # ... other environment variables ...
    -e MCP_SERVERS='{"<MCP SERVER NAME>":{"url":"<MCP SERVER URL>"}}' \
    docker.cke-cs.com/ai-service:[version]

export MCP_SERVERS='{
    "<MCP SERVER NAME>": {
        "url": "<MCP SERVER URL>"
    }
}'

docker run --init -p 8000:8000 \
    # ... other environment variables ...
    -e MCP_SERVERS="$MCP_SERVERS" \
    docker.cke-cs.com/ai-service:[version]

The configuration also supports specifying additional HTTP headers (e.g., an authorization token) that will be included with each request sent to the MCP server:

{
    "mcp_servers": {
        "<MCP SERVER NAME>": {
            "url": "<MCP SERVER URL>",
            "headers": {
                "Authorization": "Bearer QUkgc2VydmljZUFJIHNlcnZpY2VBSSBzZXJ2aWNlQUkgc2VydmljZQ==",
                "<HEADER NAME>": "<HEADER VALUE>"
            }
        }
    }
}

MCP_SERVERS='{"<MCP SERVER NAME>":{"url":"<MCP SERVER URL>","headers":{"Authorization":"Bearer QUkgc2VydmljZUFJIHNlcnZpY2VBSSBzZXJ2aWNlQUkgc2VydmljZQ==","<HEADER NAME>":"<HEADER VALUE>"}}}'

For some MCP servers, you may want to disable specific tools to prevent the LLM from making harmful or dangerous actions. You can do this by providing the names of the tools to disable in the tools.disabled array.

{
    "mcp_servers": {
        "<MCP SERVER NAME>": {
            "url": "<MCP SERVER URL>",
            "headers": {
                "Authorization": "Bearer QUkgc2VydmljZUFJIHNlcnZpY2VBSSBzZXJ2aWNlQUkgc2VydmljZQ==",
                "<HEADER NAME>": "<HEADER VALUE>"
            },
            "tools": {
                "disabled": ["<NAME OF THE TOOL TO DISABLE>"]
            }
        }
    }
}

MCP_SERVERS='{"<MCP SERVER NAME>":{"url":"<MCP SERVER URL>","headers":{"Authorization":"Bearer ...","<HEADER NAME>":"<HEADER VALUE>"},"tools":{"disabled":["<NAME OF THE TOOL TO DISABLE>"]}}}'

You can also configure additional options for the MCP client by providing them in the options object. Currently we support the following options:

• callToolTimeout (optional, default: 60 seconds) – the timeout for the MCP tool call in seconds.

{
    "mcp_servers": {
        "<MCP SERVER NAME>": {
            "url": "<MCP SERVER URL>",
            "options": {
               "callToolTimeout": 300
            }
        }
    }
}

MCP_SERVERS='{"<MCP SERVER NAME>":{"url":"<MCP SERVER URL>","options":{"callToolTimeout":300}}}'

For MCP servers that require OAuth 2.0 authorization instead of a static access token in the Authorization header, you can configure CKEditor AI to act as an OAuth client. The service implements the OAuth 2.0 Authorization Code flow with PKCE and supports Dynamic Client Registration (RFC 7591) for servers that allow it.

End users authorize the connection through their browser. Each user authorizes independently, and the resulting access token is reused on their subsequent requests. CKEditor AI refreshes the access token automatically when it expires.

Enabling OAuth for an MCP server requires two configuration changes:

1. A top-level mcp_oauth_callback_url – the URL of the OAuth callback page hosted by your integrating web application. CKEditor AI uses this URL as the OAuth redirect_uri parameter for all OAuth-enabled MCP servers (unless overridden per server).
2. An oauth block inside the entry under mcp_servers.<MCP SERVER NAME>.

{
    "mcp_oauth_callback_url": "https://your-app.example.com/oauth/callback",
    "mcp_servers": {
        "<MCP SERVER NAME>": {
            "url": "<MCP SERVER URL>",
            "oauth": {
                "clientId": "<OAUTH CLIENT ID>",
                "clientSecret": "<OAUTH CLIENT SECRET>",
                "scopes": ["<OAUTH SCOPE>"]
            }
        }
    }
}

MCP_SERVERS='{"<MCP SERVER NAME>":{"url":"<MCP SERVER URL>","oauth":{"clientId":"<OAUTH CLIENT ID>","clientSecret":"<OAUTH CLIENT SECRET>","scopes":["<OAUTH SCOPE>"]}}}'

All fields inside oauth are optional:

• clientId – OAuth 2.0 client identifier issued by the MCP server. Omit to perform Dynamic Client Registration.
• clientSecret – OAuth 2.0 client secret. Used together with clientId for confidential clients.
• scopes – an array of OAuth scopes to request from the authorization server. Omit to use default server scopes.
• callbackUrl – per-server override of the top-level mcp_oauth_callback_url. Useful when different MCP servers must redirect to different pages in your web application.

If the MCP server supports RFC 7591 Dynamic Client Registration, you can omit clientId and clientSecret from the oauth block. CKEditor AI will register itself with the MCP server automatically on the first authorization attempt and reuse the resulting registration for later flows.

The OAuth flow is driven by your integrating web application. The AI service exposes the REST endpoints listed below; your application is responsible for orchestrating the redirects and forwarding the authorization code.

1. Initialize. Your application calls POST /v1/mcp/oauth/{serverName}/initialize for the signed-in user. The response contains either:
   • { "connected": true } – the user already has a valid access token; nothing more to do.
   • { "connected": false, "authorizationUrl": "..." } – redirect the user’s browser to authorizationUrl.
2. User consents. The MCP server’s authorization page opens in the user’s browser. After the user approves the request, the server redirects back to the URL configured as mcp_oauth_callback_url (or oauth.callbackUrl) with code and state query parameters appended.
3. Complete. Your callback page extracts code and state from the query string and forwards them to POST /v1/mcp/oauth/{serverName}/complete with body { "code": "...", "state": "..." }. On success the user’s connection becomes active and subsequent AI conversations for that user can use the MCP server’s tools.

CKEditor AI does not host the callback page itself. You must register mcp_oauth_callback_url (or each per-server oauth.callbackUrl) as an authorized redirect URI with the MCP server – either through the server’s developer console or, with Dynamic Client Registration, automatically.

All endpoints below are authenticated with the same token used for other AI service endpoints. The acting user is identified by the token; each user has their own connection state per MCP server.

These endpoints are available once OAuth is configured for at least one MCP server.

OAuth connections are established per user and do not carry over between users or environments.

To revoke the calling user’s connection, send DELETE /v1/mcp/oauth/{serverName}.

Once the MCP client is configured, it will automatically establish a connection to the MCP server and retrieve the list of available tools. These tools will then be accessible to AI models during conversations (not in reviews or quick actions), enabling them to determine when and how to use them as needed.

For OAuth-enabled MCP servers, the connection is established only after each user completes the authorization flow; until then, the server’s tools are not exposed to that user.