code-engine-mcp-server
Advanced tools
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.
vscode-extension/# 1) Install dependencies
npm install
# 2) Build the server
npm run build
# 3) Run once to verify
node build/index.js
Then configure your MCP client using one of the examples in the Configuration section below.
This walks through deploying the included Star Wars splash page example โ a static nginx container โ entirely through the MCP server.
Apple Silicon users: always build with
--platform linux/amd64. Code Engine runs amd64 only.
cd examples/starwars-splash
podman build --platform linux/amd64 -t us.icr.io/<your-namespace>/starwars-splash:v1.0.0 .
podman push us.icr.io/<your-namespace>/starwars-splash:v1.0.0
Or ask your assistant:
Build examples/starwars-splash as us.icr.io/my-namespace/starwars-splash:v1.0.0 for linux/amd64 and push it
MCP response โ build_container_image:
{
"success": true,
"command": "podman build --platform linux/amd64 -t us.icr.io/my-namespace/starwars-splash:v1.0.0 ...",
"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"
}
Note: Container runtimes (Podman/Docker) write build progress to stderr. The
build_outputfield combines stdout and stderr so you see the full build log.
MCP response โ push_container_image:
{
"success": true,
"command": "podman push us.icr.io/my-namespace/starwars-splash:v1.0.0",
"output": "Getting image source signatures\nCopying blobs...\nWriting manifest to image destination"
}
Ask your assistant (once per project):
Create a registry secret called icr-pull-secret in project <project-id> for us.icr.io using my IBM Cloud API key
Or use the ce_create_secret tool directly:
{
"project_id": "<your-project-id>",
"name": "icr-pull-secret",
"format": "registry",
"data": {
"username": "iamapikey",
"password": "<your-ibm-cloud-api-key>",
"server": "us.icr.io",
"email": "user@example.com"
}
}
MCP response โ ce_create_secret:
{
"name": "icr-pull-secret",
"format": "registry",
"resource_type": "secret_registry_v2",
"created_at": "2026-05-08T22:10:00Z",
"project_id": "<your-project-id>"
}
Ask your assistant:
Deploy us.icr.io/my-namespace/starwars-splash:v1.0.0 to Code Engine project <project-id>
as app "starwars-splash" using pull secret icr-pull-secret, min 1 instance
Or use the ce_create_application tool:
{
"project_id": "<your-project-id>",
"name": "starwars-splash",
"image": "us.icr.io/<your-namespace>/starwars-splash:v1.0.0",
"image_secret": "icr-pull-secret",
"scale_min_instances": 1,
"scale_max_instances": 3
}
MCP response โ ce_create_application:
{
"name": "starwars-splash",
"resource_type": "app_v2",
"status": "deploying",
"image_reference": "us.icr.io/my-namespace/starwars-splash:v1.0.0",
"image_secret": "icr-pull-secret",
"image_port": 8080,
"scale_min_instances": 1,
"scale_max_instances": 3,
"scale_cpu_limit": "1",
"scale_memory_limit": "4G",
"endpoint": "https://starwars-splash.<subdomain>.us-south.codeengine.appdomain.cloud",
"status_details": {
"latest_created_revision": "starwars-splash-00001",
"latest_ready_revision": null
}
}
Get details for the starwars-splash app in project <project-id>
This calls ce_get_application and returns the public URL once the app reaches ready status.
List the running instances of starwars-splash in project <project-id>
This calls ce_list_app_instances (or ce_get_app_instance for a specific instance) and shows:
running / pending / failed)MCP response โ ce_get_application (once ready):
{
"name": "starwars-splash",
"status": "ready",
"image_reference": "us.icr.io/my-namespace/starwars-splash:v1.0.0",
"image_port": 8080,
"scale_min_instances": 1,
"scale_max_instances": 3,
"scale_cpu_limit": "0.5",
"scale_memory_limit": "1G",
"region": "us-south",
"endpoint": "https://starwars-splash.<subdomain>.us-south.codeengine.appdomain.cloud",
"status_details": {
"latest_created_revision": "starwars-splash-00001",
"latest_ready_revision": "starwars-splash-00001"
}
}
To 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.
5a โ Get a Let's Encrypt certificate (certbot)
# Install once
brew install certbot
# Request cert โ certbot will print a DNS TXT challenge value
mkdir -p ~/certbot/{config,work,logs}
/opt/homebrew/bin/certbot certonly --manual --preferred-challenges dns \
-d <your-domain> --agree-tos --no-eff-email --email you@example.com \
--config-dir ~/certbot/config --work-dir ~/certbot/work --logs-dir ~/certbot/logs
Certbot will pause and ask you to add a TXT record:
Add TXT record: _acme-challenge.<your-domain> = <challenge-value>
Verify propagation, then press Enter. Certbot writes:
~/certbot/config/live/<your-domain>/fullchain.pem~/certbot/config/live/<your-domain>/privkey.pem5b โ Create the TLS secret in Code Engine
Ask your assistant:
Create a TLS secret called starwars-tls in project <project-id>
using cert ~/certbot/config/live/myapp.example.com/fullchain.pem
and key ~/certbot/config/live/myapp.example.com/privkey.pem
This calls ce_create_tls_secret_from_pem โ reads the PEM files from disk and stores them as a Code Engine tls secret.
MCP response โ ce_create_tls_secret_from_pem:
{
"name": "my-tls",
"format": "tls",
"resource_type": "secret_tls_v2",
"created_at": "2026-05-08T22:30:00Z",
"project_id": "<your-project-id>"
}
5c โ Create the domain mapping
Ask your assistant:
Map domain myapp.example.com to app my-app
in project <project-id> using TLS secret my-tls
This calls ce_create_domain_mapping and returns the cname_target.
MCP response โ ce_create_domain_mapping:
{
"name": "myapp.example.com",
"status": "ready",
"cname_target": "custom.<subdomain>.us-south.codeengine.appdomain.cloud",
"component": {
"resource_type": "app_v2",
"name": "my-app"
},
"tls_secret": "my-tls",
"region": "us-south"
}
5d โ Update your CNAME
In your DNS provider, set:
myapp.example.com CNAME custom.<subdomain>.us-south.codeengine.appdomain.cloud
Use the cname_target value returned in 5c (it uses the custom. prefix, not the app name).
Once DNS propagates, https://<your-domain> serves the app with a valid TLS certificate.
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.
I have a Star Wars splash page in examples/starwars-splash.
Build it for linux/amd64 as us.icr.io/my-namespace/starwars-splash:v1.0.0,
push it, then deploy it to Code Engine project <project-id> with pull secret icr-pull-secret.
Tell me the public URL and confirm the instance is running.
mcp.json required for the default npx flow)code-engine-mcp-server/
โโโ api/
โ โโโ code-engine-openapi.yaml # OpenAPI reference used for API coverage
โโโ build/ # Compiled JavaScript output
โโโ docs/ # API references and setup guides
โโโ internal/ # Internal release/publishing 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)
โโโ package.json # npm package metadata and scripts
โโโ server.json # MCP Registry metadata
โโโ tsconfig.json # TypeScript configuration
ce_validate_dockerfile) โ checks architecture, port, nginx sed patterns, USER, CMDce_create_tls_secret_from_pem)ce_renew_tls_secret_from_pem)ce_update_secret)ce_wait_for_app_ready, ce_wait_for_build_run)iam_get_token_info)icr_create_namespace)proc_build_push_deploy โ full container pipeline in one prompt (build โ push โ deploy โ wait)proc_setup_custom_domain โ TLS cert + domain mapping in one step, returns CNAME targetproc_build_run_and_deploy โ CE source build โ wait โ deploy app โ wait โ return URLThe 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.
.vsix built with npm run package inside vscode-extension/, or from the Marketplace when published).npx is on your PATH.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.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.
More detail: vscode-extension/README.md.
mcp.json (workspace)Copy mcp.example.json to .vscode/mcp.json in your workspace root:
cp mcp.example.json ../.vscode/mcp.json
Then edit .vscode/mcp.json and replace the placeholder with your IBM Cloud API key:
{
"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"
}
}
}
}
Restart the server: Cmd+Shift+P -> "MCP: Restart Server" -> code-engine.
Security: Add
.vscode/mcp.jsonto your.gitignoreto avoid committing your API key.
Get your API key at IBM Cloud IAM โ API keys.
{
"cline.mcpServers": {
"code-engine": {
"command": "node",
"args": ["/absolute/path/to/code-engine-mcp-server/build/index.js"],
"env": {
"IBMCLOUD_API_KEY": "your-api-key-here"
}
}
}
}
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"],
"env": {
"IBMCLOUD_API_KEY": "your-api-key-here"
}
}
}
}
Use the published package from npm or browse the MCP Registry listing:
Ask your assistant:
Can you detect which container runtime I have installed?
Ask your assistant:
Build a container image from ./Dockerfile with the name myapp:latest
Ask your assistant:
Test the myapp:latest image locally on port 8080
Ask your assistant:
Push myapp:latest to icr.io/my-namespace/myapp:latest
Ask your assistant:
List all my Code Engine projects
Ask your assistant:
I have a Node.js app in ./my-app with a Dockerfile. Can you:
1. Build it as myapp:v1.0.0
2. Test it locally on port 3000
3. Push it to icr.io/my-namespace/myapp:v1.0.0
4. Deploy it to my Code Engine project "production"
5. Show me the application URL
Ask your assistant:
Create a TLS secret called my-tls in project <project-id>
using cert ~/certbot/config/live/example.com/fullchain.pem
and key ~/certbot/config/live/example.com/privkey.pem.
Then map domain example.com to app my-app using that secret.
Tell me what CNAME value to set in DNS.
62 tools total: 9 container tools + 4 ICR tools + 45 Code Engine tools + 1 IAM tool + 3 procedures.
Procedures bundle multiple tools into a single call. Use them for common end-to-end workflows.
| Tool | Description | Key Parameters |
|---|---|---|
detect_container_runtime | Detect Docker or Podman | โ |
list_local_images | List local container images | runtime |
list_local_containers | List local containers | runtime, all |
build_container_image | Build a container image | dockerfile_path, image_name, context_path |
push_container_image | Push image to registry | image_name, runtime |
test_container_locally | Run container for local testing | image_name, port_mapping, env_vars |
get_container_logs | Get logs from a running container | container_id, runtime |
stop_local_container | Stop and remove a container | container_id, runtime |
ce_validate_dockerfile | Validate a Dockerfile for Code Engine compatibility (architecture, port, nginx sed patterns, USER, CMD) | dockerfile_path, context_path, expected_port |
| Tool | Description | Key Parameters |
|---|---|---|
icr_list_namespaces | List ICR namespaces in your account | region |
icr_list_images | List images in ICR (optionally filtered by namespace) | namespace, region |
icr_delete_image | Delete an image by full tag | image, region |
icr_create_namespace | Create a new ICR namespace | namespace, region |
| Tool | Description | Key Parameters |
|---|---|---|
ce_list_projects | List all projects in a region | โ |
ce_get_project | Get project details | project_id |
ce_create_project | Create a new project | name, resource_group_id |
ce_delete_project | Delete a project | project_id |
| Tool | Description | Key Parameters |
|---|---|---|
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_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 |
ce_get_app_logs | Get logs for an app instance | project_id, app_name, instance_name |
ce_wait_for_app_ready | Poll until app status is ready or timeout; returns poll_history | project_id, app_name, timeout_seconds |
| Tool | Description | Key Parameters |
|---|---|---|
ce_list_builds | List build configurations | project_id |
ce_get_build | Get build configuration details | project_id, build_name |
ce_create_build | Create a build configuration | project_id, name, output_image, output_secret |
ce_delete_build | Delete a build configuration | project_id, build_name |
ce_list_build_runs | List build runs | project_id |
ce_get_build_run | Get build run status | project_id, build_run_name |
ce_create_build_run | Start a build run | project_id, build_name |
ce_delete_build_run | Delete a build run | project_id, build_run_name |
ce_wait_for_build_run | Poll until build run succeeds or fails; returns poll_history | project_id, build_run_name, timeout_seconds |
| Tool | Description | Key Parameters |
|---|---|---|
ce_list_jobs | List job definitions | project_id |
ce_get_job | Get job definition details | project_id, job_name |
ce_create_job | Create a job definition | project_id, name, image |
ce_delete_job | Delete a job definition | project_id, job_name |
ce_list_job_runs | List job runs | project_id, job_name (optional) |
ce_get_job_run | Get job run status | project_id, job_run_name |
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 |
| Tool | Description | Key Parameters |
|---|---|---|
ce_list_secrets | List secrets (names + keys only) | project_id |
ce_get_secret | Get secret metadata (no values) | project_id, secret_name |
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_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 |
| Tool | Description | Key Parameters |
|---|---|---|
ce_list_config_maps | List configmaps | project_id |
ce_get_config_map | Get configmap details | project_id, config_map_name |
ce_create_config_map | Create a configmap | project_id, name, data |
ce_delete_config_map | Delete a configmap | project_id, config_map_name |
| Tool | Description | Key Parameters |
|---|---|---|
ce_list_domain_mappings | List all custom domain mappings | project_id |
ce_get_domain_mapping | Get status and CNAME target for a mapping | project_id, domain_name |
ce_create_domain_mapping | Map a custom domain to an app | project_id, domain_name, app_name, tls_secret |
ce_delete_domain_mapping | Delete a custom domain mapping | project_id, domain_name |
| Tool | Description | Key Parameters |
|---|---|---|
iam_get_token_info | Inspect the current IAM token โ account, expiry, validity | โ |
| Tool | What it does | Key Parameters |
|---|---|---|
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 |
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 |
proc_build_run_and_deploy | Start CE build run โ wait for success โ create/update app โ wait for ready โ return URL + build_poll_history + app_poll_history | project_id_or_name, build_name, app_name, image_secret, port, build_timeout_seconds, deploy_timeout_seconds |
IBMCLOUD_API_KEY: IBM Cloud API key (required for Code Engine operations)IBMCLOUD_REGION: Default IBM Cloud region (optional, defaults to us-south)CONTAINER_RUNTIME: Force specific runtime (docker or podman)DEBUG: Enable debug loggingThe MCP server communicates directly with the IBM Cloud REST API and ICR API. No IBM Cloud CLI or Code Engine plugin is required.
# Run in development mode
npm run dev
# Build
npm run build
# Test manually
node build/index.js
node --versionls build/index.jsnode build/index.jsdocker --version or podman --versionIBMCLOUD_API_KEY in your MCP client configus-south); set IBMCLOUD_REGION if neededce_list_projects to find itMIT (see LICENSE)
Contributions are welcome! Please open an issue or submit a pull request (see Contributing Guide).
Markus van Kempen
Email: markus.van.kempen@gmail.com | mvankempen@ca.ibm.com
Website: markusvankempen.github.io
Research | Floor 7 1/2
For issues and questions:
FAQs
IBM Code Engine MCP Server - deploy containers to IBM Cloud Code Engine from Cursor, Copilot, Claude, and Cline using natural language
The npm package code-engine-mcp-server receives a total of 117 weekly downloads. As such, code-engine-mcp-server popularity was classified as not popular.
We found that code-engine-mcp-server demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago.ย It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
During a UK cyber test, a Mythos 5 agent used sockpuppets, social engineering, and prompt injection to try to get a maintainer to merge malware.
Company News
Socket is now in the AWS Security Hub Extended plan. Adopt it through AWS, apply committed spend, and block malicious open source packages.
Research
/Security News
Popular npm packages keyv and cacheable compromised.