code-engine-mcp-server 1.0.4 → 1.0.7

package/README.md

@@ -5,32 +5,43 @@
 Model Context Protocol (MCP) server for IBM Code Engine and Docker/Podman integration.
 It enables AI assistants to build, run, push, and deploy containerized workloads with a single MCP server.
 
-[![MCP](https://img.shields.io/badge/MCP-Server-blue)](#)
-[![IBM Cloud](https://img.shields.io/badge/IBM%20Cloud-Code%20Engine-1261FE)](#)
+[![MCP](https://img.shields.io/badge/MCP-Server-blue)](https://github.com/markusvankempen/code-engine-mcp-server)
+[![IBM Cloud](https://img.shields.io/badge/IBM%20Cloud-Code%20Engine-1261FE)](https://cloud.ibm.com/codeengine/overview)
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-339933?logo=nodedotjs&logoColor=white)](#prerequisites)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![VS Code Marketplace](https://img.shields.io/badge/VS%20Code-Marketplace-007ACC?logo=visualstudiocode&logoColor=white)](https://marketplace.visualstudio.com/items?itemName=MarkusvanKempen.code-engine-mcp)
+[![Open VSX](https://img.shields.io/badge/Open%20VSX-Registry-C160EF?logo=eclipseide&logoColor=white)](https://open-vsx.org/extension/markusvankempen/code-engine-mcp)
+[![npm](https://img.shields.io/badge/npm-code--engine--mcp--server-CB3837?logo=npm&logoColor=white)](https://www.npmjs.com/package/code-engine-mcp-server)
+
+## How It Works
+
+```mermaid
+flowchart TD
+    A([AI Assistant\nCopilot / Claude / Cline]) -->|MCP JSON-RPC| B[Code Engine MCP Server]
+
+    B --> C{Tool Category}
+
+    C -->|Container Tools| D[Docker / Podman]
+    C -->|Registry Tools| E[IBM Container Registry\nus.icr.io]
+    C -->|Code Engine Tools| F[IBM Code Engine\nREST API]
+    C -->|Procedures| G[Multi-step Workflows]
+
+    D -->|build / push / validate| E
+    E -->|image reference| F
+
+    G -->|proc_build_push_deploy| D
+    G -->|proc_build_run_and_deploy| F
+
+    F --> H[(Projects\nApps\nBuilds\nJobs\nSecrets\nDomains)]
+
+    H -->|ready| I([Live App\nhttps://app.region.codeengine.appdomain.cloud])
+
+    style A fill:#1261FE,color:#fff
+    style B fill:#0f3460,color:#fff
+    style G fill:#7b2d8b,color:#fff
+    style I fill:#198038,color:#fff
+```
 
-## 📚 Table of Contents
-
-- [What You Get](#what-you-get)
-- [Quick Start](#quick-start)
-- [Deploy Your First App](#deploy-your-first-app)
-- [Documentation](#documentation)
-- [Project Structure](#project-structure)
-- [Features](#features)
-- [Configuration](#configuration)
-- [npm and MCP Registry](#npm-and-mcp-registry)
-- [Example Prompts](#example-prompts)
-- [Available Tools](#available-tools)
-- [Environment Variables](#environment-variables)
-- [Prerequisites](#prerequisites)
-- [Development](#development)
-- [Troubleshooting](#troubleshooting)
-- [Security](#security)
-- [License](#license)
-- [Contributing](#contributing)
-- [Author](#author)
-- [Support](#support)
 
 ## ✨ What You Get
 
@@ -55,7 +66,29 @@ node build/index.js
 
 Then configure your MCP client using one of the examples in the Configuration section below.
 
-## � Deploy Your First App
+## 🤖 The Agentic Experience (No Docker/Code Engine Lingo Needed)
+
+The true power of this MCP server is that **you don't need to know Docker or Code Engine commands**. You can simply state your goal, and the LLM will discover the environment, run the pipeline, and fix issues autonomously. 
+
+Here is an example interaction from a real session:
+
+**User:**
+> "I have an app in the `developer-splash` folder. Deploy it to my Code Engine project."
+
+**Assistant's Autonomous Thought Process:**
+1. *Discovery:* "Let me check what projects and namespaces exist... Found project `markus-app-v2-toronto` and namespace `mvk-code-engine`."
+2. *Prerequisites:* "No pull secret in this project yet. I'll get the API key from the `.env` file and create the secret `icr-pull-secret`."
+3. *Execution:* "Now I'll run the full pipeline: build → push → deploy → wait."
+4. *Validation:* "It's deployed but stuck at 'deploying'. Let me check the logs... The container is running but the readiness probe is failing."
+5. *Self-Correction:* "Ah, the `sed` pattern in the Dockerfile didn't match nginx alpine's default config format for port 80. I'll fix the Dockerfile with a regex-safe `sed` and rebuild."
+6. *Completion:* "App is live! 🎉 Status: ready."
+
+**Assistant Response to User:**
+> "Your app is deployed and live at: `https://developer-splash.29m5mrru3s3n.ca-tor.codeengine.appdomain.cloud`. I had to fix a minor port configuration issue in your Dockerfile, but it is successfully running now!"
+
+With this MCP server, the AI acts as an expert DevOps engineer pairing with you.
+
+## Deploy Your First App
 
 This walks through deploying the included [Star Wars splash page example](./examples/starwars-splash/) — a static nginx container — entirely through the MCP server.
 
@@ -301,14 +334,216 @@ push it, then deploy it to Code Engine project <project-id> with pull secret icr
 Tell me the public URL and confirm the instance is running.
 ```
 
-## �📖 Documentation
+---
+
+## 🌐 Host Any MCP Server on Code Engine
+
+You can use **this** MCP server to deploy **another** MCP server to Code Engine — no CLI, no Dockerfile, no YAML. The key ingredient is [`supergateway`](https://github.com/supercorp-ai/supergateway): a tiny bridge that wraps any STDIO-based MCP server as an HTTP + SSE endpoint, making it accessible to any remote client.
+
+> Credit: [Jeremias Werner & Enrico Regge — IBM Cloud Code Engine](https://community.ibm.com/community/user/blogs/jeremias-werner/2025/04/30/code-engine-mcp-server)
+
+```
+Your AI Assistant
+    │  MCP JSON-RPC (STDIO, local)
+    ▼
+code-engine-mcp-server  ──► ce_create_application
+                                     │
+                                     ▼
+                         Code Engine App
+                         image: docker.io/supercorp/supergateway
+                         args:  --stdio "npx -y <any-mcp-server>"
+                                --outputTransport sse
+                                     │  HTTPS + SSE  (public URL)
+                                     ▼
+                         Any remote MCP client
+                         (Claude Desktop, Cursor, VS Code, …)
+```
+
+Any STDIO MCP server becomes a remotely accessible, auto-scaling cloud service — with no custom infrastructure.
+
+This example deploys [`@tokenizin/mcp-npx-fetch`](https://www.npmjs.com/package/@tokenizin/mcp-npx-fetch), an MCP server that lets an AI assistant fetch content from public URLs.
+
+The example files live in [examples/mcp-server-supergateway/](./examples/mcp-server-supergateway/).
+
+### Step 1 — Deploy the hosted MCP server
+
+Ask your assistant:
+```
+Deploy a hosted MCP fetch server to my Code Engine project <project-id>.
+Use image docker.io/supercorp/supergateway on port 8000.
+Startup args: --stdio "npx -y @tokenizin/mcp-npx-fetch" --outputTransport sse
+Name it "mcp-fetch-server". No pull secret needed.
+```
+
+This calls `ce_create_application`:
+```json
+{
+  "project_id": "<your-project-id>",
+  "name": "mcp-fetch-server",
+  "image": "docker.io/supercorp/supergateway",
+  "port": 8000,
+  "run_args": ["--stdio", "npx -y @tokenizin/mcp-npx-fetch", "--outputTransport", "sse"]
+}
+```
+
+**MCP response — `ce_create_application`:**
+```json
+{
+  "name": "mcp-fetch-server",
+  "resource_type": "app_v2",
+  "status": "deploying",
+  "image_reference": "docker.io/supercorp/supergateway",
+  "image_port": 8000,
+  "scale_min_instances": 0,
+  "scale_max_instances": 10,
+  "endpoint": "https://mcp-fetch-server.<subdomain>.<region>.codeengine.appdomain.cloud",
+  "status_details": {
+    "latest_created_revision": "mcp-fetch-server-00001",
+    "latest_ready_revision": null
+  }
+}
+```
+
+> No pull secret is needed — `docker.io/supercorp/supergateway` is a public image. Code Engine scales to zero when idle; you pay only for actual requests.
+
+### Step 2 — Wait for the app to be ready
+
+Ask your assistant:
+```
+Wait for mcp-fetch-server in project <project-id> to be ready
+```
+
+This calls `ce_wait_for_app_ready`:
+```json
+{
+  "project_id": "<your-project-id>",
+  "app_name": "mcp-fetch-server",
+  "timeout_seconds": 120
+}
+```
+
+**MCP response — `ce_wait_for_app_ready`:**
+```json
+{
+  "app_name": "mcp-fetch-server",
+  "status": "ready",
+  "endpoint": "https://mcp-fetch-server.<subdomain>.<region>.codeengine.appdomain.cloud",
+  "elapsed_seconds": 34,
+  "poll_history": [
+    { "attempt": 1, "status": "deploying", "elapsed_seconds": 10 },
+    { "attempt": 2, "status": "deploying", "elapsed_seconds": 20 },
+    { "attempt": 3, "status": "ready",     "elapsed_seconds": 34 }
+  ]
+}
+```
+
+### Step 3 — Verify the running instance
+
+Ask your assistant:
+```
+List the running instances of mcp-fetch-server in project <project-id>
+```
+
+This calls `ce_list_app_instances`:
+
+**MCP response — `ce_list_app_instances`:**
+```json
+{
+  "instances": [
+    {
+      "name": "mcp-fetch-server-00001-deployment-abc123",
+      "revision": "mcp-fetch-server-00001",
+      "status": "running",
+      "restart_count": 0,
+      "started_at": "2026-05-09T12:01:44Z"
+    }
+  ]
+}
+```
+
+### Step 4 — Connect your MCP client
+
+Use [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) to bridge the HTTP+SSE endpoint back to STDIO for local clients.
+
+**VS Code `mcp.json`:**
+```json
+{
+  "servers": {
+    "fetch": {
+      "command": "npx",
+      "args": [
+        "mcp-remote",
+        "https://mcp-fetch-server.<subdomain>.<region>.codeengine.appdomain.cloud/sse"
+      ]
+    }
+  }
+}
+```
+
+**Claude Desktop `claude_desktop_config.json`:**
+```json
+{
+  "mcpServers": {
+    "fetch": {
+      "command": "npx",
+      "args": [
+        "mcp-remote",
+        "https://mcp-fetch-server.<subdomain>.<region>.codeengine.appdomain.cloud/sse"
+      ]
+    }
+  }
+}
+```
+
+### Step 5 — Test the endpoint
+
+Verify the server is live and streaming:
+```bash
+curl -N https://mcp-fetch-server.<subdomain>.<region>.codeengine.appdomain.cloud/sse
+```
+
+Or open it in the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
+```bash
+npx @modelcontextprotocol/inspector
+# Connect via SSE → paste the Code Engine URL
+```
+
+Once connected, you will see the `fetch` tool listed and can invoke it directly from the inspector.
+
+### Full one-shot prompt
+
+```
+Deploy a hosted MCP fetch server to my Code Engine project <project-id>.
+Use image docker.io/supercorp/supergateway on port 8000 with no pull secret.
+run_args: --stdio "npx -y @tokenizin/mcp-npx-fetch" --outputTransport sse
+Name it "mcp-fetch-server", wait for it to be ready, and give me the /sse URL
+so I can add it to my mcp.json.
+```
+
+See [examples/mcp-server-supergateway/](./examples/mcp-server-supergateway/) for the ready-to-use client config file.
 
+### Deploy any other STDIO MCP server
+
+The same pattern works for any `npx`-runnable MCP server — just swap the `--stdio` argument:
+
+| MCP Server | `--stdio` argument |
+|---|---|
+| Fetch | `npx -y @tokenizin/mcp-npx-fetch` |
+| Filesystem | `npx -y @modelcontextprotocol/server-filesystem /data` |
+| Brave Search | `npx -y @modelcontextprotocol/server-brave-search` |
+| Your own server | `node /app/server.js` |
+
+---
+
+## Documentation
+
+- [Setup Instructions](./docs/SETUP_INSTRUCTIONS.md)
+- [MCP Inspector Troubleshooting](./docs/MCP_INSPECTOR_TROUBLESHOOTING.md)
 - [Code Engine API Reference](./docs/CODE_ENGINE_API_REFERENCE.md)
 - [API Call Scenarios](./docs/API_CALL_SCENARIOS.md)
-- [Setup Instructions](./docs/SETUP_INSTRUCTIONS.md)
 - [Client README](./docs/CLIENT_README.md)
 - [Cline MCP Config Example](./docs/CLINE_CONFIG_EXAMPLE.json)
-- [VS Code MCP extension](./vscode-extension/README.md) (registers this server via settings; no `mcp.json` required for the default `npx` flow)
+- [VS Code MCP extension](./vscode-extension/README.md)
 - [Code of Conduct](./docs/CODE_OF_CONDUCT.md)
 - [Contributing Guide](./docs/CONTRIBUTING.md)
 - [Maintainers](./docs/MAINTAINERS.md)
@@ -317,20 +552,27 @@ Tell me the public URL and confirm the instance is running.
 
 ```text
 code-engine-mcp-server/
-├── api/
-│   └── code-engine-openapi.yaml      # OpenAPI reference used for API coverage
+├── api/                              # OpenAPI reference used for API coverage
 ├── build/                            # Compiled JavaScript output
-├── docs/                             # API references and setup guides
-├── internal/                         # Internal release/publishing notes
+├── docs/                             # API references, client guides, community files
+│   ├── API_CALL_SCENARIOS.md
+│   ├── CODE_ENGINE_API_REFERENCE.md
+│   ├── MCP_INSPECTOR_TROUBLESHOOTING.md
+│   ├── SETUP_INSTRUCTIONS.md
+│   ├── CODE_OF_CONDUCT.md
+│   ├── CONTRIBUTING.md
+│   └── MAINTAINERS.md
+├── examples/
+│   ├── developer-splash/             # nginx static container example
+│   ├── starwars-splash/              # nginx Star Wars crawl example
+│   └── mcp-server-supergateway/      # Host any MCP server on Code Engine via supergateway
+├── internal/                         # Internal release notes
 ├── src/                              # Main TypeScript source code
 ├── CHANGELOG.md                      # Release history
-├── CODE_OF_CONDUCT.md                # Community guidelines
-├── CONTRIBUTING.md                   # Contribution workflow
 ├── LICENSE                           # Project license
-├── MAINTAINERS.md                    # Maintainer list
 ├── README.md                         # Project overview and usage
 ├── mcp.example.json                  # Example MCP client configuration
-├── vscode-extension/                 # Optional VS Code extension (MCP definition provider)
+├── vscode-extension/                 # Optional VS Code extension
 ├── package.json                      # npm package metadata and scripts
 ├── server.json                       # MCP Registry metadata
 └── tsconfig.json                     # TypeScript configuration
@@ -367,6 +609,7 @@ code-engine-mcp-server/
 - ✅ TLS secrets from Let's Encrypt / certbot PEM files (`ce_create_tls_secret_from_pem`)
 - ✅ TLS cert renewal in-place without disrupting domain mappings (`ce_renew_tls_secret_from_pem`)
 - ✅ Update any secret in-place (`ce_update_secret`)
+- ✅ Refresh ICR pull secret with current API key credentials (`ce_refresh_icr_pull_secret`) — fixes `no_revision_ready` failures caused by stale registry credentials without needing the CLI
 - ✅ Wait for app deployment or build run to complete (`ce_wait_for_app_ready`, `ce_wait_for_build_run`)
 - ✅ IAM token info and diagnostics (`iam_get_token_info`)
 - ✅ Create ICR namespaces via REST API (`icr_create_namespace`)
@@ -378,79 +621,188 @@ code-engine-mcp-server/
 
 ## ⚙️ Configuration
 
-### VS Code — IBM Code Engine MCP extension (optional)
+### Getting an IBM Cloud API key
+
+All Code Engine and ICR operations require an IBM Cloud API key. Get one at:
+**[IBM Cloud IAM → API keys](https://cloud.ibm.com/iam/apikeys)** → **Create an IBM Cloud API key**.
+
+Store the key somewhere safe (password manager). You will paste it into one of the configuration paths below.
+
+---
+
+### Path A — VS Code extension (recommended)
+
+The [IBM Code Engine MCP extension](https://marketplace.visualstudio.com/items?itemName=MarkusvanKempen.code-engine-mcp) handles everything: server startup, API key storage, and MCP registration — no manual `mcp.json` editing required.
+
+**Install from the Marketplace:**
+
+| IDE / Platform | Install link |
+|---|---|
+| VS Code | [marketplace.visualstudio.com](https://marketplace.visualstudio.com/items?itemName=MarkusvanKempen.code-engine-mcp) |
+| Cursor / Theia / Gitpod / Codium | [open-vsx.org](https://open-vsx.org/extension/markusvankempen/code-engine-mcp) |
+| From a local `.vsix` | **Command Palette** → **Extensions: Install from VSIX…** |
+
+**Set your API key (required before any tool works):**
 
-The extension in `vscode-extension/` registers this MCP server with VS Code using the **MCP server definition provider** API (VS Code **1.101+**). You do **not** need a workspace `.vscode/mcp.json` entry for the default flow: the server is started with `npx -y code-engine-mcp-server` and your API key from settings.
+1. Open the **IBM Code Engine MCP** sidebar panel (cloud icon in the Activity Bar)
+2. Paste your IBM Cloud API key and click **Save**  
+   _(The key is stored in VS Code global settings — encrypted by the OS keychain, never in a plaintext file)_
+3. Optionally change the region (default: `us-south`) in the same panel
+4. Click **Configure MCP** — this writes the server entry to the global `mcp.json` and restarts VS Code's MCP server list
+5. Click **Run Diagnostics** to confirm everything is wired up:
+   - ✅ Node.js found on PATH
+   - ✅ API key configured
+   - ✅ MCP server registered
+   - ✅ Tool list discovered
 
-1. Install the extension (from a `.vsix` built with `npm run package` inside `vscode-extension/`, or from the Marketplace when published).
-2. Ensure **Node.js** is installed and `npx` is on your `PATH`.
-3. Open **Settings** and search for **IBM Code Engine MCP**, or edit `settings.json` directly:
-   - `codeEngineMcp.apiKey` — your IBM Cloud API key (**required**; until this is set, the extension contributes no MCP server).
-   - `codeEngineMcp.region` — IBM Cloud region (optional, default `us-south`). Passed as `IBMCLOUD_REGION` to the server.
+After step 4 you can open GitHub Copilot Chat and immediately ask:
+> *"List all my Code Engine projects"*
 
-The extension sets `IBMCLOUD_API_KEY` and `IBMCLOUD_REGION` for the spawned process. Use GitHub Copilot and MCP in VS Code as described in the [Copilot documentation](https://code.visualstudio.com/docs/copilot/copilot-chat).
+> **Tip:** If Copilot can't see the tools after installing, run **Command Palette → Reload Window** once.
 
 More detail: [vscode-extension/README.md](./vscode-extension/README.md).
 
 ---
 
-### 1) GitHub Copilot (VS Code) — `mcp.json` (workspace)
+### Path B — Pure MCP config (no extension)
+
+Use this path with **any** MCP-capable client: GitHub Copilot without the extension, Cline, Claude Desktop, Cursor, etc.
+
+#### Where to put the API key (choose one approach)
+
+**Option 1 — Shell environment variable (most secure)**
+
+Copy the provided template and fill in your key:
+
+```bash
+cp .env.example .env          # copy template (already in .gitignore)
+# edit .env → set IBMCLOUD_API_KEY=your-key
+source .env                   # load into current shell session
+```
 
-Copy `mcp.example.json` to `.vscode/mcp.json` in your workspace root:
+Or add the export permanently to your shell profile so every new terminal has it:
 
 ```bash
-cp mcp.example.json ../.vscode/mcp.json
+# ~/.zshrc or ~/.bash_profile
+export IBMCLOUD_API_KEY="your-ibm-cloud-api-key-here"
+```
+
+See [.env.example](.env.example) for all available variables (`IBMCLOUD_REGION`, `CONTAINER_RUNTIME`, `DEBUG`).
+
+Then reference the variable in the MCP config without embedding the value:
+
+```json
+{
+  "servers": {
+    "code-engine": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "code-engine-mcp-server@latest"],
+      "env": {
+        "IBMCLOUD_API_KEY": "${env:IBMCLOUD_API_KEY}",
+        "IBMCLOUD_REGION": "us-south"
+      }
+    }
+  }
+}
+```
+
+> `${env:VARIABLE}` is VS Code's input substitution syntax — it reads the value from your shell environment at startup so your API key is never stored in the file.
+
+**Option 2 — VS Code input variable (prompted on connect)**
+
+VS Code can prompt you for the API key when it starts the server — great for shared machines:
+
+```json
+{
+  "inputs": [
+    {
+      "id": "ibmcloud-api-key",
+      "type": "promptString",
+      "description": "IBM Cloud API key",
+      "password": true
+    }
+  ],
+  "servers": {
+    "code-engine": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "code-engine-mcp-server@latest"],
+      "env": {
+        "IBMCLOUD_API_KEY": "${input:ibmcloud-api-key}",
+        "IBMCLOUD_REGION": "us-south"
+      }
+    }
+  }
+}
 ```
 
-Then edit `.vscode/mcp.json` and replace the placeholder with your IBM Cloud API key:
+**Option 3 — Inline value (simplest, least secure)**
+
+Paste the key directly. **Never commit this file to git.**
 
 ```json
 {
-    "servers": {
-        "code-engine": {
-            "type": "stdio",
-            "command": "node",
-            "args": [
-                "${workspaceFolder}/code-engine-mcp-server/build/index.js"
-            ],
-            "env": {
-                "IBMCLOUD_API_KEY": "your-ibm-cloud-api-key-here"
-            }
-        }
+  "servers": {
+    "code-engine": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "code-engine-mcp-server@latest"],
+      "env": {
+        "IBMCLOUD_API_KEY": "your-ibm-cloud-api-key-here",
+        "IBMCLOUD_REGION": "us-south"
+      }
     }
+  }
 }
 ```
 
-Restart the server: **Cmd+Shift+P** -> **"MCP: Restart Server"** -> `code-engine`.
+> **Security:** Add the config file to `.gitignore`. For workspace configs, use `${env:...}` or `${input:...}` instead of inline values.
 
-> **Security:** Add `.vscode/mcp.json` to your `.gitignore` to avoid committing your API key.
+---
+
+#### 1) GitHub Copilot (VS Code) — workspace `mcp.json`
+
+Create `.vscode/mcp.json` in your workspace root (or copy `mcp.example.json`):
+
+```bash
+cp mcp.example.json .vscode/mcp.json
+echo '.vscode/mcp.json' >> .gitignore
+```
 
-Get your API key at [IBM Cloud IAM → API keys](https://cloud.ibm.com/iam/apikeys).
+Paste one of the API key options above. Then restart the server:
+**Cmd+Shift+P** → **MCP: Restart Server** → `code-engine`.
+
+Alternatively, use the **global** MCP config at `~/Library/Application Support/Code/User/mcp.json` (macOS) so the server is available in every workspace without a per-project file.
 
 ---
 
-### 2) Cline (VS Code Extension)
+#### 2) Cline (VS Code Extension)
 
-1. Open VSCode Settings (Cmd/Ctrl + ,)
-2. Search for "Cline: MCP Settings"
-3. Click "Edit in settings.json"
-4. Add the configuration:
+1. Open VS Code Settings (`Cmd+,`)
+2. Search for **Cline: MCP Settings** → **Edit in settings.json**
+3. Add:
 
 ```json
 {
   "cline.mcpServers": {
     "code-engine": {
-      "command": "node",
-      "args": ["/absolute/path/to/code-engine-mcp-server/build/index.js"],
+      "command": "npx",
+      "args": ["-y", "code-engine-mcp-server@latest"],
       "env": {
-        "IBMCLOUD_API_KEY": "your-api-key-here"
+        "IBMCLOUD_API_KEY": "your-api-key-here",
+        "IBMCLOUD_REGION": "us-south"
       }
     }
   }
 }
 ```
 
-### 3) Claude Desktop
+> Prefer `${env:IBMCLOUD_API_KEY}` if your shell exports the key, so it never appears in `settings.json`.
+
+---
+
+#### 3) Claude Desktop
 
 Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
@@ -458,22 +810,29 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
 {
   "mcpServers": {
     "code-engine": {
-      "command": "node",
-      "args": ["/absolute/path/to/code-engine-mcp-server/build/index.js"],
+      "command": "npx",
+      "args": ["-y", "code-engine-mcp-server@latest"],
       "env": {
-        "IBMCLOUD_API_KEY": "your-api-key-here"
+        "IBMCLOUD_API_KEY": "your-api-key-here",
+        "IBMCLOUD_REGION": "us-south"
       }
     }
   }
 }
 ```
 
-## npm and MCP Registry
+> Restart Claude Desktop after saving. The server starts on demand when Claude needs a tool.
+
+## Install & Registry Links
 
-Use the published package from npm or browse the MCP Registry listing:
+| Platform | Link |
+|---|---|
+| **npm** (MCP server package) | [code-engine-mcp-server](https://www.npmjs.com/package/code-engine-mcp-server) |
+| **VS Code Marketplace** (extension) | [MarkusvanKempen.code-engine-mcp](https://marketplace.visualstudio.com/items?itemName=MarkusvanKempen.code-engine-mcp) |
+| **Open VSX Registry** (Theia / Gitpod / Cursor) | [markusvankempen.code-engine-mcp](https://open-vsx.org/extension/markusvankempen/code-engine-mcp) |
+| **MCP Registry** | [io.github.markusvankempen/code-engine-mcp-server](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.markusvankempen%2Fcode-engine-mcp-server) |
 
-- [npm package: code-engine-mcp-server](https://www.npmjs.com/package/code-engine-mcp-server)
-- [MCP Registry entry: io.github.markusvankempen/code-engine-mcp-server](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.markusvankempen%2Fcode-engine-mcp-server)
+The **VS Code extension** is the easiest starting point — it handles server startup, API key storage, and MCP registration automatically. Use the **npm package** directly if you prefer a manual MCP config (Cline, Claude Desktop, Cursor, or any other client).
 
 ## 💬 Example Prompts
 
@@ -537,7 +896,7 @@ Tell me what CNAME value to set in DNS.
 
 ## 🛠️ Available Tools
 
-62 tools total: 9 container tools + 4 ICR tools + 45 Code Engine tools + 1 IAM tool + 3 procedures.
+63 tools total: 9 container tools + 4 ICR tools + 46 Code Engine tools + 1 IAM tool + 3 procedures.
 
 > **Procedures** bundle multiple tools into a single call. Use them for common end-to-end workflows.
 
@@ -579,8 +938,8 @@ Tell me what CNAME value to set in DNS.
 |------|-------------|----------------|
 | `ce_list_applications` | List applications in a project | `project_id` |
 | `ce_get_application` | Get application details and public URL | `project_id`, `app_name` |
-| `ce_create_application` | Deploy a new application | `project_id`, `name`, `image`, `image_secret`, `port`, `env_vars` |
-| `ce_update_application` | Update image, scaling, env, pull secret | `project_id`, `app_name`, `image`, `image_secret`, `scale_*` |
+| `ce_create_application` | Deploy a new application | `project_id`, `name`, `image`, `image_secret`, `port`, `env_vars`, `run_args`, `run_commands` |
+| `ce_update_application` | Update image, scaling, env, pull secret, run args | `project_id`, `app_name`, `image`, `image_secret`, `scale_*`, `run_args`, `run_commands` |
 | `ce_delete_application` | Delete an application | `project_id`, `app_name` |
 | `ce_list_app_instances` | List all running instances with status | `project_id`, `app_name` |
 | `ce_get_app_instance` | Get status details for a specific instance | `project_id`, `app_name`, `instance_name` |
@@ -614,7 +973,7 @@ Tell me what CNAME value to set in DNS.
 | `ce_create_job_run` | Submit a job run | `project_id`, `job_name` |
 | `ce_delete_job_run` | Delete a job run | `project_id`, `job_run_name` |
 
-### Code Engine: Secrets (7)
+### Code Engine: Secrets (8)
 
 | Tool | Description | Key Parameters |
 |------|-------------|----------------|
@@ -623,6 +982,7 @@ Tell me what CNAME value to set in DNS.
 | `ce_create_secret` | Create a secret | `project_id`, `name`, `format`, `data` |
 | `ce_update_secret` | Update an existing secret in-place (PATCH) | `project_id`, `secret_name`, `data` |
 | `ce_delete_secret` | Delete a secret | `project_id`, `secret_name` |
+| `ce_refresh_icr_pull_secret` | Delete and recreate an ICR registry pull secret using the server's own API key — fixes stale-credential failures without needing the CLI | `project_id`, `secret_name` (default: `icr-pull-secret`), `icr_host` |
 | `ce_create_tls_secret_from_pem` | Create a TLS secret from PEM files | `project_id`, `secret_name`, `cert_pem_path`, `key_pem_path` |
 | `ce_renew_tls_secret_from_pem` | Renew an existing TLS secret from updated PEM files | `project_id`, `secret_name`, `cert_pem_path`, `key_pem_path` |