Getting Started¶

Last update: June 4, 2026

This guide walks you through everything needed to get AI-Bridge for Cisco UC up and running — from prerequisites to your first successful AI agent connection.

Before You Begin¶

The full journey takes six steps:

 ① Prerequisites  →  ② License  →  ③ Install  →  ④ Configure  →  ⑤ First Startup  →  ⑥ Connect

Estimated time: ~one hour for a standard deployment on a prepared Docker host.

Step 1 — Prerequisites¶

Docker¶

AI-Bridge for Cisco UC is deployed as a Docker container.

Requirements:

Docker Engine ≥ 27.0
Docker Compose ≥ 2.32

For installation instructions, refer to the official Docker documentation.

docker --version
docker compose version

Service account: create a dedicated non-root user (e.g. docker) and add it to the docker group so it can manage containers without sudo:

sudo useradd -m -s /bin/bash docker
sudo usermod -aG docker docker

All subsequent commands in this guide assume you are logged in as this user.

Host operating system: any OS capable of running Docker.

Linux — recommended for production (Docker Engine)
macOS — supported via Docker Desktop
Windows — supported via Docker Desktop with WSL 2

Production recommendation

For production deployments, use a Linux host with Docker Engine for best performance, stability, and security. Docker Desktop (macOS / Windows) is suitable for evaluation, development, and lab environments.

Minimum host resources:

CPU: 2 vCPUs
RAM: 2 GB
Disk: 10 GB (varies with backup retention and report volume)

Cisco UC Requirements¶

CUCMIMPCUC

The CUCM module uses three protocols: AXL, RIS, and SSH.

Protocol	Requirement
AXL	Activate Cisco AXL Web Service on the publisher node (Serviceability → Tools → Service Activation). Create an user (EndUser ou ApplicationUSer) with the roles "Standard AXL API Users", "Standard SERVICEABILITY" and "Standard CCM Admin Users"
RIS	Cisco RisPort70 runs by default — no activation needed. Same credentials as AXL.
SSH	SSH access enabled on CUCM nodes. A platform administrator (OS admin) account with privilege level 4 ("Advanced") is required.

The IMP module uses two protocols: AXL and SSH.

Protocol	Requirement
AXL	Activate Cisco AXL Web Service on the IMP publisher node. Same credentials as CUCM AXL.
SSH	SSH access enabled on IMP nodes. A platform administrator (OS admin) account with privilege level 4 ("Advanced") is required.

The CUC module uses two protocols: CUPI (REST) and SSH. There is no AXL/SOAP and no cluster concept — operations are scoped per host.

Protocol	Requirement
CUPI	REST is enabled by default on tcp/8443 (`/vmrest/`). Create a Unity Connection administrator account. For read-only use, the "System Administrator" role is sufficient. For write operations (provisioning users, call handlers, schedules, etc.), assign the appropriate role template covering the targeted CUPI endpoints.
SSH	SSH access enabled on CUC nodes. A platform administrator (OS admin) account with privilege level 4 ("Advanced") is required.

Nominative accounts — best practice

Create a dedicated account per AI-Bridge user on Cisco UC servers, rather than sharing a single service account. This enables per-user access control, end-to-end audit trail correlation, and credential isolation.

Network Requirements¶

Ensure the following ports are open on your firewalls:

Source	Destination	Port	Protocol	Purpose
AI Agent	Server	tcp/8443*	HTTPS	MCP client connectivity
Web-reverse Proxy	Server	tcp/8443*	HTTPS	(optional) MCP client connectivity proxified
Server	CUCM	tcp/8443	HTTPS	AXL/SOAP, RIS/SOAP
Server	CUCM	tcp/22	SSH	VOS CLI commands
Server	IMP	tcp/8443	HTTPS	AXL/SOAP
Server	IMP	tcp/22	SSH	VOS CLI commands
Server	CUC	tcp/8443	HTTPS	CUPI/REST
Server	CUC	tcp/22	SSH	VOS CLI commands
Server	SFTP Server	tcp/22	SSH	Backup export (optional)

* Default MCP_SERVER_PORT — configurable in .env.

No internet access required

The server never initiates outbound connections to the internet. Licensing, updates, and telemetry are fully offline.

Step 2 — Obtain Your License¶

AI-Bridge for Cisco UC requires a valid license to run. Each license is bound to the server hostname.

Retrieve your server hostname:

hostname -f

Hostname binding

The license is locked to the FQDN returned by hostname -f on the Docker host. Make sure this hostname is stable before ordering — any change (VM rename, DNS update, migration) will invalidate the license.

To order a license:

Contact contact@sourdeau.com with your organization name, intended deployment scope, and the server hostname (hostname -f).
You will receive a license.jwt file by secure transfer.
The license file is installed later (Step 5).

Demo license available

A time-limited demo license is available on request to evaluate the product in your environment before purchase.

License is version-agnostic

A valid license continues to work across upgrades — no re-issuance needed after an upgrade.

Step 3 — Install¶

3.1 Obtain the Package¶

AI-Bridge is distributed as a single archive:

