FAQ

Last update: October 13, 2026

---

Frequently asked questions about Tolk for Cisco UC, organized by topic.

---

General

What is Tolk for Cisco UC?

Tolk for Cisco UC is an on-premises MCP (Model Context Protocol) server that bridges AI agents — Claude Desktop, GitHub Copilot, Cursor, or any MCP-compatible tool — to your Cisco Unified Communications infrastructure.

It is not a cloud service. It runs as a Docker container on a host inside your network, exposes a secure HTTPS MCP endpoint to AI agents, and communicates with Cisco UC nodes using AXL, RIS, CUPI and SSH. It is administered from an HTTPS Admin Web UI.

Does it require internet access?

No. Tolk is fully air-gapped capable. It has no telemetry, no cloud dependency, and no phone-home behavior. All connectivity is strictly between:

• Your AI agent client → Tolk (HTTPS/MCP)
• Administrators' browsers → Tolk (HTTPS, Admin Web UI)
• Tolk → Your Cisco UC nodes (AXL/HTTPS, RIS/HTTPS, CUPI/HTTPS, SSH)

Even license verification is performed offline — the license file is a signed JWT validated locally against the server's hostname.

Which AI agents are compatible?

Any agent that supports the MCP Streamable HTTP transport protocol. For example:

• Claude Desktop
• VS Code with the MCP extension
• Cursor
• OpenCode
• Custom LLM-based tools using the MCP SDK

Tolk uses the standard MCP Streamable HTTP transport — any MCP-compliant client will work.

Can I use it with a cloud-hosted LLM?

Yes. The LLM (OpenAI, Anthropic Claude API, etc.) and the AI agent can be cloud-hosted. Tolk stays inside your network: the only inbound connection it needs is the agent's MCP call.

Keep in mind that the results of the Tolk tools are given to the LLM as context: with a cloud LLM, the Cisco UC data read by the agent (configuration, users, devices…) is sent to the LLM provider. Restrict the tools and data each agent can access with its client RBAC profile (Clients page → Profiles tab), and prefer a local LLM when no data may leave your network.

Is it compatible with local LLMs?

Yes. When paired with a local LLM (Ollama, LM Studio, llama.cpp, etc.) and a locally running AI agent, the entire chain operates without any internet connectivity. This is ideal for highly regulated environments where no data may leave the internal network.

---

Licensing

How do I get a license?

Contact tolk@sourdeau.com to order a license, giving the FQDN of the Docker host (hostname -f): the license is bound to it (see Obtain Your License).

You receive a license.jwt file. Import it from the Admin Web UI: Licensing page → Import license card, then click Apply & restart (see Import Your License).

What happens when my license expires?

License expiry follows a two-phase model:

1. Grace period (30 days after expiry, unless the license sets another duration): the server continues to operate normally. A renewal reminder is logged and shown on the Licensing page and in /status.
2. Post-grace (EXPIRED): the MCP endpoint is disabled — no AI agent can connect. The Admin Web UI stays available as a recovery console, to import a new license. A license that expires while the server is running is enforced at the nightly restart (03:15).

Plan ahead

Monitor the expiry date on the Licensing page (or with the infra_server_status tool / GET /status), and renew before the end of the grace period (see Renewal).

Can I use the same license on a different server?

No. Licenses are hostname-bound — each license is issued for a specific Docker host FQDN (HOST_FQDN). Running the same license on a different hostname results in an INVALID state.

Contact tolk@sourdeau.com for re-issuance when migrating to a new server.

Is the license version-agnostic?

Yes. A valid license continues to work across all software upgrades — there is no per-version licensing. Once issued, your license is valid until its expiry date regardless of how many times you upgrade.

What is a demo license?

A time-limited license for evaluation purposes. It grants full access to all product modules for a fixed trial period. Available on request at tolk@sourdeau.com.

What server attribute is the license bound to?

The license is bound to the FQDN of the Docker host (hostname -f), set in HOST_FQDN and used as the container hostname. The hostname is embedded in the license JWT at issuance time and verified at every startup; the Licensing page shows the server hostname next to the one of the license. Any hostname change — VM rename, migration, domain change — invalidates the license.

Contact tolk@sourdeau.com for re-issuance if the hostname changes.

How do I check the current license status?

