1Panel MCP Docker Image: Containerized Server Guide

Quick answer: Pull the official 1Panel MCP server container image, set the transport mode (SSE or STDIO) via environment variables, and start the container with the necessary ports and secrets. Example: docker run -d --name mcp -p 8080:8080 -e MCP_TRANSPORT=sse 1panel/mcp:latest.

This article explains which image to use, how to run it in Docker (single host and Compose), the differences between SSE and STDIO transports, and best practices for environment variable and secret management for production deployments.

For the official reference image and additional implementation notes, see the 1Panel MCP docs: 1Panel MCP server container image.

Which container image to use and how to pull it

Use the official 1Panel MCP server container image published by the project maintainers. The image contains the runtime binary, minimal OS layer, and the default configuration entrypoint so you can run it directly with Docker. Using the project’s official image reduces surprises and ensures compatibility with the documented transport modes (SSE and STDIO).

Pull the image with a simple docker command. Replace latest with a specific tag for predictable upgrades in production (for example, a semver tag):

docker pull 1panel/mcp:latest
# or pin a version
docker pull 1panel/mcp:v1.2.3

If you want the authoritative link and supported tags, consult the project’s container documentation: 1Panel MCP server container image docs. Pinning image tags and scanning them for CVEs should be part of your CI/CD pipeline.

Running the container: examples and configuration patterns

The simplest run command exposes the server port and sets the transport mode. In many test scenarios, you can start the server like this:

docker run -d \
  --name mcp \
  -p 8080:8080 \
  -e MCP_TRANSPORT=sse \
  1panel/mcp:latest

For reproducible and multi-variable setups prefer Docker Compose or an env file. Compose lets you define environment variables, volumes, and restart policies in a declarative way. Here is a minimal Compose fragment:

version: "3.8"
services:
  mcp:
    image: 1panel/mcp:latest
    ports:
      - "8080:8080"
    environment:
      - MCP_TRANSPORT=sse
      - MCP_LOG_LEVEL=info
    restart: unless-stopped

In production, use restart policies, resource limits, and read-only root filesystems where possible. Also use healthchecks to let orchestrators detect failed containers and trigger restarts.

Transport modes: SSE vs STDIO — when to use each

1Panel MCP supports two common transport approaches: SSE (Server-Sent Events) and STDIO. SSE streams event updates over an HTTP connection and is best when the MCP server and clients are communicating across networks or when proxies are involved. STDIO communicates over the process standard input/output and is commonly used when MCP is launched and managed locally or embedded into another process.

SSE advantages: it works well with load balancers and reverse proxies that support long-lived HTTP connections, and it enables reconnection semantics for clients. SSE is straightforward for browser-based or networked clients that can receive a continuous event stream. STDIO advantages: lower overhead when MCP is run as a child process or managed by a supervisor, and easier if your agent framework expects stdin/stdout framing.

Operational considerations: SSE needs proper proxy configuration to avoid buffering (disable buffering or use proxy buffering off). STDIO requires container logs to be captured reliably (systemd, journald, or container log drivers). Choose SSE for distributed setups and STDIO for tightly coupled or local process deployments.

Managing environment variables and secrets in containers

Environment variables are the primary configuration mechanism for containerized 1Panel MCP. Use them to set transport mode, ports, log level, and secret tokens. Common env vars you will encounter include MCP_TRANSPORT, MCP_PORT, MCP_LOG_LEVEL, and MCP_SECRET_TOKEN (names can vary by image version — always check the image docs linked above).

Best practices for secrets: never bake secrets into images or keep them in plaintext in VCS. For Docker, use Docker secrets (in Swarm) or pass secrets from the host at runtime. For Kubernetes, store confidential values in a Secret and mount them as environment variables or files. Use an external secret manager (HashiCorp Vault, AWS Secrets Manager) if your deployment requires rotation and auditability.

Sample secure patterns:
– Use an env_file for non-sensitive variables and mount secrets via Docker Secrets or Kubernetes Secrets.
– Limit container privileges and mount config as read-only where possible.
– Rotate tokens by tooling in your CI/CD pipeline and avoid long-lived static credentials in images.

