Connect manually

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.

Let an AI agent set this up for you

If you already use an agentic CLI tool (Claude Code, opencode, Codex, Cursor), you can have the agent add the MCP endpoint for you. Copy the prompt below, replace <your-site> with your site hostname, and paste it into your agent. Set your API key in an environment variable named <CUSTOMER_SITE>_MCP_TOKEN first (using the Server API Token from Get Authorization).

First, ask me for my NiCE KM site hostname if I have not already given it to
you, and wait for my answer. Then use it as <your-site> everywhere below.

Add an MCP server named "expert" to my MCP client configuration.

- Transport: HTTP (streamable HTTP)
- URL: https://<your-site>/@api/deki/mcp
- Auth: send an "Authorization: Bearer" header whose value is my API token

Detect which agentic CLI / MCP client I am running and write the server entry
to the correct config file for that tool (for example
~/.config/opencode/opencode.json, ~/.claude.json or .mcp.json,
~/.codex/config.toml, or ~/.cursor/mcp.json). Match that tool's required schema
(for example Claude Code needs "type": "http").

Read the token from the environment variable <CUSTOMER_SITE>_MCP_TOKEN rather
than hard-coding it in the config. Tell me the exact command to set that
variable, but never print the token value back to me.

After writing the config, verify the server is reachable and list the tools it
exposes: page_search, llm_kernels, page_get, file_get, report_run,
draft_write, draft_file_write, draft_publish (plus graph_neighbors,
graph_subgraph, and graph_paths if the knowledge graph is on). If the endpoint returns HTTP 403,
tell me the MCP feature is not enabled on the site and that I need to contact my
NiCE account rep to enable it.

---
name: connect-nice-km-mcp
description: >-
  Install and verify the NiCE Knowledge Management MCP Server in the current
  agentic CLI (Claude Code, opencode, Codex, Cursor, or any MCP client). Use
  when the user asks to connect, add, or set up the NiCE KM / Expert MCP
  endpoint.
---

Standard configuration examples

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

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

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

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

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

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

pi install npm:pi-mcp-adapter

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

Connect ChatGPT

ChatGPT connects to the NiCE KM MCP endpoint 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 endpoint: first, create an OAuth client; then create the connector.

Protocol versions

The MCP endpoint supports the MCP specification revision 2026-07-28 and these earlier revisions: 2025-11-25, 2025-06-18, 2025-03-26, and 2024-11-05.

Clients that use an earlier revision connect with the initialize handshake. The server negotiates the version in its initialize response:

• If the client asks for one of the supported earlier revisions in protocolVersion, the server returns that same version.
• If the client asks for any other version, or sends no version, the server returns 2025-11-25.
• The initialize response never returns 2026-07-28. Clients built for an earlier revision do not recognize that version and disconnect.

server/discover

Clients that use revision 2026-07-28 call server/discover to find the supported versions, capabilities, and server identity. No handshake is needed first. The result has this shape:

{
  "resultType": "complete",
  "supportedVersions": ["2026-07-28"],
  "capabilities": {
    "tools": { "listChanged": false }
  },
  "_meta": {
    "io.modelcontextprotocol/serverInfo": {
      "name": "mindtouch-deki-mcp",
      "version": "1.0.0"
    }
  }
}

The server/discover result does not include the protocolVersion and serverInfo fields of the initialize result. The server identity is in _meta instead.

resultType

Every result from the server includes resultType. The value is always complete, including results from tools/call, tools/list, server/discover, and ping. If your client does not read this field, it is not affected.

Cache hints

The tools/list result includes two cache hints:

• ttlMs: how long the client can reuse the tool list, in milliseconds. The value is 300000 (5 minutes).
• cacheScope: the value is public.

When edge caching for anonymous reads is turned on, a successful anonymous read response also has a Cache-Control: public, s-maxage=<seconds> header. Refer to Anonymous public reads in this article.

Sessions

The server tracks each request in a per-user session, but it does not store session state between requests. The server finds the session ID for a request this way:

• If the request has an Mcp-Session-Id header with a valid value, the server uses that value.
• If the header is missing or not valid, the server uses the site session ID of the request.

A valid Mcp-Session-Id value has 200 characters or fewer and uses only letters, numbers, periods (.), underscores (_), and hyphens (-). The server ignores any other value.

The server returns the session ID in the Mcp-Session-Id header of the initialize response. Send that value on later requests to keep them in the same session. A DELETE request to the endpoint is accepted, but it does nothing because the server stores no session state.

Troubleshooting

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 endpoint 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 the account does not have a license seat, the MCP endpoint removes the Write Draft, Write Draft File, Publish Draft, and Run Report tools from the tool list. The client sees only the read tools, and a direct call to a removed tool is refused. A valid site API key counts as seated.
• If you want the MCP client to only answer questions and not change content, use an account that has neither authoring nor publishing permissions.

The MCP endpoint must be enabled on your site before any MCP client can connect. If the endpoint returns a 403 error, contact your NiCE account rep to enable it.