Open the Licensing page of the Admin Web UI: it shows the license state, customer, tier, expiry date, enabled products, the clients used versus the maximum, and the hostname binding. The license state is also shown on the Dashboard.

Alternatively, use the infra_server_status MCP tool or GET /status, or the command-line checker:

docker compose exec tolk python scripts/license_checker.py

---

Installation & Setup

Which operating systems are supported?

Tolk is delivered as a Docker image: it runs on any host with Docker Engine ≥ 27.0 and Docker Compose ≥ 2.32. A Linux host is recommended for production; macOS and Windows (Docker Desktop, WSL 2) are suitable for evaluation and lab environments. See the Prerequisites.

The following Linux distributions are actively tested:

Distribution	Versions
Ubuntu LTS	22.04, 24.04
RHEL / AlmaLinux	9.x, 10.x
Debian	12, 13

Can I run it in Docker?

Yes — Docker is the deployment mode of Tolk. Follow the Getting Started guide: only a few Docker bootstrap values are set in .env before the first start; everything else is configured from the Admin Web UI.

The container runs as a non-root user (UID / GID, root refused), with a read-only root filesystem and a health check. All runtime data is persisted via bind-mount volumes.

Can I run multiple instances?

Yes. You can run multiple Tolk instances on separate hosts, each with its own hostname-bound license. This is the recommended approach for separating environments (e.g., production vs. lab) or serving multiple teams with isolated audit trails.

Several instances can also be published behind a load-balancing reverse proxy (see Reverse Proxy).

What if the RSA-PSS signature check fails during installation?

Do not proceed with the installation. A signature verification failure means either:

• The archive was corrupted during download (retry the download and verify SHA-512)
• The archive has been tampered with

Contact tolk@sourdeau.com before proceeding. Never run software that fails its integrity check.

How do I reconfigure after installation?

From the Admin Web UI — no .env editing is needed:

1. Edit the settings on the Global settings and Products pages (the clients are on the Clients page). Each change is staged.
2. Click Apply & restart in the banner (or System & reload → Apply / Restart): review the pending changes and the pre-restart checks, then click Restart now.

See Editing Settings. Exception: the Docker-level values (HOST_FQDN, UID / GID, MCP_SERVER_PORT, ADMIN_UI_PORT) are applied by Docker Compose — after changing them, run docker compose up -d on the host.

How do I change the listening port (e.g. 8443 → 10443)?

