How to Connect Claude Desktop to CoCoCo

There are two ways to connect Claude Desktop to CoCoCo. Almost everyone should use Option A — it’s a single file, takes about a minute, and needs no terminal, no Node.js installation, and no editing of configuration files. The configuration form shows a lot of fields, but only two are required: Endpoint URL and API key. Everything else is optional. Option B (the manual proxy) is kept only for advanced users who need full control.

Option A — Install the CoCoCo extension (recommended)

Current version: 1.2.1 · released 2026-08-31 Download: cococo.mcpb

CoCoCo ships as a Claude Desktop extension (a .mcpb file). Installing it is similar to adding a browser extension: you drag in one file and paste two values.

Before you start

• Claude Desktop installed — download from claude.ai/download
• Your Endpoint URL and an active API Token — both on the MCP Connection page in CoCoCo

You do not need Node.js or any other software — Claude Desktop brings its own runtime.

Step 1 — Copy your Endpoint URL and token from CoCoCo

1. In CoCoCo, open the MCP Connection settings.
2. Click Copy next to the Endpoint URL (it looks like https://<your-domain>/mcp).
3. Have an active API Token ready from the same page (it’s used as the bearer credential).

Step 2 — Install the extension

1. Download the cococo.mcpb file.
2. In Claude Desktop, open the menu (☰) in the top-left and go to File → Settings → Extensions.
3. Drag cococo.mcpb onto the Extensions page (or use Install Extension… and pick the file).
4. A security note may appear because the extension is distributed privately rather than through the public directory. This is expected — choose Install Anyway.

Step 3 — Enter your details

The form groups its fields per environment (“Instance 1”, “Instance 2”, “Instance 3”). For a single environment, fill in the first two fields and leave the rest as they are.

Required

• Endpoint URL — paste the URL you copied in Step 1 (e.g. https://<your-domain>/mcp)
• API key — paste your CoCoCo API token; it’s used as the bearer credential

Optional

• Name — a short label (e.g. “Prod”, “Staging”). It’s shown as a prefix on this environment’s tools once more than one environment is configured. Left empty, it’s derived from the host name.
• Enabled — on by default. Switching it off disables the environment without losing its URL and token: no connection, no tools.
• Read-only — off by default. When on, only tools that read data are offered; tools that modify data are hidden and refused.
• Tool filter — comma-separated patterns narrowing which tools reach Claude; a leading - excludes. Examples: -*_mutation,-train_* or describe_*,search_*,execute_sql. Display hygiene only — your server-side tool permissions remain the authority.

Leave the Instance 2 and Instance 3 fields empty if you use a single environment — see “Connecting more than one environment”.

After changing any of these fields, press Save and then open a new conversation.

Your token is stored encrypted in your operating system’s secure store (macOS Keychain / Windows Credential Manager), not in any plain-text file.

Step 4 — Verify

Open a new conversation, click the tools icon (hammer) at the bottom of the input field, and confirm that CoCoCo appears. Or ask Claude directly:

“What CoCoCo tools do you have access to?”

Connecting more than one environment

You can connect up to three CoCoCo environments at once. Fill in the Instance 2 block (and Instance 3 if you need it): Endpoint URL, API key, and ideally a name.

When more than one environment is connected, each environment’s tools are shown with its name as a prefix so they never clash — “Staging” becomes Staging__execute_sql, and “Sandbox DE” becomes Sandbox-DE__execute_sql (spaces turn into hyphens). With a single environment, no prefix is added.

Each environment has its own switches, so you can secure them differently — for example staging fully writable and the sandbox read-only.

Read-only and tool filters

Read-only is the simplest safeguard: with it on, every tool that modifies data disappears from the list, and a direct call is refused as well. This covers, among others, create_custom_app, update_custom_app, replace_in_file, create_version, import_workflow, train_ml_model, execute_graphql_mutation and the integration tools (create_integration_draft, update_integration_file, update_integration_manifest, publish_integration). Recommendation: set production environments to read-only and do your building in staging or sandbox.

Tool filter is not a security feature — it’s tidying up. With several environments connected, Claude sees a lot of tools. describe_*,search_*,execute_sql reduces an environment to research only; -*_mutation,-train_* hides specific tools. The real authority is always the server-side permissions of your API token.

Diagnostics

The extension ships a tool called cococo_diagnostics. Just ask Claude:

“Run CoCoCo diagnostics”

The output shows the extension version, every configured environment, its mode (full or read), how many tools are exposed versus hidden (with the reason), connection age, reconnect count, and the last error per environment. It’s the fastest way to confirm a setting actually took effect — and the first thing we ask for in support.

Updating

Privately distributed extensions don’t update automatically. When a new version of cococo.mcpb is provided, install the new file the same way — it replaces the previous version. Nothing changes on your machine unless you install an update.

Troubleshooting

• CoCoCo doesn’t appear: make sure you opened a new conversation after installing, and that the extension toggle is on under Settings → Extensions.
• A whole environment is missing: check the Enabled switch for that instance, and that you pressed Save afterwards.
• A single tool is missing: usually Read-only is on (write tools are hidden) or a Tool filter is matching. cococo_diagnostics names the reason per tool.
• Changes don’t take effect: press Save, then open a new conversation. If it still doesn’t apply, fully quit Claude Desktop (⌘Q) and reopen it.
• After restarting Claude Desktop: continue in a new conversation. A conversation that was open before the restart may no longer reach the tools, even though new conversations work normally.
• Authentication errors: re-check the API token (no extra spaces); confirm it hasn’t been revoked on the MCP / API Tokens page.
• Connection errors: confirm the Endpoint URL is correct and your machine can reach it. Internal .local addresses are only reachable on the local network; from outside, use the public URL shown in CoCoCo.
• Logs: the extension writes to ~/cococo-bridge.log. A line beginning cococo-bridge … started; environments=[…] confirms which environments were detected.

Option B — Manual proxy setup (advanced / fallback)

Use this only if you specifically need to run the connection yourself rather than via the extension. It requires Node.js and editing a configuration file.

Before you start

• Claude Desktop installed
• Node.js version 18 or higher
• An active API Token and your Endpoint URL (from the MCP Connection page)

How it works

Claude Desktop talks to local MCP servers over stdio — it launches a local process and exchanges JSON messages with it. Because the CoCoCo MCP server is a remote HTTPS endpoint, a small local script bridges between the two: it reads stdio messages from Claude Desktop, forwards them to the CoCoCo endpoint, and returns the responses.

Step 1 — Create the proxy script

Create a folder, e.g. ~/mcp-proxies/, and inside it a file cococo-proxy.mjs with the hardened bridge script (provided separately). This version parses streamed responses incrementally, enforces an absolute per-request timeout, handles each request independently, and shuts down cleanly — avoiding the stalls that simpler proxy scripts can run into.

The script reads its settings from environment variables (set in the config below), so you do not paste your token into the script itself:

• COCOCO_ENDPOINT — your Endpoint URL (e.g. https://<your-domain>/mcp)
• COCOCO_TOKEN — your API token

Step 2 — Find your Node.js path

Run which node. Note the output (e.g. /usr/local/bin/node, or an nvm path like /Users/yourname/.nvm/versions/node/v18.20.8/bin/node).

Step 3 — Configure Claude Desktop

Open (or create) the config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add a cococo server block (inside mcpServers), using your Node path, the path to the script, and your details:

{
  "mcpServers": {
    "cococo": {
      "command": "/usr/local/bin/node",
      "args": ["/Users/yourname/mcp-proxies/cococo-proxy.mjs"],
      "env": {
        "COCOCO_ENDPOINT": "https://<your-domain>/mcp",
        "COCOCO_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

Step 4 — Restart Claude Desktop

Save the file, then fully quit (⌘Q) and reopen Claude Desktop — closing the window is not enough.

Note: if you restart Claude Desktop while a conversation is open, continue in a new conversation afterwards. A conversation started before the restart may no longer reach the tools.

Step 5 — Verify

Open a new conversation, click the tools icon, and confirm CoCoCo appears — or ask “What CoCoCo tools do you have access to?”

Troubleshooting

• CoCoCo doesn’t appear: confirm the JSON is valid (a missing comma or bracket stops the file from loading); confirm the file paths exist; make sure you fully quit and restarted.
• Authentication errors: check COCOCO_TOKEN; confirm the token is still active.
• Node.js not found: re-run which node and update the command path; with nvm, ensure the right version is active.
• Connection errors: confirm the Endpoint URL is reachable.

What you can do once connected

• “List all my Custom Apps and tell me what each one does”
• “Build me a Custom App that shows a live overview of all active jobs”
• “What GraphQL query do I use to fetch jobs with status PRESS?”
• “Create a new KIOSK app for shopfloor job reporting”

The fastest use case is Custom App development — describe what you want, and Claude builds it directly on your platform.