ai-bridge-for-cisco-uc-<version>.tar.gz   # Release archive (config, docker-compose, scripts, pre-built Docker image)

The package is delivered by the editor via secure file transfer. No internet access is required on the target server. Contact contact@sourdeau.com to request a release.

3.2 Verify Package Integrity¶

Before installation, verify the archive using the DNS-published SHA-512 checksum:

From LinuxFrom Windows

# 1. Query the DNS TXT record published by the editor (uses a computer with public DNS resolution)
dig ai-bridge-for-cisco-uc-<version>.sha512.check.consulting.sourdeau.com txt +short

# 2. Compute the SHA-512 hash of the downloaded archive
sha512sum ai-bridge-for-cisco-uc-<version>.tar.gz

# 3. Compare both values — they must match exactly

# 1. Query the DNS TXT record published by the editor (uses a computer with public DNS resolution)
nslookup -q=txt ai-bridge-for-cisco-uc-<version>.sha512.check.consulting.sourdeau.com

# 2. Compute the SHA-512 hash of the downloaded archive
Get-FileHash -Algorithm SHA512 ai-bridge-for-cisco-uc-<version>.tar.gz

# 3. Compare both values — they must match exactly

Do not skip this step

If the values do not match, do not proceed. Contact contact@sourdeau.com immediately.

3.3 Extract¶

Extract the archive into your chosen installation directory on the Docker host:

# Create the installation directory and extract the package
mkdir ~/ai-bridge && cd ~/ai-bridge
tar -xzf /path/to/ai-bridge-for-cisco-uc-<version>.tar.gz

After extraction, the directory contains docker-compose.yml, .env, the pre-built Docker image, and all supporting files.

3.4 Load the Docker Image¶

Load the pre-built Docker image included in the archive (no internet access required):

docker load < ai-bridge-for-cisco-uc-<version>-docker-image.tar.gz

Verify the image is loaded:

docker images | grep ai-bridge

You should see ai-bridge-for-cisco-uc with the tag latest.

Docker Compose will use the pre-loaded image and mount runtime data from this directory.

Step 4 — Initial Configuration¶

4.1 Edit `.env`¶

The .env configuration file is included in the package, ready to edit:

nano .env

Key	What to set	Why
`HOST_FQDN`	Your server's FQDN (e.g. `mcp.domain.com`) — run `hostname -f`	Required — used as the Docker container hostname and must match the license hostname binding
`AUTH_CLIENTS`	Define at least one AI client (e.g. `claude:sub-claude-20260512:admin`)	Required — the server refuses to start without at least one client
`AUTH_ISSUER`	Your server's HTTPS URL (e.g. `https://mcp.domain.com:8443`)	Recommended — embedded in JWT tokens and OAuth metadata
`MCP_SERVER_SECURITY_ALLOWED_HOSTS`	Add your server FQDN (e.g. `localhost:,127.0.0.1:,mcp.domain.com:*`)	Recommended — used for DNS rebinding protection and TLS SAN entries
`MCP_SERVER_SECURITY_ALLOWED_ORIGINS`	Add your server origin (e.g. `https://mcp.domain.com:8443`)	Recommended — required for CORS / Origin header validation
`UID` / `GID`	Your service account's UID and GID (run `id -u && id -g`)	Required if your user is not UID 1000 — ensures the container can write to volumes

Full configuration reference

All available settings are documented in the Setup guide. You can reconfigure .env at any time — changes take effect on the next docker compose up -d.

4.2 Import a CA-Signed Certificate (optional)¶

By default, the server auto-generates a self-signed TLS certificate at first startup. If you already have a CA-signed certificate, you can deploy it before the first start:

# Place your certificate chain and private key in the secrets directory
cp /path/to/your-cert.crt secrets/server-ca-signed.crt
cp /path/to/your-cert.key secrets/server-ca-signed.key
chmod 600 secrets/server-ca-signed.key

If these files are present at startup, the server uses them instead of generating a self-signed certificate. No additional .env change is needed — the default paths in .env.example already point to secrets/server-ca-signed.crt and secrets/server-ca-signed.key.

Don't have a certificate yet?

No problem — start the server first with the auto-generated self-signed certificate (Step 5). You can generate a CSR and deploy a CA-signed certificate later (Step 5.3) without any data loss.

Step 5 — First Startup¶

5.1 Install the License¶

Before starting the server for the first time, copy the license file into the secrets/ directory:

cp /path/to/license.jwt secrets/license.jwt

No restart needed for renewals

The background license watchdog checks every 24 hours and automatically picks up a renewed license file.

5.2 Start the Container¶

docker compose up -d

Check the container is running and healthy:

docker compose ps
docker compose logs -f

On first startup, the server automatically:

Generates an RSA-4096 key pair — used for JWT signing, backup encryption, and license verification
Generates a self-signed TLS certificate — with SAN entries derived from MCP_SERVER_SECURITY_ALLOWED_HOSTS
Creates client directories — isolated secrets/, reports/, and custom/ subdirectory per client
Generates client bearer tokens — for each client in JWT auth mode (written to clients/<name>/secrets/.token)
Generates client oauth secrets — for each client in OAuth auth mode (written to clients/<name>/secrets/.secret)
Runs the software integrity check — against manifest.json and manifest.sig
Verifies the license — from secrets/license.jwt