1. In Global settings → Server tab → Transport, edit MCP_SERVER_PORT (e.g. 10443) and save. The Admin Web UI port is ADMIN_UI_PORT (Admin UI tab); the two ports must differ.
2. In the same section, update MCP_SERVER_SECURITY_ALLOWED_ORIGINS with the new port (e.g. https://tolk.domain.com:10443). MCP_SERVER_SECURITY_ALLOWED_HOSTS needs no change if it uses the port wildcard (tolk.domain.com:*).
3. If AUTH_ISSUER (Authentication tab) contains the port, update it as well. It is embedded in the JWT tokens: redistribute them afterwards (Reset tokens then View credentials on the Clients page).

4. The port is published by Docker Compose, so Apply & restart is not enough: on the host, re-create the container:

   docker compose up -d
   

5. Update the endpoint URL in all AI agent configurations and, if applicable, your firewall rules.

How do I trust the Cisco UC certificates and test the connectivity?

TLS verification towards the CUCM, IMP and CUC nodes is enabled by default: add the CA that issued their tomcat certificates to the product CA trust store (Products page), then check the access with Tools → Product connectivity test (DNS, TCP, TLS, authentication, APIs, SSH).

See Trust the Cisco UC Certificates and Test the Connectivity to Cisco UC.

How do I upgrade Tolk?

A new release is extracted over the installation directory and applied with tolk-setup.sh; your .env, secrets, clients, logs and backups are preserved.

Follow the Upgrade procedure: package integrity check, backup and maintenance mode beforehand, dry-run, then restart on the new image.

How do I completely uninstall Tolk?

To fully remove Tolk from a server, follow these steps:

1. Stop and remove the container:

docker compose down

2. Remove the Docker image:

# List Tolk images
docker images | grep tolk

# Remove the image
docker rmi tolk-for-cisco-uc:latest

# Remove any dangling images
docker image prune -f

3. Delete the installation directory:

rm -rf ~/tolk

After these steps, no Tolk artefacts remain on the server.

---

Operations

How do I drain a node (maintenance mode) before a restart or an upgrade?

On the System & reload page → Maintenance mode card, click Enable maintenance mode — no restart is needed:

• the MCP sessions in progress continue, new sessions are refused;
• a client idle for more than MAINTENANCE_IDLE_TIMEOUT_SECONDS (5 minutes by default) is turned away with a "retry later" message; Refuse now turns away an active client immediately;
• once every client is drained, /health reports "status":"maintenance", so a load balancer takes the node out.

The mode survives a restart: click Disable maintenance mode once the service is checked. See Maintenance mode for the idle timeout and the optional maximum drain duration.

How do I put Tolk behind a reverse proxy or a load balancer?

Publish Tolk under a VIP FQDN on the proxy, then declare on the Tolk side that FQDN in MCP_SERVER_PUBLIC_URL, the proxy IPs in TRUSTED_PROXY_IPS, and allow the proxy and the admin PCs in ADMIN_UI_TRUSTED_IPS. The health checks must send the Host header of the node.

See Reverse Proxy (HAProxy) for the settings and the complete HAProxy configurations (single server and load balancing). With load balancing, use the maintenance mode to take a node out without cutting the sessions in progress.

How do I back up and restore Tolk, and export the backups over SFTP?

Backups are automatic (every BACKUP_INTERVAL_HOURS, weekly by default) and encrypted; Backup now on the Backup / Restore page triggers one immediately. The same page lists, downloads and restores the archives. Each archive can also be pushed to an SFTP server.

See Backup and Backup SFTP export for the settings, and Backup & Restore for the encryption model and the restore procedure.

How do I undo a change, and is the configuration history kept?

• Pending change (not applied yet): on the System & reload page → Apply / Restart, click Undo this change or Undo all changes (see Editing Settings).
• Applied change: a snapshot of the configuration is taken before each change (the last 16 by default, BACKUP_ADMIN_UI_ENV_BACKUP_RETENTION). On the Backup / Restore page, select the Configuration (.env) perimeter and restore a snapshot: every parameter that differs is staged for review before Apply & restart.

Certificates and RSA keys have their own snapshots, restored the same way (see Other backups).

How do I generate a show-tech for support?

On the Logs page → Diagnostics tab, click Run show-tech, then Download the bundle and send it to tolk@sourdeau.com with a description of the issue. Secrets (private keys, tokens, Cisco UC credentials, license file) are never included.

See Show Tech (Support Bundle).

---

Authentication & Clients

How many AI clients can I have simultaneously?

The number of clients is limited by the license (max clients). The Licensing page shows the declared clients against the limit (e.g. 3 / 5). Beyond the limit, the license switches to GRACE with a countdown. Contact tolk@sourdeau.com if you need to increase your client limit.

How do I add a new client?

1. Open the Clients page and click Add client.
2. Enter the name, the subject (JWT sub claim, e.g. sub-<name>-YYYYMMDD) and the RBAC profile — plus the authentication mode when AUTH_MODE is jwt+oauth2 — then click Create client.
3. Click Apply & restart: the client directory and its credentials (JWT token and/or OAuth secret) are generated.
4. Back on the Clients page, click View credentials and send the connection details securely to the user — they are displayed only once.

See Create a Client.

How do I remove a client?

Delete the client on the Clients page, then click Apply & restart. At the restart, the client's directory — including all reports, tokens, and stored Cisco UC credentials — is purged automatically, and its tokens are rejected.

Data loss warning

Download any reports you wish to retain (Reports page) before deleting the client and restarting.

How do I revoke a client token without removing the client?

On the Clients page, click Reset tokens on the client — no restart is needed:

• JWT: the current token is revoked immediately and a new one is generated;
• OAuth 2.1: the client_secret is rotated — the previous secret can no longer obtain tokens; access tokens already issued expire on their own (AUTH_OAUTH_TOKEN_EXPIRY_SECONDS).

Then click View credentials to retrieve the new credentials (shown once) and send them to the user.

Note

The POST /revoke endpoint (RFC 7009) lets a client revoke one of its own tokens.

What is the difference between JWT and OAuth 2.1 mode?

	JWT Mode	OAuth 2.1 Mode
Token type	Static, long-lived (default: 365 days)	Dynamic, short-lived (default: 1 hour)
Issuance	Generated by the server, shown once	On-demand via POST /token
Client secret	None	bcrypt-hashed, shown once
Best for	Interactive AI agents (simple setup)	Automated pipelines, CI/CD, stricter security
Revocation	Reset tokens (Clients page), POST /revoke	Reset tokens (rotates the secret), POST /revoke

Both modes are equally secure in terms of transport and signature. OAuth 2.1 limits the window of exposure if a token is compromised due to its short lifetime. The mode is set by AUTH_MODE (Global settings → Authentication); with jwt+oauth2, each client has its own mode (see Authentication Modes).

What happens to tokens after an RSA key rotation?

The rotation (Regenerate keypair, Global settings → Authentication tab) re-issues a new JWT token for every client. Retrieve each one with View credentials on the Clients page.

The previous tokens remain accepted until the Apply & restart that activates the new key pair; from then on they are rejected. Plan the restart together with the redistribution of the new tokens.

OAuth client secrets (bcrypt-based) are unaffected: OAuth clients simply request a new access token. See RSA Key Rotation.

How do I configure the MCP server in OpenCode with OAuth authentication?

In OAuth 2.1 mode, OpenCode handles the authentication flow natively — no bearer token needs to be hard-coded in the configuration file.

Edit opencode.json and declare the server without an Authorization header:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "cisco-uc-mcp-server": {
      "type": "remote",
      "url": "https://tolk.domain.com:8443/mcp/",
      "enabled": true
    }
  }
}

