Using the Model Context Protocol endpoint

Last updated
Save as PDF

Connect an MCP client to your site to search, get, and publish content with the client.

The NiCE Knowledge Management MCP Server connects your NiCE KM site to an AI client. The client must support the Model Context Protocol (MCP). Examples of MCP clients are Claude and Cursor.

After you connect an MCP client, the AI client can use tools to:

Search your knowledge base
Get page content and file content
Create and update draft pages
Publish draft pages

You do not have to write API code to do this integration.

Set up the MCP Server

There are 4 steps to set up the MCP Server:

Get an API key for the MCP Server
Connect an MCP client to your site
Find the tools that the MCP Server gives you
Set the correct permissions for the API key

If you want to build a custom integration without an MCP client, refer to Integrating with Generative AI Tools via the API.

Get an MCP API key

Each request through the NiCE KM MCP Server uses a NiCE KM user account. The permissions of this account control what the MCP client can see and do. This is the same permission model that the NiCE KM REST API uses.

The MCP Server does not use a separate, MCP-specific credential type. It authenticates with a Server API Token like the REST APIs use. More information is available in the Authorization Tokens documentation.

To get an API key:

Log in to your site as an administrator.
Append Special:Integrations/Tokens to your site URL.
Select Add Token.
Select the token type Server.
Enter a name for the token. For example mcp-client.
Select the Generate JWT checkbox.
In the account field, select the user account for this token.
Refer to Permissions and Security in this article.
Set the JWT expiration.
Select Add Token.
Copy the Authorization value that the system shows.

The authorization value is your MCP API key. The system shows this value only one time, so be sure to copy it when it is displayed.

Connect an MCP Client

Each site has its own MCP endpoint with the format:

https://<your-site>/@api/deki/mcp

Add the endpoint address and the API key to the configuration of your MCP client. Many MCP clients use a configuration file with the format:

{
  "mcpServers": {
    "expert": {
      "url": "https://<your-site>/@api/deki/mcp",
      "headers": {
        "Authorization": "Bearer <your-mcp-api-key>"
      }
    }
  }
}

Refer to the documentation of your MCP client. Find the correct location for this configuration, then restart the MCP client to connect it to your site.

After you connect the MCP client, it finds the tools in the next section. The MCP client can then use these tools during a conversation.

Standard configuration examples

These are verified configuration examples for common coding-agent CLI clients:

opencode

Add an mcp entry to your project or global opencode.json file, for example ~/.config/opencode/opencode.json. Use a remote server type and interpolate the API key from an environment variable. Do not hard-code the key in the file.

{
  "mcp": {
    "expert": {
      "type": "remote",
      "url": "https://<your-site>/@api/deki/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:EXPERT_MCP_TOKEN}"
      }
    }
  }
}

Export the API key as an environment variable before you start opencode, for example export EXPERT_MCP_TOKEN="<your-mcp-api-key>".

Claude Code

Use the claude mcp add command to register the MCP Server with an HTTP transport and an Authorization header:

claude mcp add --transport http expert https://<your-site>/@api/deki/mcp \
  --header "Authorization: Bearer <your-mcp-api-key>"

This command adds an equivalent entry to your .mcp.json file. If you edit the file directly, set type to http. An entry that has a url value but no type value is treated as a misconfigured local server, and Claude Code does not load it.

{
  "mcpServers": {
    "expert": {
      "type": "http",
      "url": "https://<your-site>/@api/deki/mcp",
      "headers": {
        "Authorization": "Bearer <your-mcp-api-key>"
      }
    }
  }
}

Codex

Add an entry under mcp_servers to ~/.codex/config.toml, or to a project-scoped .codex/config.toml. Codex reads the API key from an environment variable; it does not accept the key directly in this field.

[mcp_servers.expert]
url = "https://<your-site>/@api/deki/mcp"
bearer_token_env_var = "EXPERT_MCP_TOKEN"

Export the environment variable in your shell configuration before you start Codex, for example add this line to .zshrc or .bashrc: export EXPERT_MCP_TOKEN="<your-mcp-api-key>".

Pi, the pi coding agent CLI from earendil-works (pi.dev), does not have native MCP client support. Pi's own extension system is a separate TypeScript API, not the standard MCP protocol. To connect Pi to the MCP Server, install the community pi-mcp-adapter package:

pi install npm:pi-mcp-adapter

Then add the MCP Server to a project .mcp.json file or the user-global ~/.config/mcp/mcp.json file. Use bearerTokenEnv to reference an environment variable instead of the raw key:

{
  "mcpServers": {
    "expert": {
      "url": "https://<your-site>/@api/deki/mcp",
      "auth": "bearer",
      "bearerTokenEnv": "EXPERT_MCP_TOKEN"
    }
  }
}

Export the environment variable in your shell configuration, for example export EXPERT_MCP_TOKEN="<your-mcp-api-key>", then restart Pi. Refer to pi.dev/docs/latest for the current status of MCP support in Pi.

Connect ChatGPT

ChatGPT connects to the NiCE KM MCP Server as a custom connector. Unlike other MCP clients, ChatGPT does not use a single long-lived API key in a header; instead, it uses OAuth 2.0 to get a token for the account that you sign in with.

There are two steps to connect ChatGPT to the MCP Server; first you must create an OAuth client, then you create teh connector.

Create an OAuth client

To create the OAuth client for ChatGPT:

Log in to your site as an administrator.
Append Special:Integrations/Tokens to your site URL.
Select Add Token.
Select type OAuth.
Enter a name for the token. For example chatgpt-connector.
In the Host field, enter chatgpt.com.
This value must match the callback host ChatGPT uses, or the connection fails.
Select Add Token.
Copy the Key and Secret values that the system shows.
The system shows the values only one time, so be sure to copy it when it is displayed.

Create the connector

To create the connector, in ChatGPT:

Go to Settings > Plugins.
Select Create.
Enter a Name and Description for the connector.
In Connection, keep Server URL selected.
Enter the MCP endpoint address: https://<your-site>/@api/deki/mcp.
Set Authentication to OAuth.

Select Advanced OAuth settings, then set these values:

Field	Value
Registration method	User-Defined OAuth Client
OAuth Client ID	The Key value from your OAuth token
OAuth Client Secret	The Secret value from your OAuth token
Token endpoint auth method	`client_secret_basic`
Auth URL	`https://<your-site>/@app/auth/{id}/token/authorize`
Token URL	`https://<your-site>/@app/auth/{id}/token/access.json`
Base scopes	`profile, seated`

The {id} value in the Auth URL and Token URL is the ID of an identity provider service on your site. Use the REST API endpoint to find this ID: GET /@api/deki/site/services.

Use the id of the identity provider service that the people who use this connector sign in with. For example, your SSO provider.

Leave Registration URL, Authorization server base, and Resource empty. The MCP Server does not support Dynamic Client Registration (DCR) or a Client Identifier Metadata Document (CIMD). ChatGPT correctly shows these registration methods as unavailable.

The profile scope is required. Every request to the authorization endpoint must include it, or the request fails.

The seated scope is required for write access. When your OAuth authorization request includes the seated scope, the resulting access token is a seated token. When it does not, the access token is explicitly unseated, and the Write Draft and Publish Draft tools fail with an unseated-user error, even if the signed-in account has a real, paid license seat. Include seated in the scopes that you request if you want to use these tools.

Select Create.
ChatGPT redirects you to sign in to your site through the identity provider that you chose. After you sign in, ChatGPT completes the connection.

ChatGPT can now use the connector to call the tools listed in the Available tools section of this article. When you ask ChatGPT a question about your knowledge base, ChatGPT calls the MCP Server and uses the result in its answer.

The New Plugin dialog in ChatGPT with Name, Description, Server URL, and Authentication fields

Available tools

The MCP Server gives these tools to a connected MCP client:

Tool	Type	What the tool does
Search Pages	Read	Performs a full-text search of the pages on your site, and returns the title, path, and a preview of each result
Semantic Content Search	Read	Finds the parts of your content that are most related to a question, and returns the correct part of a long article
Get Page	Read	Returns the full content of one page via the page ID or the page path
Get File	Read	Returns the content of a file that is attached to a page (for example, a PDF or an image)
Write Draft	Write	Creates a new page, or changes the draft content of a page
Write Draft File	Write	Attaches a file to a draft page, or replaces a file on a draft page
Publish Draft	Write	Publishes a draft, which makes the draft the live version of the page

The write tools use the draft workflow of NiCE KM. New content stays in draft form, and the content is not visible to your readers until you publish it. The MCP client can publish the draft with the Publish Draft tool, or a user can publish the draft manually.

Permissions and security

NiCE KM is a permission-based system. An API key can only see and do the tasks that its user account is permitted to do, and the MCP Server does not give more access than the permissions of the account.

If the account has access to public content only, the search and retrieval tools do not return restricted pages or private pages.
If the account does not have authoring permissions, the Write Draft tool, the Write Draft File tool, and the Publish Draft tool do not work for that API key.
If you want the MCP client to only answer questions and not change content, use an account that has neither authoring nor publishing permissions.