Docker Servers

Docker servers are the most common MCP setup. TeamWeb AI pulls or builds a Docker image, runs a container, and connects to it automatically.

Creating a Docker Server

Navigate to MCP Servers in the sidebar and click New MCP Server. Set the runtime to Docker and choose a transport type.

Basic Fields

Name — A unique name for the server (e.g., “GitHub”, “Filesystem”)
Description — Optional description of what the server does
Docker Image — The base image to use (default: node:20-slim)
Command — The command to run inside the container
Environment Variables — One per line in KEY=value format. Use these for API tokens and configuration.

npm Packages

Many MCP servers are published as npm packages. For these, enter the package name as the command and TeamWeb AI handles installation automatically:

@modelcontextprotocol/server-github

TeamWeb AI detects that this is a bare package name and installs it before running.

stdio Transport

The simplest setup. TeamWeb AI starts a container, connects over stdin/stdout, and removes the container when the session ends.

Create the server

Go to MCP Servers > New MCP Server. Set runtime to Docker and transport to stdio.

Set the command

Enter the npm package name or command:

@modelcontextprotocol/server-github

Add environment variables

Add any required API tokens:

GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here

Test the connection

Save and click Test Connection on the detail page. TeamWeb AI pulls the image, starts the container, and discovers the available tools.

HTTP Transports (SSE / Streamable HTTP)

For servers that communicate over HTTP rather than stdio, additional options are available:

Server Port — The port the server listens on inside the container (default: 8080)
Endpoint Path — The HTTP path for the transport endpoint (default: /sse)
Keep Running — When enabled, the container stays running between sessions instead of being created fresh each time. Useful for servers with expensive startup or persistent state.

For stdio servers, a fresh container is always created per session. The keep-running option only applies to HTTP transports.

Container Management

The server detail page shows the current container status:

Running — The container is active. A Stop button is available for persistent containers.
Exited — The container exists but is not running.
Not running — No container exists. It will be created on next use.

For stdio servers, containers are always ephemeral and created fresh each session. For HTTP servers with keep-running enabled, containers persist and can be stopped manually.

Technical Details

stdio transport internals — For stdio transport, TeamWeb AI creates a Docker container, attaches to its stdin and stdout streams, and bridges them to an internal message queue. Messages between TeamWeb AI and the MCP server are exchanged as length-prefixed JSON-RPC frames over these streams. The container is automatically removed when the agent loop finishes.

HTTP transport startup — For SSE and Streamable HTTP transports, the container exposes a port on the Docker network. After starting the container, TeamWeb AI performs TCP health checks on that port to verify the server is ready before establishing the MCP session. This prevents connection failures from servers that take time to start up.

Configuration change detection — When TeamWeb AI starts a container for an MCP server, it checks whether the running container’s configuration (image, command, entrypoint) matches the current server settings. If the configuration has changed — for example, you updated the Docker image or command — the old container is automatically removed and a new one is created with the updated settings.

Background cleanup — A periodic background task runs every 5 minutes and removes orphaned or inactive MCP containers. This catches containers that were left behind due to unexpected shutdowns or containers that belong to servers that have been deleted or disabled.

External Servers