Before starting the OpenCode desktop client, run the following CLI command to authenticate:

opencode mcp auth cisco-uc-mcp-server

OpenCode opens the Tolk login page in your browser, where you enter your client_id and client secret to complete the authentication:

┌  MCP OAuth Authentication
│
▲  cisco-uc-mcp-server has expired credentials. Re-authenticating...
│
◇  Authentication successful!
│
└  Done

Tip

The client secret is shown once with View credentials on the Clients page. In production, also allow OpenCode's redirect_uri (http://127.0.0.1:19876/mcp/oauth/callback by default) — see OAuth Redirect URI Allow-List.

How do I restrict a client to read-only access?

Assign it a read-only RBAC profile: on the Clients page, edit the client and select the predefined auditor profile (AXL get / list operations and SQL queries, show SSH commands, CUPI GET only), then click Apply & restart. For finer control, create a custom profile on the Profiles tab (Add profile) and keep only the read operations.

See Predefined Profiles and Editing a Profile.

How do I change AUTH_MODE without breaking the existing clients?

Switching directly between jwt and oauth2 replaces the credentials of every client at the next restart (the JWT tokens or the OAuth secrets are removed): all the AI agents must be reconfigured at once. For a progressive migration, go through the hybrid mode:

1. Set AUTH_MODE to jwt+oauth2 (Global settings → Authentication tab), then Apply & restart: each client keeps its current mode.
2. On the Clients page, set the clients to jwt+oauth2, apply, then send them their new credentials (View credentials).
3. Once every agent uses the new mode, set the clients to the target mode, then AUTH_MODE to the same mode.

The Admin Web UI refuses an AUTH_MODE more restrictive than the mode of a client: align the clients first. See Authentication Modes.

---

Admin Web UI

How do I give an administrator read-only access to the Admin Web UI?

On the Administrators page → Profiles tab, click Add profile and set every page to read-only (RO) — or to no access for the pages to hide. Then assign the profile to the account on the Accounts tab. Changes take effect immediately.

See Administrators.

I lost my Admin Web UI password, or my account is locked — what do I do?

• Another administrator with write access on the Administrators page can click Reset password on your account (temporary password, to change at the next login) or unlock it.

• No other administrator available: reset the password from the Docker host (add --unlock if the account is locked):

  docker compose exec tolk python scripts/admin_set_password.py <login>
  

  See Create the Admin Account.

After too many failed logins (ADMIN_UI_LOGIN_MAX_ATTEMPTS), the login is also locked out temporarily (ADMIN_UI_LOGIN_LOCKOUT_MINUTES, 15 minutes by default).

The Admin Web UI returns 403 Forbidden — what should I check?

The admin port only accepts the source IPs allowed by ADMIN_UI_TRUSTED_IPS (by default the private ranges 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16). A 403 means that:

