{
  "markdown": "<!--\nSEO: IBM Code Engine MCP Server | Deploy containers to IBM Cloud Code Engine | MCP · AI Agents · DevOps\nKeywords: code-engine, code-engine-mcp, ibm-code-engine, ibm-cloud, ibm-container-registry, icr, serverless, container-deployment, mcp, mcp-server, model-context-protocol, docker, podman, typescript, vscode-extension, npm-package, npx, stdio\nAlso: deploy to code engine, ibm ce mcp, ai deploy containers, copilot mcp server, cursor mcp ibm cloud, claude mcp deployment, github copilot ibm cloud, model context protocol deployment, watsonx orchestrate mcp, code engine ai agent\n-->\n\n# IBM Code Engine MCP Server\n\n![Code Engine MCP Server — IBM Cloud rocket and container logo](https://github.com/markusvankempen/code-engine-mcp-server/raw/main/images/code_engine_mcp_logo.png)\n\n**MCP server for IBM Code Engine — build, push, and deploy containers from Cursor, Copilot, Claude, and Cline using natural language.**\n\n> **Current release: v1.5.0** — Projects & Resources Tree View in the sidebar (apps, jobs, builds, secrets, config maps with inline actions), Activity sidebar view, plus 8 new operational tools (events, build-run logs, app restart, job resubmit/cancel, project quotas).\n\n**Search terms:** `code-engine-mcp` · `ibm-code-engine` · `ibm-cloud` · `ibm-container-registry` · `mcp-server` · `model-context-protocol` · `cursor` · `github-copilot` · `claude-desktop` · `cline` · `docker` · `podman` · `serverless` · `container-deployment` · `typescript` · `npx` · `ai-agents` · `devops` · `cloud-native` · `watsonx-orchestrate`\n\n---\n\n**Author:** Markus van Kempen | [markus.van.kempen@gmail.com](mailto:markus.van.kempen@gmail.com) · [markusvankempen.github.io](https://markusvankempen.github.io/)\n*No bug too small, no syntax too weird.*\n\n---\n\n[![MCP](https://img.shields.io/badge/MCP-Server-blue)](https://github.com/markusvankempen/code-engine-mcp-server)\n[![Release](https://img.shields.io/badge/release-v1.5.0-blue)](https://github.com/markusvankempen/code-engine-mcp-server/blob/main/CHANGELOG.md#150---2026-07-04)\n[![IBM Cloud](https://img.shields.io/badge/IBM%20Cloud-Code%20Engine-1261FE)](https://cloud.ibm.com/codeengine/overview)\n[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-339933?logo=nodedotjs&logoColor=white)](#prerequisites)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/markusvankempen/code-engine-mcp-server/blob/main/LICENSE)\n[![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)\n[![Open VSX](https://img.shields.io/badge/Open%20VSX-Registry-C160EF?logo=eclipseide&logoColor=white)](https://open-vsx.org/extension/markusvankempen/code-engine-mcp)\n[![npm](https://img.shields.io/npm/v/code-engine-mcp-server.svg?label=npm)](https://www.npmjs.com/package/code-engine-mcp-server)\n\n## How It Works\n\n```mermaid\nflowchart TD\n    A([AI Assistant\\nCopilot / Claude / Cline / Bob]) -->|MCP JSON-RPC| B[Code Engine MCP Server]\n\n    B --> C{Tool Category}\n\n    C -->|Container Tools| D[Docker / Podman]\n    C -->|Registry Tools| E[IBM Container Registry\\nus.icr.io]\n    C -->|Code Engine Tools| F[IBM Code Engine\\nREST API]\n    C -->|Procedures| G[Multi-step Workflows]\n\n    D -->|build / push / validate| E\n    E -->|image reference| F\n\n    G -->|proc_build_push_deploy| D\n    G -->|proc_apply_manifest| F\n\n    F --> H[(Projects\\nApps\\nBuilds\\nJobs\\nSecrets\\nDomains)]\n\n    H -->|ready| I([Live App\\nhttps://app.region.codeengine.appdomain.cloud])\n\n    style A fill:#1261FE,color:#fff\n    style B fill:#0f3460,color:#fff\n    style G fill:#7b2d8b,color:#fff\n    style I fill:#198038,color:#fff\n```\n\n\n## ✨ What You Get\n\n- Container workflow tools for Docker or Podman\n- IBM Container Registry (ICR) tools — list namespaces, list images, delete images\n- IBM Code Engine project and application management tools\n- MCP-ready setup for GitHub Copilot, Cline, Bob, Claude Desktop, and the optional VS Code extension in `vscode-extension/`\n- **MCP Activity Dashboard** — live timeline of tool calls, session grouping, deploy outcome highlights, and a Deployments inventory tab (extension or dev repo)\n- **Live activity logging** — optional JSONL event stream for every MCP tool call (`MCP_ACTIVITY_*` env vars)\n- A simple local development and troubleshooting workflow\n\n## 🚀 Quick Start\n\n```bash\n# 1) Install dependencies\nnpm install\n\n# 2) Build the server\nnpm run build\n\n# 3) Run once to verify\nnode build/index.js\n```\n\nThen configure your MCP client using one of the examples in the Configuration section below.\n\n## 🤖 The Agentic Experience (No Docker/Code Engine Lingo Needed)\n\nThe 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. \n\nHere is an example interaction from a real session:\n\n**User:**\n> \"I have an app in the `developer-splash` folder. Deploy it to my Code Engine project.\"\n\n**Assistant's Autonomous Thought Process:**\n1. *Discovery:* \"Let me check what projects and namespaces exist... Found project `markus-app-v2-toronto` and namespace `mvk-code-engine`.\"\n2. *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`.\"\n3. *Execution:* \"Now I'll run the full pipeline: build → push → deploy → wait.\"\n4. *Validation:* \"It's deployed but stuck at 'deploying'. Let me check the logs... The container is running but the readiness probe is failing.\"\n5. *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.\"\n6. *Completion:* \"App is live! 🎉 Status: ready.\"\n\n**Assistant Response to User:**\n> \"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!\"\n\nWith this MCP server, the AI acts as an expert DevOps engineer pairing with you.\n\n## 📊 MCP Activity Dashboard (v1.4.0)\n\nSee what your AI assistant is doing in real time — tool calls, idle gaps between steps, deploy outcomes, and live app URLs.\n\n```mermaid\nflowchart LR\n    A[MCP tool call] -->|MCP_ACTIVITY_ENABLED| B[events.jsonl]\n    B --> C{Dashboard}\n    C -->|VS Code extension| D[Activity tab]\n    C -->|Browser| E[localhost:8767]\n    D --> F[Deployments tab\\ninventory + actions]\n```\n\n### Enable activity logging\n\nAdd to your MCP client env (Cursor `.cursor/mcp.json`, VS Code `mcp.json`, etc.):\n\n```json\n\"MCP_ACTIVITY_ENABLED\": \"true\",\n\"MCP_ACTIVITY_EVENTS_PATH\": \"/absolute/path/to/code-engine-mcp-server/dashboard/activity/live/events.jsonl\",\n\"MCP_ACTIVITY_SESSION_ID\": \"session:my-chat-001\",\n\"MCP_ACTIVITY_CHAT_LABEL\": \"Deploy Star Wars splash\"\n```\n\nRestart the MCP server after changing env. Events append to `events.jsonl` on every tool start/finish — including input summaries, pipeline sub-steps (`proc_build_push_deploy`), result highlights, and optional HTTP smoke-test labels.\n\nSee [.env.example](.env.example) for all `MCP_ACTIVITY_*` variables.\n\n### Open the dashboard\n\n| Method | How |\n|--------|-----|\n| **VS Code extension** | Command Palette → **IBM Code Engine MCP: Open MCP Activity Dashboard** |\n| **Browser (dev repo)** | `npm run dashboard` → http://localhost:8767/ |\n| **Live refresh** | On by default in the browser; toggle in-panel or set `codeEngineMcp.activityLiveRefresh` (extension) |\n\nThe **Activity** tab shows a session timeline with tool duration, idle gaps, and a task-outcome banner (status, image, live URL). The **Deployments** tab lists projects and apps from Code Engine and supports get-details, redeploy, and delete via MCP tools.\n\n**Example chat prompt:**\n\n> *\"I have a Star Wars splash page in examples/starwars-splash. Deploy it to Code Engine using only MCP tools — build for linux/amd64, push to my ICR namespace, and deploy to my Code Engine project. Show me the live URL when ready.\"*\n\nOpen the Activity Dashboard while the assistant runs to watch `proc_build_push_deploy` progress step by step.\n\n## Deploy Your First App\n\nThis walks through deploying the included [Star Wars splash page example](https://github.com/markusvankempen/code-engine-mcp-server/tree/main/examples/starwars-splash) — a static nginx container — entirely through the MCP server.\n\n> **Apple Silicon users:** always build with `--platform linux/amd64`. Code Engine runs amd64 only.\n\n### Step 1 — Build and push the image\n\n```bash\ncd examples/starwars-splash\npodman build --platform linux/amd64 -t us.icr.io/<your-namespace>/starwars-splash:v1.0.0 .\npodman push us.icr.io/<your-namespace>/starwars-splash:v1.0.0\n```\n\nOr ask your assistant:\n```\nBuild examples/starwars-splash as us.icr.io/my-namespace/starwars-splash:v1.0.0 for linux/amd64 and push it\n```\n\n**MCP response — `build_container_image`:**\n```json\n{\n  \"success\": true,\n  \"command\": \"podman build --platform linux/amd64 -t us.icr.io/my-namespace/starwars-splash:v1.0.0 ...\",\n  \"build_output\": \"STEP 1/5: FROM nginx:alpine\\nSTEP 2/5: COPY index.html /usr/share/nginx/html/index.html\\nSTEP 3/5: RUN sed -i 's/listen  80;/listen 8080;/g' /etc/nginx/conf.d/default.conf\\nSTEP 4/5: EXPOSE 8080\\nSTEP 5/5: CMD [\\\"nginx\\\", \\\"-g\\\", \\\"daemon off;\\\"]\\nSuccessfully tagged us.icr.io/my-namespace/starwars-splash:v1.0.0\"\n}\n```\n\n> **Note:** Container runtimes (Podman/Docker) write build progress to stderr. The `build_output` field combines stdout and stderr so you see the full build log.\n\n**MCP response — `push_container_image`:**\n```json\n{\n  \"success\": true,\n  \"command\": \"podman push us.icr.io/my-namespace/starwars-splash:v1.0.0\",\n  \"output\": \"Getting image source signatures\\nCopying blobs...\\nWriting manifest to image destination\"\n}\n```\n\n### Step 2 — Create a registry pull secret\n\nAsk your assistant (once per project):\n```\nCreate a registry secret called icr-pull-secret in project <project-id> for us.icr.io using my IBM Cloud API key\n```\n\nOr use the `ce_create_secret` tool directly:\n```json\n{\n  \"project_id\": \"<your-project-id>\",\n  \"name\": \"icr-pull-secret\",\n  \"format\": \"registry\",\n  \"data\": {\n    \"username\": \"iamapikey\",\n    \"password\": \"<your-ibm-cloud-api-key>\",\n    \"server\": \"us.icr.io\",\n    \"email\": \"user@example.com\"\n  }\n}\n```\n\n**MCP response — `ce_create_secret`:**\n```json\n{\n  \"name\": \"icr-pull-secret\",\n  \"format\": \"registry\",\n  \"resource_type\": \"secret_registry_v2\",\n  \"created_at\": \"2026-05-08T22:10:00Z\",\n  \"project_id\": \"<your-project-id>\"\n}\n```\n\n### Step 3 — Deploy the application\n\nAsk your assistant:\n```\nDeploy us.icr.io/my-namespace/starwars-splash:v1.0.0 to Code Engine project <project-id>\nas app \"starwars-splash\" using pull secret icr-pull-secret, min 1 instance\n```\n\nOr use the `ce_create_application` tool:\n```json\n{\n  \"project_id\": \"<your-project-id>\",\n  \"name\": \"starwars-splash\",\n  \"image\": \"us.icr.io/<your-namespace>/starwars-splash:v1.0.0\",\n  \"image_secret\": \"icr-pull-secret\",\n  \"scale_min_instances\": 1,\n  \"scale_max_instances\": 3\n}\n```\n\n**MCP response — `ce_create_application`:**\n```json\n{\n  \"name\": \"starwars-splash\",\n  \"resource_type\": \"app_v2\",\n  \"status\": \"deploying\",\n  \"image_reference\": \"us.icr.io/my-namespace/starwars-splash:v1.0.0\",\n  \"image_secret\": \"icr-pull-secret\",\n  \"image_port\": 8080,\n  \"scale_min_instances\": 1,\n  \"scale_max_instances\": 3,\n  \"scale_cpu_limit\": \"1\",\n  \"scale_memory_limit\": \"4G\",\n  \"endpoint\": \"https://starwars-splash.<subdomain>.us-south.codeengine.appdomain.cloud\",\n  \"status_details\": {\n    \"latest_created_revision\": \"starwars-splash-00001\",\n    \"latest_ready_revision\": null\n  }\n}\n```\n\n### Step 4 — Check deployment status\n\n```\nGet details for the starwars-splash app in project <project-id>\n```\n\nThis calls `ce_get_application` and returns the public URL once the app reaches `ready` status.\n\n```\nList the running instances of starwars-splash in project <project-id>\n```\n\nThis calls `ce_list_app_instances` (or `ce_get_app_instance` for a specific instance) and shows:\n- Instance name and revision\n- Container status (`running` / `pending` / `failed`)\n- Restart count\n- Started-at timestamp\n- CPU and memory allocation\n\n**MCP response — `ce_get_application` (once ready):**\n```json\n{\n  \"name\": \"starwars-splash\",\n  \"status\": \"ready\",\n  \"image_reference\": \"us.icr.io/my-namespace/starwars-splash:v1.0.0\",\n  \"image_port\": 8080,\n  \"scale_min_instances\": 1,\n  \"scale_max_instances\": 3,\n  \"scale_cpu_limit\": \"0.5\",\n  \"scale_memory_limit\": \"1G\",\n  \"region\": \"us-south\",\n  \"endpoint\": \"https://starwars-splash.<subdomain>.us-south.codeengine.appdomain.cloud\",\n  \"status_details\": {\n    \"latest_created_revision\": \"starwars-splash-00001\",\n    \"latest_ready_revision\": \"starwars-splash-00001\"\n  }\n}\n```\n\n### Step 5 — Map a custom domain (optional)\n\nTo serve the app at your own domain (e.g. `myapp.example.com`) you need a TLS certificate. The IBM Code Engine REST API always requires a real certificate — IBM's Console \"Platform managed\" option is not available via the API.\n\n**5a — Get a Let's Encrypt certificate (certbot)**\n\n```bash\n# Install once\nbrew install certbot\n\n# Request cert — certbot will print a DNS TXT challenge value\nmkdir -p ~/certbot/{config,work,logs}\n/opt/homebrew/bin/certbot certonly --manual --preferred-challenges dns \\\n  -d <your-domain> --agree-tos --no-eff-email --email you@example.com \\\n  --config-dir ~/certbot/config --work-dir ~/certbot/work --logs-dir ~/certbot/logs\n```\n\nCertbot will pause and ask you to add a TXT record:\n```\nAdd TXT record: _acme-challenge.<your-domain> = <challenge-value>\n```\nVerify propagation, then press Enter. Certbot writes:\n- `~/certbot/config/live/<your-domain>/fullchain.pem`\n- `~/certbot/config/live/<your-domain>/privkey.pem`\n\n**5b — Create the TLS secret in Code Engine**\n\nAsk your assistant:\n```\nCreate a TLS secret called starwars-tls in project <project-id>\nusing cert ~/certbot/config/live/myapp.example.com/fullchain.pem\nand key ~/certbot/config/live/myapp.example.com/privkey.pem\n```\n\nThis calls `ce_create_tls_secret_from_pem` — reads the PEM files from disk and stores them as a Code Engine `tls` secret.\n\n**MCP response — `ce_create_tls_secret_from_pem`:**\n```json\n{\n  \"name\": \"my-tls\",\n  \"format\": \"tls\",\n  \"resource_type\": \"secret_tls_v2\",\n  \"created_at\": \"2026-05-08T22:30:00Z\",\n  \"project_id\": \"<your-project-id>\"\n}\n```\n\n**5c — Create the domain mapping**\n\nAsk your assistant:\n```\nMap domain myapp.example.com to app my-app\nin project <project-id> using TLS secret my-tls\n```\n\nThis calls `ce_create_domain_mapping` and returns the `cname_target`.\n\n**MCP response — `ce_create_domain_mapping`:**\n```json\n{\n  \"name\": \"myapp.example.com\",\n  \"status\": \"ready\",\n  \"cname_target\": \"custom.<subdomain>.us-south.codeengine.appdomain.cloud\",\n  \"component\": {\n    \"resource_type\": \"app_v2\",\n    \"name\": \"my-app\"\n  },\n  \"tls_secret\": \"my-tls\",\n  \"region\": \"us-south\"\n}\n```\n\n**5d — Update your CNAME**\n\nIn your DNS provider, set:\n```\nmyapp.example.com CNAME custom.<subdomain>.us-south.codeengine.appdomain.cloud\n```\n\nUse the `cname_target` value returned in 5c (it uses the `custom.` prefix, not the app name).\n\nOnce DNS propagates, `https://<your-domain>` serves the app with a valid TLS certificate.\n\n> **Certificate renewal:** Let's Encrypt certs expire after 90 days. Re-run certbot to get updated PEM files, then ask Copilot to run `ce_renew_tls_secret_from_pem` — it patches the existing secret in-place so your domain mapping continues working without any changes.\n\n### Full one-shot prompt\n\n```\nI have a Star Wars splash page in examples/starwars-splash.\nBuild it for linux/amd64 as us.icr.io/my-namespace/starwars-splash:v1.0.0,\npush it, then deploy it to Code Engine project <project-id> with pull secret icr-pull-secret.\nTell me the public URL and confirm the instance is running.\n```\n\n---\n\n## 🔒 Security & Transport Model\n\nThe Code Engine MCP Bridge implements a **Stateless Security Model** and supports the modern **Streamable HTTP** transport standard.\n\n### **Authentication**\nAll requests must be authenticated. Credentials are not stored on the server; they must be provided by the client in every request:\n- **Primary (Recommended)**: `Authorization: Bearer <IBMCLOUD_API_KEY>` header.\n- **Legacy**: `?apiKey=<key>` query parameter.\n\n### **Transport Endpoints**\n| Protocol | Method | Endpoint | Description |\n| :--- | :--- | :--- | :--- |\n| **Streamable HTTP** | `POST` | `/sse` | Modern MCP transport. Returns the session endpoint. |\n| **Standard SSE** | `GET` | `/sse` | Legacy EventSource transport. |\n| **Messaging** | `POST` | `/message` | Send JSON-RPC messages (requires `sessionId` query param). |\n\n---\n\n## 🌐 Host Any MCP Server on Code Engine\n\nYou 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.\n\n> 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)\n\n```\nYour AI Assistant\n    │  MCP JSON-RPC (STDIO, local)\n    ▼\ncode-engine-mcp-server  ──► ce_create_application\n                                     │\n                                     ▼\n                         Code Engine App\n                         image: docker.io/supercorp/supergateway\n                         args:  --stdio \"npx -y <any-mcp-server>\"\n                                --outputTransport sse\n                                     │  HTTPS + SSE  (public URL)\n                                     ▼\n                         Any remote MCP client\n                         (Claude Desktop, Cursor, VS Code, …)\n```\n\nAny STDIO MCP server becomes a remotely accessible, auto-scaling cloud service — with no custom infrastructure.\n\nThis 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.\n\nThe example files live in [examples/mcp-server-supergateway/](https://github.com/markusvankempen/code-engine-mcp-server/tree/main/examples/mcp-server-supergateway).\n\n### Step 1 — Deploy the hosted MCP server\n\nAsk your assistant:\n```\nDeploy a hosted MCP fetch server to my Code Engine project <project-id>.\nUse image docker.io/supercorp/supergateway on port 8000.\nStartup args: --stdio \"npx -y @tokenizin/mcp-npx-fetch\" --outputTransport sse\nName it \"mcp-fetch-server\". No pull secret needed.\n```\n\nThis calls `ce_create_application`:\n```json\n{\n  \"project_id\": \"<your-project-id>\",\n  \"name\": \"mcp-fetch-server\",\n  \"image\": \"docker.io/supercorp/supergateway\",\n  \"port\": 8000,\n  \"run_args\": [\"--stdio\", \"npx -y @tokenizin/mcp-npx-fetch\", \"--outputTransport\", \"sse\"]\n}\n```\n\n**MCP response — `ce_create_application`:**\n```json\n{\n  \"name\": \"mcp-fetch-server\",\n  \"resource_type\": \"app_v2\",\n  \"status\": \"deploying\",\n  \"image_reference\": \"docker.io/supercorp/supergateway\",\n  \"image_port\": 8000,\n  \"scale_min_instances\": 0,\n  \"scale_max_instances\": 10,\n  \"endpoint\": \"https://mcp-fetch-server.<subdomain>.<region>.codeengine.appdomain.cloud\",\n  \"status_details\": {\n    \"latest_created_revision\": \"mcp-fetch-server-00001\",\n    \"latest_ready_revision\": null\n  }\n}\n```\n\n> 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.\n\n### Step 2 — Wait for the app to be ready\n\nAsk your assistant:\n```\nWait for mcp-fetch-server in project <project-id> to be ready\n```\n\nThis calls `ce_wait_for_app_ready`:\n```json\n{\n  \"project_id\": \"<your-project-id>\",\n  \"app_name\": \"mcp-fetch-server\",\n  \"timeout_seconds\": 120\n}\n```\n\n**MCP response — `ce_wait_for_app_ready`:**\n```json\n{\n  \"app_name\": \"mcp-fetch-server\",\n  \"status\": \"ready\",\n  \"endpoint\": \"https://mcp-fetch-server.<subdomain>.<region>.codeengine.appdomain.cloud\",\n  \"elapsed_seconds\": 34,\n  \"poll_history\": [\n    { \"attempt\": 1, \"status\": \"deploying\", \"elapsed_seconds\": 10 },\n    { \"attempt\": 2, \"status\": \"deploying\", \"elapsed_seconds\": 20 },\n    { \"attempt\": 3, \"status\": \"ready\",     \"elapsed_seconds\": 34 }\n  ]\n}\n```\n\n### Step 3 — Verify the running instance\n\nAsk your assistant:\n```\nList the running instances of mcp-fetch-server in project <project-id>\n```\n\nThis calls `ce_list_app_instances`:\n\n**MCP response — `ce_list_app_instances`:**\n```json\n{\n  \"instances\": [\n    {\n      \"name\": \"mcp-fetch-server-00001-deployment-abc123\",\n      \"revision\": \"mcp-fetch-server-00001\",\n      \"status\": \"running\",\n      \"restart_count\": 0,\n      \"started_at\": \"2026-05-09T12:01:44Z\"\n    }\n  ]\n}\n```\n\n### Step 4 — Connect your MCP client\n\nUse [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) to bridge the HTTP+SSE endpoint back to STDIO for local clients.\n\n**VS Code `mcp.json`:**\n```json\n{\n  \"servers\": {\n    \"fetch\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"mcp-remote\",\n        \"https://mcp-fetch-server.<subdomain>.<region>.codeengine.appdomain.cloud/sse\"\n      ]\n    }\n  }\n}\n```\n\n**Claude Desktop `claude_desktop_config.json`:**\n```json\n{\n  \"mcpServers\": {\n    \"fetch\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"mcp-remote\",\n        \"https://mcp-fetch-server.<subdomain>.<region>.codeengine.appdomain.cloud/sse\"\n      ]\n    }\n  }\n}\n```\n\n### Step 5 — Test the endpoint\n\nVerify the server is live and streaming:\n```bash\ncurl -N https://mcp-fetch-server.<subdomain>.<region>.codeengine.appdomain.cloud/sse\n```\n\nOr open it in the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):\n```bash\nnpx @modelcontextprotocol/inspector\n# Connect via SSE → paste the Code Engine URL\n```\n\nOnce connected, you will see the `fetch` tool listed and can invoke it directly from the inspector.\n\n### Full one-shot prompt\n\n```\nDeploy a hosted MCP fetch server to my Code Engine project <project-id>.\nUse image docker.io/supercorp/supergateway on port 8000 with no pull secret.\nrun_args: --stdio \"npx -y @tokenizin/mcp-npx-fetch\" --outputTransport sse\nName it \"mcp-fetch-server\", wait for it to be ready, and give me the /sse URL\nso I can add it to my mcp.json.\n```\n\nSee [examples/mcp-server-supergateway/](https://github.com/markusvankempen/code-engine-mcp-server/tree/main/examples/mcp-server-supergateway) for the ready-to-use client config file.\n\n### Deploy any other STDIO MCP server\n\nThe same pattern works for any `npx`-runnable MCP server — just swap the `--stdio` argument:\n\n| MCP Server | `--stdio` argument |\n|---|---|\n| Fetch | `npx -y @tokenizin/mcp-npx-fetch` |\n| Filesystem | `npx -y @modelcontextprotocol/server-filesystem /data` |\n| Brave Search | `npx -y @modelcontextprotocol/server-brave-search` |\n| Your own server | `node /app/server.js` |\n\n---\n\n## Documentation\n\n- [Setup Instructions](https://github.com/markusvankempen/code-engine-mcp-server/blob/main/docs/SETUP_INSTRUCTIONS.md)\n- [MCP Inspector Troubleshooting](https://github.com/markusvankempen/code-engine-mcp-server/blob/main/docs/MCP_INSPECTOR_TROUBLESHOOTING.md)\n- [VS Code MCP extension](https://github.com/markusvankempen/code-engine-mcp-server/blob/main/vscode-extension/README.md) — Activity Dashboard, Receipt Visualizer, setup & diagnostics\n- [IBM Code Engine API (IBM Cloud)](https://cloud.ibm.com/apidocs/codeengine/v2)\n- [Client README](https://github.com/markusvankempen/code-engine-mcp-server/blob/main/docs/CLIENT_README.md)\n- [Cline MCP Config Example](https://github.com/markusvankempen/code-engine-mcp-server/blob/main/docs/CLINE_CONFIG_EXAMPLE.json)\n- [Code of Conduct](https://github.com/markusvankempen/code-engine-mcp-server/blob/main/docs/CODE_OF_CONDUCT.md)\n- [Contributing Guide](https://github.com/markusvankempen/code-engine-mcp-server/blob/main/docs/CONTRIBUTING.md)\n- [Maintainers](https://github.com/markusvankempen/code-engine-mcp-server/blob/main/docs/MAINTAINERS.md)\n\n## 🗂️ Project Structure\n\n```text\ncode-engine-mcp-server/\n├── build/                            # Compiled JavaScript output (dev repo)\n├── docs/                             # API references, client guides, community files\n│   ├── API_CALL_SCENARIOS.md\n│   ├── CODE_ENGINE_API_REFERENCE.md\n│   ├── MCP_INSPECTOR_TROUBLESHOOTING.md\n│   ├── SETUP_INSTRUCTIONS.md\n│   ├── CODE_OF_CONDUCT.md\n│   ├── CONTRIBUTING.md\n│   └── MAINTAINERS.md\n├── examples/\n│   ├── developer-splash/             # nginx static container example\n│   ├── starwars-splash/              # nginx Star Wars crawl example\n│   └── mcp-server-supergateway/      # Host any MCP server on Code Engine via supergateway\n├── dashboard/                        # MCP Activity Dashboard (dev repo) — npm run dashboard\n│   ├── index.html                    # Activity + Deployments UI\n│   ├── serve-dashboard.mjs           # Local server on port 8767\n│   └── activity/live/events.jsonl    # Live tool-call log (gitignored runtime file)\n├── internal/                         # Internal release notes\n├── src/                              # Main TypeScript source code\n├── CHANGELOG.md                      # Release history\n├── LICENSE                           # Project license\n├── README.md                         # Project overview and usage\n├── mcp.example.json                  # Example MCP client configuration\n├── vscode-extension/                 # Optional VS Code extension\n├── package.json                      # npm package metadata and scripts\n├── server.json                       # MCP Registry metadata\n└── tsconfig.json                     # TypeScript configuration\n```\n\n## 🧩 Features\n\n### Container Runtime Tools (Docker/Podman)\n- ✅ Detect container runtime (Docker/Podman)\n- ✅ Build container images (with platform targeting for amd64)\n- ✅ Push images to registries\n- ✅ Tag images with a new name/tag before pushing\n- ✅ List local images\n- ✅ Test containers locally\n- ✅ Get container logs\n- ✅ Stop and remove containers\n- ✅ List all containers\n- ✅ Inspect container image architecture, labels, and env\n- ✅ Prune unused/dangling images to reclaim disk space\n- ✅ Remove a local container image\n- ✅ Scaffold a Code Engine-compatible Dockerfile (`scaffold_dockerfile`)\n\n### IBM Container Registry (ICR)\n- ✅ Log in to IBM Container Registry (`login_to_registry`)\n- ✅ List ICR namespaces\n- ✅ List images with optional namespace filter\n- ✅ Delete images by tag\n- ✅ Create ICR namespaces (`icr_create_namespace`)\n\n### IBM Code Engine Tools\n- ✅ List, create, and delete projects\n- ✅ Deploy applications with image pull secrets\n- ✅ Update applications (image, scaling, env)\n- ✅ List applications and get public URLs\n- ✅ Get per-instance status (running, restarts, started-at)\n- ✅ Get application logs per instance\n- ✅ Build and job management (build configs, build runs, events, logs)\n- ✅ Validate Dockerfile for Code Engine compatibility (`ce_validate_dockerfile`)\n- ✅ Secrets and ConfigMaps (CRUD + update-in-place)\n- ✅ Custom domain mappings (create, list, get, update, delete)\n- ✅ Service bindings — connect IBM Cloud services to CE apps\n- ✅ TLS secrets from Let's Encrypt / certbot PEM files (`ce_create_tls_secret_from_pem`)\n- ✅ TLS cert renewal in-place without disrupting domain mappings (`ce_renew_tls_secret_from_pem`)\n- ✅ Update any secret in-place (`ce_update_secret`)\n- ✅ 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\n- ✅ Restart app instances, roll back to a previous revision (`ce_restart_application`, `ce_rollback_application`)\n- ✅ Resubmit or cancel job runs (`ce_resubmit_job_run`, `ce_cancel_job_run`)\n- ✅ Kubernetes system events for apps, build runs, and job runs\n- ✅ Project resource quotas and public egress IPs\n- ✅ Sync env vars from a local `.env` file (`ce_sync_env_from_dotenv`)\n- ✅ Find idle / cost-incurring apps (`ce_find_idle_apps`)\n- ✅ Wait for app deployment to complete (`ce_wait_for_app_ready`)\n- ✅ IAM token info and diagnostics (`iam_get_token_info`)\n\n### Procedures\n- ✅ `proc_build_push_deploy` — full container pipeline in one prompt (build → push → deploy → wait)\n- ✅ `proc_setup_custom_domain` — TLS cert + domain mapping in one step, returns CNAME target\n- ✅ `proc_apply_manifest` — apply a declarative JSON manifest (`ce-deploy.json`) to create/update all CE resources\n\n### Developer Experience (v1.4.0)\n- ✅ **MCP Activity Dashboard** — session timeline, idle-gap visualization, deploy outcome banner, Deployments inventory tab\n- ✅ **Live activity logging** — JSONL event stream with input summaries, pipeline sub-steps, and HTTP probe highlights\n- ✅ **VS Code extension commands** — Open MCP Activity Dashboard, Open Optional Receipt Visualizer\n\n## ⚙️ Configuration\n\n### Getting an IBM Cloud API key\n\nAll Code Engine and ICR operations require an IBM Cloud API key. Get one at:\n**[IBM Cloud IAM → API keys](https://cloud.ibm.com/iam/apikeys)** → **Create an IBM Cloud API key**.\n\nStore the key somewhere safe (password manager). You will paste it into one of the configuration paths below.\n\n---\n\n### Path A — VS Code extension (recommended)\n\nThe [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.\n\n**Install from the Marketplace:**\n\n| IDE / Platform | Install link |\n|---|---|\n| VS Code | [marketplace.visualstudio.com](https://marketplace.visualstudio.com/items?itemName=MarkusvanKempen.code-engine-mcp) |\n| Cursor / Theia / Gitpod / Codium | [open-vsx.org](https://open-vsx.org/extension/markusvankempen/code-engine-mcp) |\n| From a local `.vsix` | **Command Palette** → **Extensions: Install from VSIX…** |\n\n**Set your API key (required before any tool works):**\n\n1. Open the **IBM Code Engine MCP** sidebar panel (cloud icon in the Activity Bar)\n2. Paste your IBM Cloud API key and click **Save**  \n   _(The key is stored in VS Code global settings — encrypted by the OS keychain, never in a plaintext file)_\n3. Optionally change the region (default: `us-south`) in the same panel\n4. Click **Configure MCP** — this writes the server entry to the global `mcp.json` and restarts VS Code's MCP server list\n5. Click **Run Diagnostics** to confirm everything is wired up:\n   - ✅ Node.js found on PATH\n   - ✅ API key configured\n   - ✅ MCP server registered\n   - ✅ Tool list discovered\n\nAfter step 4 you can open GitHub Copilot Chat and immediately ask:\n> *\"List all my Code Engine projects\"*\n\n> **Tip:** If Copilot can't see the tools after installing, run **Command Palette → Reload Window** once.\n\nMore detail: [vscode-extension/README.md](https://github.com/markusvankempen/code-engine-mcp-server/blob/main/vscode-extension/README.md).\n\n---\n\n### Path B — Pure MCP config (no extension)\n\nUse this path with **any** MCP-capable client: GitHub Copilot without the extension, Cline, Bob, Claude Desktop, Cursor, etc.\n\n#### Where to put the API key (choose one approach)\n\n**Option 1 — Shell environment variable (most secure)**\n\nCopy the provided template and fill in your key:\n\n```bash\ncp .env.example .env          # copy template (already in .gitignore)\n# edit .env → set IBMCLOUD_API_KEY=your-key\nsource .env                   # load into current shell session\n```\n\nOr add the export permanently to your shell profile so every new terminal has it:\n\n```bash\n# ~/.zshrc or ~/.bash_profile\nexport IBMCLOUD_API_KEY=\"your-ibm-cloud-api-key-here\"\n```\n\nSee [.env.example](.env.example) for all available variables (`IBMCLOUD_REGION`, `CONTAINER_RUNTIME`, `DEBUG`).\n\nThen reference the variable in the MCP config without embedding the value:\n\n```json\n{\n  \"servers\": {\n    \"code-engine\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"code-engine-mcp-server@latest\"],\n      \"env\": {\n        \"IBMCLOUD_API_KEY\": \"${env:IBMCLOUD_API_KEY}\",\n        \"IBMCLOUD_REGION\": \"us-south\"\n      }\n    }\n  }\n}\n```\n\n> `${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.\n\n**Option 2 — VS Code input variable (prompted on connect)**\n\nVS Code can prompt you for the API key when it starts the server — great for shared machines:\n\n```json\n{\n  \"inputs\": [\n    {\n      \"id\": \"ibmcloud-api-key\",\n      \"type\": \"promptString\",\n      \"description\": \"IBM Cloud API key\",\n      \"password\": true\n    }\n  ],\n  \"servers\": {\n    \"code-engine\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"code-engine-mcp-server@latest\"],\n      \"env\": {\n        \"IBMCLOUD_API_KEY\": \"${input:ibmcloud-api-key}\",\n        \"IBMCLOUD_REGION\": \"us-south\"\n      }\n    }\n  }\n}\n```\n\n**Option 3 — Inline value (simplest, least secure)**\n\nPaste the key directly. **Never commit this file to git.**\n\n```json\n{\n  \"servers\": {\n    \"code-engine\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"code-engine-mcp-server@latest\"],\n      \"env\": {\n        \"IBMCLOUD_API_KEY\": \"your-ibm-cloud-api-key-here\",\n        \"IBMCLOUD_REGION\": \"us-south\"\n      }\n    }\n  }\n}\n```\n\n> **Security:** Add the config file to `.gitignore`. For workspace configs, use `${env:...}` or `${input:...}` instead of inline values.\n\n---\n\n#### 1) GitHub Copilot (VS Code) — workspace `mcp.json`\n\nCreate `.vscode/mcp.json` in your workspace root (or copy `mcp.example.json`):\n\n```bash\ncp mcp.example.json .vscode/mcp.json\necho '.vscode/mcp.json' >> .gitignore\n```\n\nPaste one of the API key options above. Then restart the server:\n**Cmd+Shift+P** → **MCP: Restart Server** → `code-engine`.\n\nAlternatively, 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.\n\n---\n\n#### 2) Cline (VS Code Extension)\n\n1. Open VS Code Settings (`Cmd+,`)\n2. Search for **Cline: MCP Settings** → **Edit in settings.json**\n3. Add:\n\n```json\n{\n  \"cline.mcpServers\": {\n    \"code-engine\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"code-engine-mcp-server@latest\"],\n      \"env\": {\n        \"IBMCLOUD_API_KEY\": \"your-api-key-here\",\n        \"IBMCLOUD_REGION\": \"us-south\"\n      }\n    }\n  }\n}\n```\n\n---\n\n#### 3) Bob (VS Code Extension)\n\nBob uses the same `cline.mcpServers` configuration format:\n\n1. Open VS Code Settings (`Cmd+,`)\n2. Search for **Cline: MCP Settings** → **Edit in settings.json**\n3. Add:\n\n```json\n{\n  \"cline.mcpServers\": {\n    \"code-engine\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"code-engine-mcp-server@latest\"],\n      \"env\": {\n        \"IBMCLOUD_API_KEY\": \"your-api-key-here\",\n        \"IBMCLOUD_REGION\": \"us-south\"\n      }\n    }\n  }\n}\n```\n\n---\n\n### Path C — Remote Deployment (Stateless Proxy)\n\nYou can run the Code Engine MCP server as a **stateless proxy** on IBM Code Engine itself. In this mode, the server **does not store any credentials**. Instead, it extracts the `IBMCLOUD_API_KEY` from each incoming request.\n\n#### 1. Security Model\nThe server accepts credentials via:\n- **Authorization Header**: `Authorization: Bearer <your-ibm-cloud-api-key>`\n- **Query Parameter**: `?apiKey=<your-ibm-cloud-api-key>`\n\n#### 2. Client Configuration\nTo connect to a remote instance (e.g., `https://ce-mcp-remote.../sse`), use [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) which handles the SSE-to-STDIO bridging and automatically forwards your local `IBMCLOUD_API_KEY` environment variable.\n\n**`mcp.json` / `claude_desktop_config.json`:**\n```json\n{\n  \"mcpServers\": {\n    \"remote-code-engine\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"mcp-remote\",\n        \"https://your-remote-server.appdomain.cloud/sse\"\n      ],\n      \"env\": {\n        \"IBMCLOUD_API_KEY\": \"${env:IBMCLOUD_API_KEY}\"\n      }\n    }\n  }\n}\n```\n\n#### 3. Diagnostic Page\nRemote deployments include a built-in diagnostic page at the root URL (e.g., `https://ce-mcp-remote.../`) providing real-time stats, tool counts, and connection health.\n\n---\n\n> Prefer `${env:IBMCLOUD_API_KEY}` if your shell exports the key, so it never appears in `settings.json`.\n\n---\n\n#### 3) Claude Desktop\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"code-engine\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"code-engine-mcp-server@latest\"],\n      \"env\": {\n        \"IBMCLOUD_API_KEY\": \"your-api-key-here\",\n        \"IBMCLOUD_REGION\": \"us-south\"\n      }\n    }\n  }\n}\n```\n\n> Restart Claude Desktop after saving. The server starts on demand when Claude needs a tool.\n\n## Install & Registry Links\n\n| Platform | Link |\n|---|---|\n| **npm** (MCP server package) | [code-engine-mcp-server](https://www.npmjs.com/package/code-engine-mcp-server) |\n| **VS Code Marketplace** (extension) | [MarkusvanKempen.code-engine-mcp](https://marketplace.visualstudio.com/items?itemName=MarkusvanKempen.code-engine-mcp) |\n| **Open VSX Registry** (Theia / Gitpod / Cursor) | [markusvankempen.code-engine-mcp](https://open-vsx.org/extension/markusvankempen/code-engine-mcp) |\n| **MCP Registry** | [io.github.markusvankempen/code-engine-mcp-server](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.markusvankempen%2Fcode-engine-mcp-server) |\n\nThe **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).\n\n## 💬 Example Prompts\n\n### Detect Container Runtime\n\nAsk your assistant:\n```\nCan you detect which container runtime I have installed?\n```\n\n### Build a Container Image\n\nAsk your assistant:\n```\nBuild a container image from ./Dockerfile with the name myapp:latest\n```\n\n### Test Container Locally\n\nAsk your assistant:\n```\nTest the myapp:latest image locally on port 8080\n```\n\n### Push to Registry\n\nAsk your assistant:\n```\nPush myapp:latest to icr.io/my-namespace/myapp:latest\n```\n\n### List Code Engine Projects\n\nAsk your assistant:\n```\nList all my Code Engine projects\n```\n\n### Complete Workflow\n\nAsk your assistant:\n```\nI have a Node.js app in ./my-app with a Dockerfile. Can you:\n1. Build it as myapp:v1.0.0\n2. Test it locally on port 3000\n3. Push it to icr.io/my-namespace/myapp:v1.0.0\n4. Deploy it to my Code Engine project \"production\"\n5. Show me the application URL\n```\n\n### Custom Domain\n\nAsk your assistant:\n```\nCreate a TLS secret called my-tls in project <project-id>\nusing cert ~/certbot/config/live/example.com/fullchain.pem\nand key ~/certbot/config/live/example.com/privkey.pem.\nThen map domain example.com to app my-app using that secret.\nTell me what CNAME value to set in DNS.\n```\n\n## 🛠️ Available Tools\n\n89 tools total: 13 container tools + 5 ICR/registry tools + 66 Code Engine tools + 1 IAM tool + 3 procedures + 1 workspace tool.\n\n> **Procedures** bundle multiple tools into a single call. Use them for common end-to-end workflows.\n\n### Container Tools (13)\n\n| Tool | Description | Key Parameters |\n|------|-------------|----------------|\n| `detect_container_runtime` | Detect Docker or Podman | — |\n| `list_local_images` | List local container images | `runtime` |\n| `list_local_containers` | List local containers | `runtime`, `all` |\n| `build_container_image` | Build a container image | `dockerfile_path`, `image_name`, `context_path` |\n| `push_container_image` | Push image to registry | `image_name`, `runtime` |\n| `tag_container_image` | Tag an image with a new name/tag before pushing | `source_image`, `target_image`, `runtime` |\n| `test_container_locally` | Run container for local testing | `image_name`, `port_mapping`, `env_vars` |\n| `get_container_logs` | Get logs from a running container | `container_id`, `runtime` |\n| `stop_local_container` | Stop and remove a container | `container_id`, `runtime` |\n| `inspect_container_image` | Inspect image architecture, labels, and env | `image_name`, `runtime` |\n| `prune_images` | Remove unused/dangling images to reclaim disk space | `runtime`, `all` |\n| `remove_local_image` | Remove a local container image | `image_name`, `runtime` |\n| `scaffold_dockerfile` | Generate a Code Engine-compatible Dockerfile for an app folder | `app_folder`, `app_type`, `port` |\n\n### IBM Container Registry Tools (5)\n\n| Tool | Description | Key Parameters |\n|------|-------------|----------------|\n| `login_to_registry` | Log in to IBM Container Registry so images can be pushed | `registry`, `username`, `password`, `runtime` |\n| `icr_list_namespaces` | List ICR namespaces in your account | `region` |\n| `icr_list_images` | List images in ICR (optionally filtered by namespace) | `namespace`, `region` |\n| `icr_delete_image` | Delete an image by full tag | `image`, `region` |\n| `icr_create_namespace` | Create a new ICR namespace | `namespace`, `region` |\n\n### Code Engine: Projects (7)\n\n| Tool | Description | Key Parameters |\n|------|-------------|----------------|\n| `ce_list_projects` | List all projects in a region | — |\n| `ce_get_project` | Get project details | `project_id` |\n| `ce_get_project_status` | Get project status (readiness, enabled components) | `project_id` |\n| `ce_get_project_quotas` | Get resource quotas: Used-vs-Limit for CPU, memory, apps, jobs | `project_id` |\n| `ce_list_egress_ips` | List public egress IPs used by a project | `project_id` |\n| `ce_create_project` | Create a new project | `name`, `resource_group_id` |\n| `ce_delete_project` | Delete a project | `project_id` |\n\n### Code Engine: Applications (14)\n\n| Tool | Description | Key Parameters |\n|------|-------------|----------------|\n| `ce_list_applications` | List applications in a project | `project_id` |\n| `ce_get_application` | Get application details and public URL | `project_id`, `app_name` |\n| `ce_create_application` | Deploy a new application | `project_id`, `name`, `image`, `image_secret`, `port`, `env_vars`, `run_args`, `run_commands` |\n| `ce_update_application` | Update image, scaling, env, pull secret, run args | `project_id`, `app_name`, `image`, `image_secret`, `scale_*`, `run_args`, `run_commands` |\n| `ce_rollback_application` | Roll back to a previous revision | `project_id`, `app_name`, `revision_name` |\n| `ce_restart_application` | Restart running instances of an app | `project_id`, `app_name` |\n| `ce_delete_application` | Delete an application | `project_id`, `app_name` |\n| `ce_list_app_instances` | List all running instances with status | `project_id`, `app_name` |\n| `ce_get_app_instance` | Get status details for a specific instance | `project_id`, `app_name`, `instance_name` |\n| `ce_list_app_revisions` | List all revisions (deployed versions) of an app | `project_id`, `app_name` |\n| `ce_get_app_revision` | Get details of a specific revision | `project_id`, `app_name`, `revision_name` |\n| `ce_get_app_logs` | Get logs for an app instance | `project_id`, `app_name`, `instance_name` |\n| `ce_get_app_events` | Get Kubernetes system events for an app | `project_id`, `app_name` |\n| `ce_wait_for_app_ready` | Poll until app status is ready or timeout; returns `poll_history` | `project_id`, `app_name`, `timeout_seconds` |\n\n### Code Engine: Builds (10)\n\n| Tool | Description | Key Parameters |\n|------|-------------|----------------|\n| `ce_list_builds` | List build configurations | `project_id` |\n| `ce_get_build` | Get build configuration details | `project_id`, `build_name` |\n| `ce_create_build` | Create a build configuration | `project_id`, `name`, `output_image`, `output_secret` |\n| `ce_delete_build` | Delete a build configuration | `project_id`, `build_name` |\n| `ce_list_build_runs` | List build runs | `project_id` |\n| `ce_get_build_run` | Get build run status | `project_id`, `build_run_name` |\n| `ce_get_build_run_events` | Get Kubernetes events for a build run | `project_id`, `build_run_name` |\n| `ce_get_build_run_logs` | Get the build output logs for a build run | `project_id`, `build_run_name` |\n| `ce_create_build_run` | Start a build run | `project_id`, `build_name` |\n| `ce_validate_dockerfile` | Validate a Dockerfile for Code Engine compatibility (architecture, port, nginx sed patterns, USER, CMD) | `dockerfile_path`, `context_path`, `expected_port` |\n\n### Code Engine: Jobs (11)\n\n| Tool | Description | Key Parameters |\n|------|-------------|----------------|\n| `ce_list_jobs` | List job definitions | `project_id` |\n| `ce_get_job` | Get job definition details | `project_id`, `job_name` |\n| `ce_create_job` | Create a job definition | `project_id`, `name`, `image` |\n| `ce_update_job` | Update an existing job definition | `project_id`, `job_name` |\n| `ce_delete_job` | Delete a job definition | `project_id`, `job_name` |\n| `ce_list_job_runs` | List job runs | `project_id`, `job_name` (optional) |\n| `ce_get_job_run` | Get job run status | `project_id`, `job_run_name` |\n| `ce_get_job_run_events` | Get Kubernetes events for a job run | `project_id`, `job_run_name` |\n| `ce_create_job_run` | Submit a job run | `project_id`, `job_name` |\n| `ce_cancel_job_run` | Cancel a running job run | `project_id`, `job_run_name` |\n| `ce_resubmit_job_run` | Resubmit an existing job run with the same config | `project_id`, `job_run_name` |\n\n### Code Engine: Secrets (8)\n\n| Tool | Description | Key Parameters |\n|------|-------------|----------------|\n| `ce_list_secrets` | List secrets (names + keys only) | `project_id` |\n| `ce_get_secret` | Get secret metadata (no values) | `project_id`, `secret_name` |\n| `ce_create_secret` | Create a secret | `project_id`, `name`, `format`, `data` |\n| `ce_update_secret` | Update an existing secret in-place (PATCH) | `project_id`, `secret_name`, `data` |\n| `ce_delete_secret` | Delete a secret | `project_id`, `secret_name` |\n| `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` |\n| `ce_create_tls_secret_from_pem` | Create a TLS secret from PEM files | `project_id`, `secret_name`, `cert_pem_path`, `key_pem_path` |\n| `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` |\n\n### Code Engine: ConfigMaps (5)\n\n| Tool | Description | Key Parameters |\n|------|-------------|----------------|\n| `ce_list_config_maps` | List configmaps | `project_id` |\n| `ce_get_config_map` | Get configmap details | `project_id`, `config_map_name` |\n| `ce_create_config_map` | Create a configmap | `project_id`, `name`, `data` |\n| `ce_update_config_map` | Update an existing configmap (PATCH) | `project_id`, `config_map_name`, `data` |\n| `ce_delete_config_map` | Delete a configmap | `project_id`, `config_map_name` |\n\n### Code Engine: Domain Mappings (5)\n\n| Tool | Description | Key Parameters |\n|------|-------------|----------------|\n| `ce_list_domain_mappings` | List all custom domain mappings | `project_id` |\n| `ce_get_domain_mapping` | Get status and CNAME target for a mapping | `project_id`, `domain_name` |\n| `ce_create_domain_mapping` | Map a custom domain to an app | `project_id`, `domain_name`, `app_name`, `tls_secret` |\n| `ce_update_domain_mapping` | Update an existing custom domain mapping | `project_id`, `domain_name` |\n| `ce_delete_domain_mapping` | Delete a custom domain mapping | `project_id`, `domain_name` |\n\n### Code Engine: Bindings (4)\n\n| Tool | Description | Key Parameters |\n|------|-------------|----------------|\n| `ce_list_bindings` | List all service bindings in a project | `project_id` |\n| `ce_get_binding` | Get details of a specific service binding | `project_id`, `binding_id` |\n| `ce_create_binding` | Create a service binding to an IBM Cloud service instance | `project_id`, `app_name`, `prefix`, `secret_name` |\n| `ce_delete_binding` | Delete a service binding | `project_id`, `binding_id` |\n\n### Code Engine: Utilities (2)\n\n| Tool | Description | Key Parameters |\n|------|-------------|----------------|\n| `ce_find_idle_apps` | Report apps with scale_min=0 that may be incurring cost | `project_id` |\n| `ce_sync_env_from_dotenv` | Read a local `.env` file and apply its key/value pairs to a CE app | `project_id`, `app_name`, `dotenv_path` |\n\n### IBM Cloud IAM (1)\n\n| Tool | Description | Key Parameters |\n|------|-------------|----------------|\n| `iam_get_token_info` | Inspect the current IAM token — account, expiry, validity | — |\n\n### Procedures — Multi-Step Workflows (3)\n\n| Tool | What it does | Key Parameters |\n|------|-------------|----------------|\n| `proc_build_push_deploy` | Build container for linux/amd64 → push → create/update CE app → wait for ready → return URL + `poll_history` | `context_path`, `project_id_or_name`, `app_name`, `image_secret`, `icr_namespace`, `image_tag` (default `latest`), `icr_host` (default `us.icr.io`), `port`, `timeout_seconds` |\n| `proc_setup_custom_domain` | Read PEM files → create TLS secret → create domain mapping → return CNAME target | `project_id_or_name`, `app_name`, `domain_name`, `tls_secret_name`, `cert_pem_path`, `key_pem_path` |\n| `proc_apply_manifest` | Apply a declarative JSON deployment manifest (`ce-deploy.json`) to Code Engine — creates or updates all resources | `manifest_path`, `project_id_or_name` |\n\n### Workspace Tools (1)\n\n| Tool | Description | Key Parameters |\n|------|-------------|----------------|\n| `write_or_modify_file` | Write or update a text file in the workspace | `path`, `content` |\n\n## 🔐 Environment Variables\n\n- `IBMCLOUD_API_KEY`: IBM Cloud API key (required for Code Engine operations)\n- `IBMCLOUD_REGION`: Default IBM Cloud region (optional, defaults to us-south)\n- `CONTAINER_RUNTIME`: Force specific runtime (docker or podman)\n- `DEBUG`: Enable debug logging\n\n> **Optional — Activity Dashboard (v1.4.0, off by default):** `MCP_ACTIVITY_*` variables log tool calls to JSONL for the live dashboard. See [MCP Activity Dashboard](#-mcp-activity-dashboard-v140) and [.env.example](.env.example).\n\n> **Optional addon:** `PROVENANCE_*` variables enable signed receipts (off by default). See [Optional addon: Provenance](#optional-addon-provenance) at the end of this README.\n\n## 📋 Prerequisites\n\n- Node.js v18 or higher\n- Docker or Podman installed (for container build/push tools)\n- IBM Cloud API key (for all Code Engine and ICR operations)\n\n> The MCP server communicates directly with the IBM Cloud REST API and ICR API. No IBM Cloud CLI or Code Engine plugin is required.\n\n## 👩‍💻 Development\n\n```bash\n# Run in development mode\nnpm run dev\n\n# Build\nnpm run build\n\n# Test manually\nnode build/index.js\n```\n\n## 🧪 Troubleshooting\n\n### Server Not Connecting\n\n1. Verify the path in configuration is absolute\n2. Check Node.js is in PATH: `node --version`\n3. Verify build output exists: `ls build/index.js`\n4. Test manually: `node build/index.js`\n\n### Docker/Podman Commands Failing\n\n1. Verify installation: `docker --version` or `podman --version`\n2. Check Docker daemon is running\n3. Verify permissions (add user to docker group if needed)\n\n### Code Engine Commands Failing\n\n1. Verify your API key is set: check `IBMCLOUD_API_KEY` in your MCP client config\n2. Confirm the region is correct (default `us-south`); set `IBMCLOUD_REGION` if needed\n3. Verify the project ID is valid: use `ce_list_projects` to find it\n4. Check for expired tokens — the server re-fetches IAM tokens automatically; if errors persist, regenerate your API key at [IBM Cloud IAM → API keys](https://cloud.ibm.com/iam/apikeys)\n\n## 🛡️ Security\n\n- Never commit API keys to version control\n- Use environment variables for sensitive data\n- Consider using IBM Cloud IAM for authentication\n- Restrict MCP server permissions as needed\n\n## 📄 License\n\n[Apache License 2.0](https://github.com/markusvankempen/code-engine-mcp-server/blob/main/LICENSE) · [opensource.org/licenses/Apache-2.0](https://opensource.org/licenses/Apache-2.0)\n\n## 🤝 Contributing\n\nContributions are welcome! Please open an issue or submit a pull request (see [Contributing Guide](https://github.com/markusvankempen/code-engine-mcp-server/blob/main/docs/CONTRIBUTING.md)).\n\n## 🙋 Support\n\nFor issues and questions:\n- Check [Setup Instructions](https://github.com/markusvankempen/code-engine-mcp-server/blob/main/docs/SETUP_INSTRUCTIONS.md) and [MCP Inspector Troubleshooting](https://github.com/markusvankempen/code-engine-mcp-server/blob/main/docs/MCP_INSPECTOR_TROUBLESHOOTING.md)\n- Open an [issue](https://github.com/markusvankempen/code-engine-mcp-server/issues) with reproduction steps and logs\n\n---\n\n## Optional: MCP Activity Dashboard\n\n> **Core observability for MCP workflows.** Unlike provenance (signed receipts), activity logging is lightweight and off by default. Enable it when you want a live view of what the assistant is doing.\n\n| Surface | Command / URL |\n|---------|---------------|\n| VS Code / Cursor extension | **IBM Code Engine MCP: Open MCP Activity Dashboard** |\n| Browser (dev repo) | `npm run dashboard` → http://localhost:8767/ |\n| Event log file | `dashboard/activity/live/events.jsonl` |\n\n**Minimal MCP env:**\n\n```json\n\"MCP_ACTIVITY_ENABLED\": \"true\"\n```\n\nThe server creates the events file automatically. Use `MCP_ACTIVITY_SESSION_ID` and `MCP_ACTIVITY_CHAT_LABEL` to label sessions in the dashboard dropdown.\n\n**Troubleshooting:** If the dashboard shows no new sessions, confirm `MCP_ACTIVITY_ENABLED=true` in the MCP server env (not just chat context), restart the MCP server, and click **Show all activity** if you previously cleared the view.\n\n---\n\n## Optional addon: Provenance\n\n> **Not part of core MCP functionality.** The Code Engine MCP server deploys, builds, and manages apps without provenance. The [provenance addon](https://github.com/markusvankempen/code-engine-mcp-server/tree/main/provenance-addon) is an experimental optional layer that emits signed receipts for selected tool actions (default: **off**).\n\n| Doc | Purpose |\n|-----|---------|\n| [provenance-addon/README.md](https://github.com/markusvankempen/code-engine-mcp-server/blob/main/provenance-addon/README.md) | What receipts prove (and do not prove) |\n| [PROVENANCE-CHAT-COMMANDS.md](https://github.com/markusvankempen/code-engine-mcp-server/blob/main/provenance-addon/PROVENANCE-CHAT-COMMANDS.md) | Chat prompts when you choose to enable it |\n| [PROVENANCE-E2E-FLOW.md](https://github.com/markusvankempen/code-engine-mcp-server/blob/main/provenance-addon/PROVENANCE-E2E-FLOW.md) | Technical E2E flow |\n| [examples/startrek-splash/README.md](https://github.com/markusvankempen/code-engine-mcp-server/blob/main/examples/startrek-splash/README.md#documented-example-flow-verified-deploy) | Documented MCP deploy + optional receipts |\n\nEnable in `code-engine-mcp-server/.env` (`PROVENANCE_ENABLED=true`), restart MCP. With provenance on, `proc_build_push_deploy` returns `provenance_receipts` in its JSON response.\n\n**Example chat prompt (addon):**\n\n```\nUsing only Code Engine MCP tools, deploy examples/startrek-splash.\nProvenance on — show provenance_receipts, verify with verify-receipt.mjs, and give me the live URL.\n```\n\n---\n\n## Topics & keywords\n\n`code-engine` · `code-engine-mcp` · `code-engine-mcp-server` · `ibm-code-engine` · `ibm-cloud` · `ibm-container-registry` · `icr` · `serverless` · `knative` · `container-deployment` · `cloud-native` · `mcp` · `mcp-server` · `model-context-protocol` · `stdio` · `npx` · `cursor` · `vscode` · `openvscode` · `claude-desktop` · `github-copilot` · `cline` · `bob-ide` · `ai-agent` · `ai-agents` · `tool-calling` · `llm-tools` · `automation` · `typescript` · `nodejs` · `docker` · `podman` · `kubernetes` · `containers` · `deploy` · `devops` · `ci-cd` · `watsonx-orchestrate` · `ibm`\n\n---\n\n**Author:** Markus van Kempen\n**Email:** [markus.van.kempen@gmail.com](mailto:markus.van.kempen@gmail.com) · [mvk@ca.ibm.com](mailto:mvk@ca.ibm.com)\n**Website:** [markusvankempen.github.io](https://markusvankempen.github.io/)\n*No bug too small, no syntax too weird.*",
  "bytes": 56033,
  "sha": "a6cba36b198e976ad5468a66224eda900927751b757e86d32e3d39db6cf5ca78",
  "repo_slug": "markusvankempen/code-engine-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_markusvankempen_code_engine_mc_0997f8ae/readme"
}