After startup, the server logs its endpoint:

INFO  — Server started: https://0.0.0.0:8443/mcp/

All runtime data is persisted on the host via bind-mount volumes:

Host Path	Container Path	Purpose
`./.env`	`/app/.env`	Configuration (read-only)
`./secrets/`	`/app/secrets/`	RSA keys, TLS certificates
`./clients/`	`/app/clients/`	Client data, reports
`./logs/`	`/app/logs/`	Application & audit logs
`./backups/`	`/app/backups/`	Encrypted backups
`./servers-data/`	`/app/servers-data/`	AXL/RIS schemas, custom prompts
`./upgrade/`	`/app/upgrade/`	Upgrade packages

5.3 Deploy a CA-Signed Certificate (optional)¶

Once the server is running, you can replace the self-signed certificate with a CA-signed one. Generate a CSR directly inside the running container:

docker compose exec ai-bridge python scripts/certificate_generate_csr.py

The script reads your .env automatically to extract the FQDN and generates a CSR with proper SAN, Key Usage, and Extended Key Usage extensions. The output files are written to the secrets/ volume on the host.

Then sign the CSR with your internal CA (the exact openssl command is printed by the script), copy the signed certificate into place, and restart:

# After your CA signs the CSR:
cp /path/to/signed-cert.crt secrets/server-ca-signed.crt
docker compose restart

Self-signed certificate cleanup

When the server detects a valid CA-signed certificate at startup, the auto-generated self-signed certificate and its private key are automatically deleted from secrets/. (if openssl is available on the host):

openssl req -new -newkey rsa:4096 -nodes \
  -keyout secrets/server-ca-signed.key \
  -out secrets/server-ca-signed.csr \
  -subj "/C=FR/O=My Company/CN=mcp.domain.com" \
  -addext "subjectAltName=DNS:mcp.domain.com" \
  -addext "keyUsage=digitalSignature,keyEncipherment" \
  -addext "extendedKeyUsage=serverAuth"
chmod 600 secrets/server-ca-signed.key

Replace mcp.domain.com with your server's FQDN (the value from AUTH_ISSUER).

No downtime

The server runs with the self-signed certificate until the CA-signed certificate is deployed. A simple docker compose restart switches to the new certificate.

Step 6 — Connect Your AI Agent¶

6.1 Get Your Bearer Token¶

Your bearer token is generated at first startup. Retrieve it:

JWT modeOAuth 2.1 mode

cat clients/<client_name>/secrets/.token

Tokens are long-lived (default: 365 days) and can be revoked at any time — see the Operations guide

Request a short-lived token using your client credentials:

curl -sk -X POST https://mcp.domain.com:8443/token \
  -u "<client_id>:<client_secret>" \
  -d "grant_type=client_credentials"

The client_id is in clients/<name>/secrets/.uuid and client_secret in clients/<name>/secrets/.secret.

6.2 Configure Your First AI Agent¶

Add the MCP server to your agent's configuration file, using the token retrieved above.

Claude DesktopOpencodeCursorCustom / Other

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "ai-bridge-cisco-uc": {
      "url": "https://mcp.domain.com:8443/mcp/",
      "headers": {
        "Authorization": "Bearer <paste-token-here>"
      }
    }
  }
}

Edit opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "ai-bridge-cisco-uc": {
      "type": "remote",
      "url": "https://mcp.domain.com:8443/mcp/",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer <paste-token-here>"
      }
    }
  }
}

Edit ~/.cursor/mcp.json (or the project-level .cursor/mcp.json):

{
  "mcpServers": {
    "ai-bridge-cisco-uc": {
      "url": "https://mcp.domain.com:8443/mcp/",
      "headers": {
        "Authorization": "Bearer <paste-token-here>"
      }
    }
  }
}

Any MCP-compatible client using Streamable HTTP transport:

Endpoint : https://mcp.domain.com:8443/mcp/
Transport: streamable-http
Auth     : Authorization: Bearer <paste-token-here>

6.3 Trust the Server Certificate¶

Your AI agent must trust the MCP server's TLS certificate — whether it is the auto-generated self-signed certificate or a CA-signed certificate deployed in Step 5.3. Import the certificate into your client's trust store or configure the client to accept it.

6.4 Verify the Connection¶

Ask your AI agent to check MCP connectivity and list available tools.

You should see the MCP server status like MCP server is healthy and ready and the tools list (common_, infra_ and {products}_).

Check cisco-uc-mcp-server connectivity and list all tools available

What's Next?¶

Guide	What you'll find
Setup	Advanced setup configuration: Full `.env` reference, TLS configuration, transport hardening, audit logging, authentication modes, client management, RBAC profiles
Operations	Usual operations: Starting/stopping, monitoring, backup, upgrade, key rotation