• the IP of your PC is not in this allow-list — behind a reverse proxy, the IP checked is the one of X-Forwarded-For, only if the proxy is declared in TRUSTED_PROXY_IPS;
• or your IP (or subnet) was blacklisted by hand on the System & reload page (Blacklisted IPs card, scope Web UI admin).

The denial is logged in audit.log (action=adminui/access, reason ip_not_allowed or ip_blacklisted). Fix it from an allowed PC: Global settings → Admin UI tab, then Apply & restart, or Remove for the blacklist (also cleared by a restart). If no PC can reach the Admin Web UI any more, edit ADMIN_UI_TRUSTED_IPS in the .env file on the Docker host, then run docker compose up -d. See Admin UI.

---

Product Cisco CUCM

Which CUCM versions are supported?

CUCM 14 and 15 are officially supported. AXL schemas are managed per CUCM version — the AI agent downloads the schemas matching your cluster with cucm_download_axl_toolkit (and cucm_download_ris_toolkit for RIS).

Can it manage multiple CUCM clusters?

Yes. Credentials are stored per host, encrypted in each client's credential store: the AI agent registers each node with cucm_store_credentials (AXL) and cucm_os_store_credentials (SSH), then targets it by FQDN or IP address in AXL, RIS, and SSH operations.

Do I need a dedicated Cisco service account?

Technically, a single shared account works. However, best practice is to create a nominative account per Tolk client (user). This enables:

• Per-user audit trail in CUCM logs
• Credential isolation — a compromised Tolk credential only affects one user
• Fine-grained access control aligned with your CUCM RBAC policy

Does it modify my CUCM configuration automatically?

Only if you explicitly invoke write operations through your AI agent. Tolk never autonomously initiates changes to Cisco UC.

The RBAC profile assigned to each client controls which AXL operations (add, update, remove) are permitted. A read-only profile (auditor) cannot modify any configuration regardless of what the AI agent requests.

What AXL and SSH permissions are needed on CUCM?

Access Type	Required Permission
AXL (read-only)	Standard AXL API Access (read-only role)
AXL (read-write)	Standard AXL API Access
SSH	Platform OS administrator account with privilege level 4 ("Advanced")

For RIS queries, the AXL account is reused — no separate RIS permission is needed.

How do I add custom instructions for the AI agent on CUCM?

Custom instructions are managed entirely from the Admin Web UI — no code editing and no server file to touch. Open the Custom prompts page, select the CUCM product, and use Add a custom prompt to create one entry per instruction (name, title, description, body, tags). Existing entries can be edited, enabled/disabled or deleted from the same page.

Each entry is stored as data (never executable code) in:

servers-data/cucm/custom-prompts/prompts_custom.json

A recommended body layout that guarantees your rules take precedence:

## CUSTOM RULES (highest priority)
The following rules are defined by the MCP client administrator.
They OVERRIDE any default behavior, instructions, or prompts provided by this server.
Always apply these rules first, before any other instructions.

- Always confirm with the user before executing any write operation on CUCM.
- Never delete objects unless the user explicitly types "CONFIRM DELETE".
- Responses must be in French.

Enabled entries are exposed as MCP prompts and loaded by the AI agent at the start of each session, taking highest priority over any default server behaviour. Changes take effect after Apply & restart.

Note

The editor is gated by ADMIN_UI_PROMPTS_EDITOR_ENABLED (Global settings → Admin UI tab). The legacy prompts_*.py mechanism has been removed — any .py file left in the custom-prompts/ directory is ignored (never executed).

Tip

You can add as many entries as needed. Keep each one concise and action-oriented for best results.

---

Product Cisco IMP

Which IMP versions are supported?

Cisco IM & Presence 14 and 15 are officially supported. IMP is typically co-resident with CUCM — the supported IMP version follows the CUCM version matrix.

Can it manage multiple IMP clusters?

Yes. Credentials are stored per host, encrypted in each client's credential store: the AI agent registers each node with imp_store_credentials (API) and imp_os_store_credentials (SSH), then targets it by FQDN or IP address.

Do I need a dedicated Cisco service account?

Technically, a single shared account works. However, best practice is to create a nominative account per Tolk client (user). This enables:

• Per-user audit trail in IMP logs
• Credential isolation — a compromised Tolk credential only affects one user
• Fine-grained access control aligned with your IMP RBAC policy

