dynamic-mcp

A production-grade dynamic MCP server for Node.js that enables runtime tool creation, management, and execution in isolated execution sandboxes (docker or node).

Unlike static MCP servers that define tools at compile time, dynamic-mcp lets AI agents and operators create, update, and delete tools on the fly with full lifecycle management.

Key Features

Runtime tool management — Create, update, delete, enable/disable tools without restarts via the dynamic.tool.* control plane
Execution backend selection — auto (Docker preferred, Node fallback), or force docker / node
Dual transport — Stdio for local/CLI use, Streamable HTTP for networked deployments with per-session MCP servers
Dual registry backend — File-based (single node) or PostgreSQL (multi-instance) with optimistic concurrency control
Execution guard — Global concurrency and per-scope rate limiting to prevent abuse
JWT authentication — Optional JWKS-based token verification for HTTP mode
Audit logging — Structured JSONL logs with rotation, redaction of sensitive fields, and shutdown flush
Experimental upstream attach — Optional feature-flagged upstream.mcp.attach for lazy discovery of existing MCP servers
Two profiles — mvp (default) for core functionality, enterprise for long-lived sandbox sessions, metrics, and ops tools
Production-ready — Health probes, Prometheus metrics, graceful shutdown, Kubernetes manifests, Docker Compose baselines

Quick Start

Prerequisites: Node.js >= 20 (Docker recommended)

Fastest way to run stdio (no clone/build):

npx -y dynamic-mcp --transport stdio --profile mvp
# optional: pin version for reproducibility
npx -y dynamic-mcp@<version> --transport stdio --profile mvp

From source (local development):

# Install dependencies
pnpm install

# Run in stdio mode (default, mvp profile)
pnpm run dev

# Run in HTTP mode
pnpm run dev:http

# Run with enterprise profile
pnpm run dev:enterprise

HTTP mode default endpoint: http://127.0.0.1:8788/mcp

Recommended Operating Modes

Development / PoC: mvp profile + stdio transport + file backend (.env.example)
Production: enterprise profile + http transport + JWT auth + PostgreSQL backend (.env.prod.example)

MCP Server Configuration

This project supports both MCP standard transports:

stdio (recommended for local development/CLI clients)
Streamable HTTP (recommended for remote/network deployment)

1. Stdio Runtime Options

Most MCP clients launch your server as a child process in stdio mode.

Option A (recommended for quick setup): run from npm with npx:

npx -y dynamic-mcp --transport stdio --profile mvp

Option B (recommended when developing this repo): build local runtime first:

pnpm install
pnpm build

Then use an absolute path to dist/index.js in client config. Example:

node /ABS/PATH/TO/dynamic-mcp/dist/index.js --transport stdio --profile mvp

Dynamic code execution features use the selected execution backend (docker or node). Note: sandbox.* tools remain Docker-based; in environments without Docker, use mvp profile or avoid sandbox.*. Execution backend can be controlled with MCP_EXECUTION_ENGINE / --execution-engine:

auto (default): use Docker when available, fallback to Node sandbox when Docker is unavailable
docker: force Docker
node: force Node sandbox (no dynamic dependency installation)

If Docker is not installed and you want the MCP server to default to Node immediately, set MCP_EXECUTION_ENGINE=node in the client config or append --execution-engine node to the launch command:

npx -y dynamic-mcp --transport stdio --profile mvp --execution-engine node

2. Claude Desktop (Local stdio)

Claude Desktop uses a local claude_desktop_config.json file with mcpServers.

macOS path: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows path: %APPDATA%\Claude\claude_desktop_config.json

Example:

{
  "mcpServers": {
    "dynamic-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "dynamic-mcp",
        "--transport",
        "stdio",
        "--profile",
        "mvp"
      ],
      "env": {
        "MCP_DYNAMIC_BACKEND": "file",
        "MCP_DYNAMIC_STORE": "/ABS/PATH/TO/dynamic-mcp/.dynamic-mcp/tools.json",
        "MCP_SANDBOX_DOCKER_BIN": "docker"
      }
    }
  }
}

If Docker is not installed, configure the server to use Node explicitly:

{
  "mcpServers": {
    "dynamic-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "dynamic-mcp",
        "--transport",
        "stdio",
        "--profile",
        "mvp"
      ],
      "env": {
        "MCP_DYNAMIC_BACKEND": "file",
        "MCP_DYNAMIC_STORE": "/ABS/PATH/TO/dynamic-mcp/.dynamic-mcp/tools.json",
        "MCP_EXECUTION_ENGINE": "node"
      }
    }
  }
}

Note: Claude Desktop remote MCP server management is done in app settings (Settings -> Connectors), not in claude_desktop_config.json.

3. Claude Code

Add local stdio server:

claude mcp add dynamic-mcp -- npx -y dynamic-mcp --transport stdio --profile mvp

If Docker is not installed:

claude mcp add dynamic-mcp -- npx -y dynamic-mcp --transport stdio --profile mvp --execution-engine node

Add remote HTTP server:

claude mcp add --transport http dynamic-mcp-http http://127.0.0.1:8788/mcp

