Using the Model Context Protocol endpoint

---
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.
---

# Connect the NiCE Knowledge Management MCP Server

## Inputs
- SITE_HOST: the customer site hostname (e.g. help.example.com). If not provided,
  prompt the user for it and wait for their answer before doing anything else.
- TOKEN_ENV: environment variable holding the Server API Token. Default name:
  <CUSTOMER_SITE>_MCP_TOKEN. Never read, echo, or log the token value.

## Endpoint
- URL: https://SITE_HOST/@api/deki/mcp
- Transport: HTTP (streamable HTTP)
- Auth header: Authorization: Bearer ${TOKEN_ENV}

## Steps
1. If SITE_HOST was not provided, ask the user for their NiCE KM site
   hostname and wait for the answer.
2. Detect the host agent/CLI and its MCP config location and schema:
   - opencode  -> ~/.config/opencode/opencode.json  (type: "remote")
   - Claude Code -> ~/.claude.json / .mcp.json       (type: "http")
   - Codex     -> ~/.codex/config.toml               ([mcp_servers.expert], bearer_token_env_var)
   - Cursor    -> ~/.cursor/mcp.json
3. Add a server named "expert" pointing at the URL, referencing the token via
   the environment variable TOKEN_ENV. Do not hard-code the token.
4. Restart or reload the client if required.
5. Verify connectivity and list the exposed tools:
   page_search, llm_kernels, page_get, file_get, report_run,
   draft_write, draft_file_write, draft_publish.

## Failure handling
- HTTP 403 on the endpoint: the MCP feature is disabled on the site. Tell the
  user to contact their NiCE account rep to enable it. Do not retry.
- Write tools (draft_write / draft_publish) fail with an unseated-user error:
  the token's account needs a paid license seat.

## Safety
- Never print the token value. Reference it only through the environment
  variable. Do not commit the token to any file.

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>".

Use the claude mcp add command to register the MCP endpoint 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>"
      }
    }
  }
}

Add the server to your global ~/.cursor/mcp.json file (or a project-scoped .cursor/mcp.json). Cursor uses the same JSON shape as the generic example:

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

Then enable the server in Cursor Settings > MCP and confirm it shows the available tools.

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 endpoint, install the community pi-mcp-adapter package:

pi install npm:pi-mcp-adapter

Then add the MCP endpoint 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.