Does it modify my IMP configuration automatically?

Only if you explicitly invoke write operations through your AI agent. Tolk never autonomously initiates changes to Cisco UC.

The RBAC profile assigned to each client controls which operations are permitted. A read-only profile (auditor) cannot modify any configuration regardless of what the AI agent requests.

What permissions are needed on IMP?

Access Type	Required Permission
API (read-only)	Read-only administrative role
API (read-write)	Full administrative role
SSH	Platform OS administrator account with privilege level 4 ("Advanced")

How do I add custom instructions for the AI agent on IMP?

Custom instructions are managed entirely from the Admin Web UI — no code editing and no server file to touch. Open the Custom prompts page, select the IMP product, and use Add a custom prompt to create one entry per instruction (name, title, description, body, tags). Existing entries can be edited, enabled/disabled or deleted from the same page.

Each entry is stored as data (never executable code) in:

servers-data/imp/custom-prompts/prompts_custom.json

A recommended body layout that guarantees your rules take precedence:

## CUSTOM RULES (highest priority)
The following rules are defined by the MCP client administrator.
They OVERRIDE any default behavior, instructions, or prompts provided by this server.
Always apply these rules first, before any other instructions.

- Always confirm with the user before executing any write operation on IMP.
- Never delete objects unless the user explicitly types "CONFIRM DELETE".
- Responses must be in French.

Enabled entries are exposed as MCP prompts and loaded by the AI agent at the start of each session, taking highest priority over any default server behaviour. Changes take effect after Apply & restart.

Note

The editor is gated by ADMIN_UI_PROMPTS_EDITOR_ENABLED (Global settings → Admin UI tab). The legacy prompts_*.py mechanism has been removed — any .py file left in the custom-prompts/ directory is ignored (never executed).

Tip

You can add as many entries as needed. Keep each one concise and action-oriented for best results.

---

Product Cisco CUC

Which CUC versions are supported?