Project-level .mcp.json example (supports both local and remote server definitions):

{
  "mcpServers": {
    "dynamic-mcp-local": {
      "command": "npx",
      "args": [
        "-y",
        "dynamic-mcp",
        "--transport",
        "stdio",
        "--profile",
        "enterprise"
      ]
    },
    "dynamic-mcp-http": {
      "type": "http",
      "url": "http://127.0.0.1:8788/mcp",
      "authorization_token": "${DYNAMIC_MCP_JWT_TOKEN}"
    }
  }
}

If Docker is not installed, add "env": { "MCP_EXECUTION_ENGINE": "node" } to the local server entry or append "--execution-engine", "node" to its args.

Claude Code supports environment variable expansion in config values, including ${VAR} and ${VAR:-default}.

4. VS Code

Use workspace config file: .vscode/mcp.json.

Local stdio example:

{
  "servers": {
    "dynamic-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "dynamic-mcp",
        "--transport",
        "stdio",
        "--profile",
        "mvp"
      ],
      "env": {
        "MCP_DYNAMIC_BACKEND": "file",
        "MCP_SANDBOX_DOCKER_BIN": "docker"
      }
    }
  }
}

If Docker is not installed, set the execution engine to Node:

{
  "servers": {
    "dynamic-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "dynamic-mcp",
        "--transport",
        "stdio",
        "--profile",
        "mvp"
      ],
      "env": {
        "MCP_DYNAMIC_BACKEND": "file",
        "MCP_EXECUTION_ENGINE": "node"
      }
    }
  }
}

Remote HTTP + JWT header example:

{
  "servers": {
    "dynamic-mcp-http": {
      "url": "http://127.0.0.1:8788/mcp",
      "headers": {
        "Authorization": "Bearer ${input:dynamic_mcp_jwt}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "dynamic_mcp_jwt",
      "description": "JWT Bearer token for dynamic-mcp"
    }
  ]
}

5. HTTP Mode Details for This Repo

Server startup example:

pnpm run dev:http
# or:
node /ABS/PATH/TO/dynamic-mcp/dist/index.js --transport http --host 127.0.0.1 --port 8788 --path /mcp
# or:
npx -y dynamic-mcp --transport http --host 127.0.0.1 --port 8788 --path /mcp

In HTTP mode, the server runs as an independent process/container, and MCP clients connect to the configured URL.

HTTP endpoints:

POST /mcp initialize/continue MCP session
GET /mcp session stream
DELETE /mcp close session
GET /livez liveness
GET /readyz readiness
GET /metrics Prometheus metrics

JWT behavior in this repo:

When MCP_AUTH_MODE=jwt, authentication is enforced on MCP endpoint requests (${MCP_PATH}, default /mcp).
/livez, /readyz, /metrics remain anonymous by default.

Production recommendation: keep /livez, /readyz, /metrics behind private networking, ingress allowlists, or a gateway even when JWT is enabled.

6. Minimal Secure Baseline (Recommended)

MCP_TRANSPORT=http
MCP_PROFILE=enterprise
MCP_HOST=0.0.0.0
MCP_PORT=8788
MCP_PATH=/mcp
MCP_EXECUTION_ENGINE=auto
MCP_DYNAMIC_BACKEND=postgres
MCP_REQUIRE_ADMIN_TOKEN=true
MCP_ADMIN_TOKEN=change-me
MCP_AUTH_MODE=jwt
MCP_AUTH_JWKS_URL=https://your-idp.example.com/.well-known/jwks.json
MCP_AUTH_ISSUER=https://your-idp.example.com/
MCP_AUTH_AUDIENCE=dynamic-mcp
MCP_AUTH_REQUIRED_SCOPES=mcp.invoke
# Optional experimental feature (enterprise only)
MCP_EXPERIMENTAL_UPSTREAM_MCP_ATTACH=false
MCP_EXPERIMENTAL_UPSTREAM_MCP_ATTACH_MAX=8

Full variable reference: docs/configuration.md

Production baseline assets:

Documentation

Document	Description
Architecture	System design, module structure, and data flow
Configuration	All environment variables and CLI arguments
API Reference	Complete tool, resource, and prompt reference
Dynamic Tools Guide	How to author and manage dynamic tools
Security	Security model, sandbox isolation, and authentication
Deployment	Docker, Compose, and Kubernetes deployment guides
Production Runbook	Production rollout, verification, and rollback steps

Profiles

MVP (default)

Core dynamic tool engine:

Tool	Description
`dynamic.tool.create`	Register a new dynamic tool
`dynamic.tool.update`	Modify an existing tool definition
`dynamic.tool.delete`	Remove a tool
`dynamic.tool.list`	List all registered tools
`dynamic.tool.get`	Get a single tool definition
`dynamic.tool.enable`	Enable or disable a tool
`run_js_ephemeral`	One-off JavaScript execution in a sandbox
`system.health`	Server liveness and uptime

Enterprise

Everything in MVP, plus:

Tool / Resource	Description
`sandbox.initialize`	Create a reusable container session
`sandbox.exec`	Run shell commands in a session
`sandbox.run_js`	Run JavaScript in a session
`sandbox.stop`	Stop a session container
`sandbox.session.list`	List active sessions
`system.guard_metrics`	Concurrency/rate-limit counters
`system.runtime_config`	Sanitized config snapshot
`dynamic://metrics/guard`	Guard metrics resource
`dynamic://service/runtime-config`	Config snapshot resource
`dynamic://service/meta`	Service metadata resource
`tool-call-checklist`	Reusable pre-call checklist prompt
`upstream.mcp.attach`	Experimental upstream MCP attach*
`upstream.mcp.detach`	Experimental upstream MCP detach*

* Registered only when MCP_EXPERIMENTAL_UPSTREAM_MCP_ATTACH=true.

Experimental Upstream MCP Attach

Enable with feature flag (enterprise profile only):

MCP_PROFILE=enterprise
MCP_EXPERIMENTAL_UPSTREAM_MCP_ATTACH=true
MCP_EXPERIMENTAL_UPSTREAM_MCP_ATTACH_MAX=8
MCP_ADMIN_TOKEN=change-me

This registers upstream.mcp.attach and upstream.mcp.detach. attach can connect to an existing MCP server (stdio or http) and return its current listTools output.

Current scope is intentionally narrow:

Supported: attach + tool discovery
Supported: attach + detach + tool discovery
Not yet supported: runtime mount/unmount/proxy of upstream tools into dynamic-mcp tool namespace

Security boundary:

transport=stdio can spawn local processes; treat it as privileged
MCP_ADMIN_TOKEN is required when this feature flag is enabled
Pair with MCP_REQUIRE_ADMIN_TOKEN=true and MCP_ADMIN_TOKEN=...

Example: Creating a Dynamic Tool

{
  "tool": {
    "name": "text.uppercase",
    "description": "Convert text to uppercase",
    "code": "const { text } = args;\nreturn { upper: String(text).toUpperCase() };",
    "dependencies": [],
    "image": "node:lts-slim",
    "timeoutMs": 10000
  }
}

Then invoke it:

{
  "args": { "text": "hello world" }
}

See the Dynamic Tools Guide for full details.

Docker

docker build -t dynamic-mcp:latest .
docker run --rm -p 8788:8788 dynamic-mcp:latest

When MCP_EXECUTION_ENGINE=auto (default), dynamic tool execution (dynamic.*, run_js_ephemeral) uses Docker when available and falls back to Node sandbox when Docker is unavailable.

sandbox.* tools remain Docker-based. For those tools in containerized deployments, the running dynamic-mcp process must have:

A Docker CLI binary available in the container (docker)
Connectivity and authorization to a Docker daemon (local socket or remote daemon)

Without that Docker access, sandbox.* calls fail at runtime.

Security note: exposing the host Docker socket gives the container high privilege over the host. Prefer a dedicated remote Docker daemon with network isolation and TLS for production.

Docker Compose (with PostgreSQL)

docker compose -f deploy/docker-compose.postgres.yml up -d --build

Kubernetes

kubectl apply -f deploy/k8s/dynamic-mcp-postgres.yaml
# Optional: HPA + PDB
kubectl apply -f deploy/k8s/dynamic-mcp-scalability.yaml
# Optional: Network policy
kubectl apply -f deploy/k8s/dynamic-mcp-networkpolicy.yaml

Development

pnpm run dev          # stdio mode, mvp profile
pnpm run dev:mvp      # explicit mvp profile
pnpm run dev:http     # HTTP mode
pnpm run dev:enterprise  # enterprise profile
pnpm run test         # run tests
pnpm run lint         # lint
pnpm run typecheck    # type check
pnpm run build        # compile TypeScript

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 61 Commits
.github/workflows		.github/workflows
deploy		deploy
docs		docs
src		src
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.env.prod.example		.env.prod.example
.gitignore		.gitignore
.nvmrc		.nvmrc
.prettierignore		.prettierignore
.prettierrc.json		.prettierrc.json
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
eslint.config.mjs		eslint.config.mjs
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

dynamic-mcp

Key Features

Quick Start

Recommended Operating Modes

MCP Server Configuration

1. Stdio Runtime Options

2. Claude Desktop (Local stdio)

3. Claude Code

4. VS Code

5. HTTP Mode Details for This Repo

6. Minimal Secure Baseline (Recommended)

Documentation

Profiles

MVP (default)

Enterprise

Experimental Upstream MCP Attach

Example: Creating a Dynamic Tool

Docker

Docker Compose (with PostgreSQL)

Kubernetes

Development

License

About

Uh oh!

Releases 5

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

dynamic-mcp

Key Features

Quick Start

Recommended Operating Modes

MCP Server Configuration

1. Stdio Runtime Options

2. Claude Desktop (Local stdio)

3. Claude Code

4. VS Code

5. HTTP Mode Details for This Repo

6. Minimal Secure Baseline (Recommended)

Documentation

Profiles

MVP (default)

Enterprise

Experimental Upstream MCP Attach

Example: Creating a Dynamic Tool

Docker

Docker Compose (with PostgreSQL)

Kubernetes

Development

License

About

Topics

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 5

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages