On this page
Before you start
- Sign in to Colliedesk and open Settings → AI & agents → External AI agents.
- Name the token (for example "Claude Desktop on my laptop"), choose what it may do (follow a role, or pick permissions; leaving out sending to customers is a good start) and choose Create token. See Agent tokens.
- Copy the token. It starts with
cdk_agent_and is shown once.
The steps below use https://desk.example.com: put the address you open Colliedesk at in its place.
Under Connect your agent, Settings shows these steps for Claude Desktop with your address already in.
Connect
- Download the extension: colliedesk.mcpb.
- Open it (double-click), or drag it onto Settings → Extensions in Claude Desktop, and choose Install.
- Fill in Colliedesk address (
https://desk.example.com) and Agent token, and turn the extension on. Claude Desktop keeps the token in your system's credential store.
In a new chat, the tools menu lists Colliedesk.
The extension always holds the newest release of collie. Check a download against
SHA256SUMS, or prove it was built by
this repository with gh attestation verify colliedesk.mcpb -R colliedesk/colliedesk.
Without the extension
Any host that starts a local MCP server (Claude Desktop's claude_desktop_config.json among them)
can run collie mcp itself. Install collie on macOS or Linux:
mkdir -p ~/.local/bin
curl -fsSL https://github.com/colliedesk/colliedesk/releases/latest/download/collie_$(uname -s)_$(uname -m).tar.gz | tar -xz -C ~/.local/bin collie
echo "$HOME/.local/bin/collie"
or on Windows, in PowerShell:
$dir = "$env:LOCALAPPDATA\Programs\collie"
New-Item -ItemType Directory -Force $dir | Out-Null
Invoke-WebRequest "https://github.com/colliedesk/colliedesk/releases/latest/download/collie_Windows_$env:PROCESSOR_ARCHITECTURE.zip" -OutFile "$env:TEMP\collie.zip"
Expand-Archive -Force "$env:TEMP\collie.zip" $dir
"$dir\collie.exe"
The last line prints the full path of collie: the host needs it, because it does not read your
shell's PATH. Copy the token and save it in a file only you can read. On macOS:
(umask 077 && pbpaste > ~/.colliedesk-token)
On Linux, paste it into ~/.colliedesk-token with an editor, then chmod 600 ~/.colliedesk-token.
On Windows, in PowerShell (Windows does not check who can read the file; your user folder is
private to you):
Get-Clipboard | Set-Content -NoNewline "$HOME\.colliedesk-token"
Then give the host this server, with your paths and address (on Windows, the collie.exe path the
install printed and C:\Users\you\.colliedesk-token, with each \ written twice in JSON):
{
"mcpServers": {
"colliedesk": {
"command": "/Users/you/.local/bin/collie",
"args": [
"mcp",
"--url",
"https://desk.example.com",
"--token-file",
"/Users/you/.colliedesk-token"
]
}
}
}
collie mcp takes the token from --token-file or the COLLIEDESK_TOKEN variable, never from its
arguments, which other programs can read. It refuses http:// addresses except on this computer.
When something is wrong it answers the call with what to do (a revoked token, a wrong address, a
server that cannot be reached) and writes one line to the host's log. On Windows the token file's
permissions are not checked.
A custom connector instead
Some Claude organizations see Request headers when an Owner adds a custom connector. That connector reaches your Colliedesk from Anthropic's servers, so it must be reachable from the internet, and everyone in the organization uses the one token the Owner entered: every action is recorded as that token's person. Prefer the extension.
Try it
Ask Claude Desktop: "Who am I in Colliedesk?" It calls colliedesk_whoami, which answers
with your name, your workspace, your roles, the token's permissions and the tools it may use. Then, for example: "Triage the
open conversations nobody owns: tag billing questions with billing and leave a note with a
summary."
What the agent can do
Colliedesk has 250 tools. The agent acts as you, with the permissions you gave the token, never more than you hold now. A tool it has the permissions for runs at once; any other is refused with the permission it lacks. See Roles and permissions.
Every tool and what it needs: Connect an AI agent (MCP).
Remove it
In Claude Desktop, Settings → Extensions, remove Colliedesk. Without the extension, delete
the colliedesk entry from the host's configuration and ~/.colliedesk-token. Then revoke the token in Settings → AI & agents → External AI agents (its ⋯ menu, Revoke): it stops working at once, wherever it was
copied.
Other hosts
- Claude Code
- Codex
- Cursor
- VS Code
- Agent skills: triage, draft replies and chase pending conversations
Was this page helpful?
Updated
This page is rendered from the repository. Spot a mistake? Open an issue or a pull request.