Cisco Unity Connection 14 and 15 are officially supported. CUC exposes its provisioning API through CUPI (REST at https://<host>:8443/vmrest/) — there is no AXL/SOAP toolkit and no WSDL schema to download.

Can it manage multiple CUC nodes?

Yes. CUC has no cluster abstraction in Tolk — credentials and operations are scoped per host. Add as many CUC hosts as needed via cuc_store_credentials (CUPI) and cuc_os_store_credentials (SSH); each host is stored separately in the client's credential store.

Do I need a dedicated Cisco service account?

Technically, a single shared account works. However, best practice is to create a nominative account per Tolk client (user). This enables:

• Per-user audit trail in CUC logs
• Credential isolation — a compromised Tolk credential only affects one user
• Fine-grained access control aligned with your CUC RBAC policy

Does it modify my CUC configuration automatically?

Only if you explicitly invoke write operations through your AI agent. Tolk never autonomously initiates changes to Cisco UC.

The RBAC profile assigned to each client controls which CUPI verbs (POST / PUT / DELETE) and which /vmrest/ paths are permitted. A read-only profile (auditor) is restricted to GET /vmrest/ and cannot modify any configuration regardless of what the AI agent requests.

What CUPI and SSH permissions are needed on CUC?

Access Type	Required Permission
CUPI (read-only)	Unity Connection administrator with the "System Administrator" role
CUPI (read-write)	Unity Connection administrator with a role template covering the targeted endpoints (users, call handlers, schedules, etc.)
SSH	Platform OS administrator account with privilege level 4 ("Advanced")

How do I add custom instructions for the AI agent on CUC?

Custom instructions are managed entirely from the Admin Web UI — no code editing and no server file to touch. Open the Custom prompts page, select the CUC product, and use Add a custom prompt to create one entry per instruction (name, title, description, body, tags). Existing entries can be edited, enabled/disabled or deleted from the same page.

Each entry is stored as data (never executable code) in:

servers-data/cuc/custom-prompts/prompts_custom.json

A recommended body layout that guarantees your rules take precedence:

## CUSTOM RULES (highest priority)
The following rules are defined by the MCP client administrator.
They OVERRIDE any default behavior, instructions, or prompts provided by this server.
Always apply these rules first, before any other instructions.

- Always confirm with the user before executing any write operation on CUC.
- Never delete objects unless the user explicitly types "CONFIRM DELETE".
- Responses must be in French.

Enabled entries are exposed as MCP prompts and loaded by the AI agent at the start of each session, taking highest priority over any default server behaviour. Changes take effect after Apply & restart.

Note

The editor is gated by ADMIN_UI_PROMPTS_EDITOR_ENABLED (Global settings → Admin UI tab). The legacy prompts_*.py mechanism has been removed — any .py file left in the custom-prompts/ directory is ignored (never executed).

Tip

You can add as many entries as needed. Keep each one concise and action-oriented for best results.

---

Security

Where are Cisco UC credentials stored?

Credentials are encrypted on disk, per client, using Fernet encryption (AES-128-CBC + HMAC-SHA256). The Fernet key is derived per-client via PBKDF2-SHA512 with 600,000 iterations, seeded from a stable UUID unique to each client (clients/<name>/secrets/.uuid).

Credentials are never stored in plaintext in .env, logs, or any other file.

Can the server read its own backups?

Yes, with its RSA private key. Backups are encrypted with AES-256-GCM, the session key being wrapped with the server's RSA public key (RSA-4096 OAEP). Restoring requires the RSA private key (secrets/rsa_private.pem): the server holds it and can restore its archives from the Backup / Restore page.

A backup copied elsewhere (e.g. exported over SFTP) cannot be read without that private key. Keep an offline copy of the private key — and of the archived keys after an RSA rotation — to be able to restore on a new server.

How does the audit log work?

Every auth event, tool call, credential operation, administration action and security anomaly is written to audit.log as a structured JSON object. The log is append-only — entries are never modified after being written. It can be browsed on the Logs page → Audit tab of the Admin Web UI.

Log rotation creates compressed archives, preserving the complete history. For long-term retention and SIEM integration, forward audit.log to your log aggregation infrastructure.

What happens if someone tampers with the server files?

The integrity watchdog runs an SHA-512 manifest check against all project files at startup and every INTEGRITY_CHECK_INTERVAL_HOURS (24 hours by default). The manifest is signed with RSA-PSS (RSA-4096) and cannot be forged without the editor signing key.

• At startup, a failed check prevents the server from starting.
• During a periodic check, a violation triggers a graceful shutdown of the server.

In both cases, the affected files are logged at CRITICAL level in app.log and audit.log. The integrity state is shown on the Dashboard and System & reload pages (see Software Integrity Verification).

React to integrity failures immediately

An integrity alert is a serious security event. Isolate the server, investigate the affected files, and reinstall the release files or restore from a known-good backup.

How do I report a security vulnerability?

Email tolk@sourdeau.com privately with a description of the vulnerability. Do not open a public GitHub issue for security findings — responsible disclosure protects all users.

You will receive an acknowledgment within 48 hours.

---

Troubleshooting

Product tools are not available — what should I check?

Check the license state on the Licensing page (or with the infra_server_status tool / GET /status). Common causes:

State	Cause	Effect	Resolution
INVALID	License missing, tampered, or hostname mismatch	MCP endpoint disabled (Admin Web UI available)	Import a valid license; check the hostname binding on the Licensing page
EXPIRED	License past grace period	MCP endpoint disabled (Admin Web UI available)	Renew via tolk@sourdeau.com and import it
GRACE	Within grace period, or max clients exceeded	Full operation	Renew soon, or reduce the number of clients

With a valid license, only the products enabled by the license are loaded, and a client only sees the tools allowed by its RBAC profile (Clients page → Profiles tab).

My AI agent cannot connect to Tolk — what should I check?

Work through this checklist in order:

1. Endpoint URL and port — use the Server URL displayed by View credentials (e.g. https://tolk.domain.com:8443/mcp)
2. Credentials — the agent must use the current token (or client_id / client_secret). If lost, use Reset tokens then View credentials on the Clients page
3. TLS certificate trust — the AI agent must trust Tolk's TLS certificate. Either trust the self-signed cert in the agent's trust store, or replace it with a CA-signed certificate
4. Network / firewall — confirm the MCP port (default 8443) is reachable from the agent host to the Tolk host
5. Server state — the Dashboard shows the license state; the System & reload page shows the maintenance mode and the blacklisted IPs

Authentication fails with HTTP 401 — what are the possible causes?

Cause	Resolution
Token expired or lost	Reset tokens then View credentials on the Clients page
Token revoked	The token was revoked (Reset tokens or POST /revoke): use the new credentials
RSA key rotated	Previous tokens are rejected after the restart that activates the new key: use the token re-issued by the rotation
Client deleted	The client no longer exists on the Clients page
Source IP blacklisted	Too many authentication failures: see the question below
Wrong token format	Ensure the Authorization header uses Bearer <token> format exactly

My IP is blocked — what do I do?

The Fail2Ban mechanism has blocked the IP after repeated authentication failures (AUTH_FAIL_LIMIT failures in AUTH_FAIL_WINDOW_SECONDS). The MCP endpoint then answers HTTP 401, and the OAuth and /status endpoints HTTP 429 (too_many_failures).

Options:

• Unblock it — System & reload page → Blacklisted IPs card → Remove
• Wait for the blacklist duration to expire (AUTH_BLACKLIST_DURATION_SECONDS, default: 15 minutes)
• Restart the server — the blacklist is held in memory and cleared at restart

Behind a reverse proxy, declare it in TRUSTED_PROXY_IPS: the blacklist then applies to the real client IP (from X-Forwarded-For) instead of the proxy address, so one failing client no longer blocks everybody. Trusted proxies are never blacklisted.

The blocked IPs and their causes appear on the Statistics pages and in audit.log (AUTH_BLOCKED and AUTH_FAILED events, Logs page → Audit tab). Resolve the root cause of the authentication failures before reconnecting.

What is the difference between the per-client and the global rate limit?

Two independent sliding-window limits apply:

• Per-client — defined in each client RBAC profile (Clients page → Profiles tab, one limit per service). It caps how fast a single client can call a given operation.
• Global (all clients, per destination host) — an optional cumulative limit protecting each Cisco node from the combined load of all clients. Keyed per destination host + product/service.

A per-client rejection is logged as RATE_LIMITED; a global rejection as RATE_LIMITED_GLOBAL. Both return HTTP 429 with a Retry-After hint. The global caps are set per product on the Products page (RATELIMIT_GLOBAL_<PRODUCT>_<SERVICE>, 0 = no cap); the whole feature is switched off with RATELIMIT_GLOBAL_ENABLED (Global settings → Rate limiting tab).

The license shows INVALID — what should I verify?

Check these points on the Licensing page, in order:

1. License present — if no license is installed, import it (Import license card) then Apply & restart
2. Hostname match — the server hostname (HOST_FQDN, the output of hostname -f on the Docker host) must exactly match the hostname of the license. A VM rename or migration breaks this; after fixing HOST_FQDN, run docker compose up -d on the host
3. File integrity — if the file was altered in transit (line endings, encoding), import it again from the original file

The import preview shows the license details and flags a hostname mismatch before anything is replaced.

OAuth token request fails with 401 invalid_client — what happened?

The client_id / client_secret pair was rejected. Common causes:

• the secret is wrong or outdated — it was rotated with Reset tokens;
• the secret was lost — it is shown only once;
• in jwt+oauth2 mode, the client is declared in jwt mode only (Clients page).

To issue a new secret, click Reset tokens on the client (Clients page), then View credentials to retrieve it — no restart is needed.

My OpenCode client cannot connect (error ERR_TLS_CERT_ALTNAME_INVALID) — what should I check?

This error means the TLS certificate presented by the server does not contain the FQDN used by the client in its Subject Alternative Name (SAN) extension.

Node.js v17+ (and all modern TLS clients) require the SAN extension — the CN field alone is no longer accepted for hostname validation (RFC 6125).

• Self-signed certificate: its SANs come from AUTH_ISSUER, MCP_SERVER_SECURITY_ALLOWED_HOSTS and MCP_SERVER_PUBLIC_URL. Add the FQDN used by the client to these settings, then Apply & restart: the certificate is regenerated.
• CA-signed certificate: in Global settings → TLS / Crypto tab → MCP server certificate, click Generate CSR… (extra SANs can be added in the preview), have it signed by your CA, import the .crt, then Apply & restart (see Use CA-Signed Certificates).

Tip

If your CA is not trusted by OpenCode's Node.js runtime, also set NODE_EXTRA_CA_CERTS=/path/to/ca.crt in your environment (or export it from ~/.bashrc).