Skip to main content
Mcpjungle supports MCP servers that use the STDIO transport. These servers run as child processes on the same host as the Mcpjungle server and communicate through standard input and output. Common examples include filesystem and time. Because STDIO servers run as local processes, you must register them using a JSON config file — the CLI flags only cover Streamable HTTP registration.

​
Register a STDIO server

1

Write a config file

Create a JSON file describing your server. Here is an example for the official MCP filesystem server:
{
  "name": "filesystem",
  "transport": "stdio",
  "description": "Filesystem MCP server",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
}
2

Register with Mcpjungle

Pass the file to the register command with the -c flag:
mcpjungle register -c ./filesystem.json
Mcpjungle spawns the process, initializes the connection, loads its tool list, and registers the server.

​
Config file format

The full set of fields for a STDIO server config: 
{
  "name": "<server-name>",
  "transport": "stdio",
  "description": "<description>",
  "command": "<command>",
  "args": ["<arg1>", "<arg2>"],
  "session_mode": "stateless",
  "env": {
    "KEY": "value"
  }
}
FieldRequiredDescription
nameYesUnique identifier. No spaces, special characters, or consecutive underscores.
transportYesMust be "stdio". Other possible values are "streamable_http" and "sse".
descriptionNoHuman-readable description surfaced in the CLI and API.
commandYesThe executable to run — typically "npx" or "uvx".
argsNoList of arguments passed to command when Mcpjungle spawns the process.
session_modeNostateless (default) creates a new process/connection per tool call. stateful reuses a persistent session.
envNoMap of environment variables injected into the process environment at startup.

​
Examples

{
  "name": "filesystem",
  "transport": "stdio",
  "description": "Filesystem MCP server",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
  "session_mode": "stateless"
}

​
Environment variable substitution

JSON config files support ${VAR_NAME} placeholders in string fields, including command args and env values. See the configuration file reference for the full substitution rules and examples.

​
Running in Docker: filesystem access

When Mcpjungle runs inside a Docker container, the container process does not have access to your host filesystem by default. To use the filesystem MCP server from inside Docker, you need to mount the host directory you want to expose. The default docker-compose.yaml provided by Mcpjungle mounts your current working directory as /host inside the container. Use /host as the target directory in your config: 
{
  "name": "filesystem",
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/host"]
}
This gives the filesystem server access to your current working directory on the host machine, mounted at /host inside the container.
If you need to expose a different directory, add a volume mount to your docker-compose.yaml and update the path in args accordingly.

​
Using the stdio Docker image

STDIO-based servers that rely on npx or uvx require those tools to be present in the Mcpjungle container.
The default mcpjungle Docker image is minimal and does not include npx or uvx. You must use the latest-stdio tagged image when registering STDIO servers that use these commands.
Start Mcpjungle with the stdio image using the MCPJUNGLE_IMAGE_TAG environment variable: 
MCPJUNGLE_IMAGE_TAG=latest-stdio docker compose up -d
If you are using the development docker-compose.yaml, the latest-stdio tag is already the default. You only need to set MCPJUNGLE_IMAGE_TAG explicitly when using docker-compose.prod.yaml.
If your STDIO server depends on a tool other than npx or uvx, create a custom Docker image that builds on the Mcpjungle base image and installs the additional dependency.

​
Debugging STDIO servers

If a STDIO server fails to start or throws errors during a tool call, check the Mcpjungle server logs. The server captures stderr output from child processes and writes it to its own log stream, making it the primary place to diagnose STDIO server issues.

Session modes

Use stateful mode when a STDIO server’s cold start cost becomes a bottleneck.

Docker deployment

Choose the right image and understand container filesystem access.

Register HTTP servers

Register remote MCP servers over streamable HTTP.

Config file reference

See the exact JSON schema for STDIO registration files.