Semantic core (expanded keywords and clusters)

The following grouped keyword clusters are crafted for SEO and natural-language coverage. They should be used organically in documentation, headings, and alt text.

• Primary: 1Panel MCP server container image, Docker container image for 1Panel MCP, containerized deployment 1Panel MCP, running 1Panel MCP server with Docker
• Secondary: 1Panel MCP Docker Hub image, transport modes SSE, transport mode STDIO, deploying 1Panel MCP server with container
• Clarifying / Related: 1Panel MCP environment variables management, MCP Docker environment variables, 1Panel MCP Docker Compose, container deployment best practices, MCP secrets and Docker secrets

Deployment patterns, orchestration, and troubleshooting

For single-node installs use Docker Compose. For scalable or HA scenarios prefer Kubernetes or a container orchestrator that handles scheduling, secrets, and rolling updates. In Kubernetes, run MCP as a Deployment or StatefulSet depending on whether you need stable identities and persistent data.

Common troubleshooting steps:
– Check container logs (docker logs mcp) for transport negotiation errors.
– Confirm the transport mode matches client expectations (SSE vs STDIO).
– Validate that any reverse proxy preserves SSE (no buffering) and that TLS is configured if exposing SSE to the public internet.

If your MCP instance fails to start, inspect environment variables, mount points, and file permissions. For STDIO mode ensure the supervising process captures and forwards stdin/stdout correctly; for SSE ensure the HTTP port is reachable and proxy timeouts are large enough for long-lived streams.

Practical tips and examples

Tip 1: Pin your image tag in CI to avoid unexpected breaks. Use automated image scanning. Tip 2: Use healthchecks so orchestrators can detect non-responsive MCP instances and restart them. Tip 3: Test both SSE and STDIO in staging to confirm behavior under your load and reverse-proxy setup.

Example: start with SSE in a dev environment behind an nginx reverse proxy. Configure nginx with chunked transfer and disable proxy buffering to preserve event streaming. For STDIO, run MCP as a child process inside a supervisor container and stream logs to a centralized logging service.

Reference and image downloads: consult the official documentation and image listing for authoritative configuration values and supported tags: 1Panel MCP server container image documentation.

Common environment variables (examples)

Below are example variable names and purposes. Exact names can differ by image version—confirm with the image docs.

• MCP_TRANSPORT — transport mode, values: sse or stdio.
• MCP_PORT — HTTP listen port (default typically 8080).
• MCP_LOG_LEVEL — logging verbosity (info, warn, debug).
• MCP_SECRET_TOKEN — secret token for agent authentication (store in secrets manager).

Set these via -e flags, an env_file, Docker Secrets, or Kubernetes Secrets for production security. Avoid embedding secrets into images or VCS.

FAQ

1. Which transport should I choose: SSE or STDIO?

SSE is the right choice when MCP communicates over the network or through proxies and you need long-lived HTTP event streams. STDIO is better for local process integration where MCP runs as a child process and communicates via stdin/stdout. Test both under your expected topology; SSE generally fits distributed setups while STDIO suits embedded/local deployments.

2. How do I securely manage MCP environment variables and secrets in Docker?

Never bake secrets into images. Use Docker Secrets (or Kubernetes Secrets) to inject confidential values at runtime, mount secrets as files if supported, and integrate an external secret manager for rotation and auditing. For non-sensitive configuration, use env files or Compose environment blocks, but keep sensitive values out of source control.

3. How can I ensure SSE works correctly behind my reverse proxy?

Configure your reverse proxy to disable buffering for SSE endpoints, increase timeouts to allow long-lived connections, and ensure it preserves chunked transfer encoding. On nginx, turn off proxy buffering and set appropriate timeout values; on HAProxy or cloud load balancers, set TCP timeouts to avoid prematurely closing the SSE stream.

Need a ready-to-run Compose example, Kubernetes manifest, or a quick troubleshooting checklist tailored to your environment? Reply with your target runtime (Docker Engine, Docker Compose, Kubernetes) and your chosen transport mode and I’ll produce a copy-paste manifest.