> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcpjungle.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Add STDIO MCP servers
> Register stdio transport-based MCP servers in mcpjungle using CLI. Expose them via the mcp gateway.
Mcpjungle supports MCP servers that use the [STDIO transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#stdio).
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](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem) and [time](https://github.com/modelcontextprotocol/servers/tree/main/src/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
Create a JSON file describing your server. Here is an example for the official MCP filesystem server:
```json theme={null}
{
"name": "filesystem",
"transport": "stdio",
"description": "Filesystem MCP server",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
}
```
Pass the file to the `register` command with the `-c` flag:
```bash theme={null}
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:
```json theme={null}
{
"name": "",
"transport": "stdio",
"description": "",
"command": "",
"args": ["", ""],
"session_mode": "stateless",
"env": {
"KEY": "value"
}
}
```
| Field | Required | Description |
| -------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| `name` | Yes | Unique identifier. No spaces, special characters, or consecutive underscores. |
| `transport` | Yes | Must be `"stdio"`. Other possible values are `"streamable_http"` and `"sse"`. |
| `description` | No | Human-readable description surfaced in the CLI and API. |
| `command` | Yes | The executable to run — typically `"npx"` or `"uvx"`. |
| `args` | No | List of arguments passed to `command` when Mcpjungle spawns the process. |
| `session_mode` | No | `stateless` (default) creates a new process/connection per tool call. `stateful` reuses a persistent session. |
| `env` | No | Map of environment variables injected into the process environment at startup. |
## Examples
```json npx (filesystem) theme={null}
{
"name": "filesystem",
"transport": "stdio",
"description": "Filesystem MCP server",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
"session_mode": "stateless"
}
```
```json uvx (custom server) theme={null}
{
"name": "my-stdio-server",
"transport": "stdio",
"description": "Custom uvx-based server",
"command": "uvx",
"args": ["my-server", "--workspace", "${WORKSPACE_ID}"],
"session_mode": "stateful",
"env": {
"API_TOKEN": "${API_TOKEN}"
}
}
```
## Environment variable substitution
JSON config files support `${VAR_NAME}` placeholders in string fields, including command args and `env` values.
See the [configuration file reference](/reference/config-file#\$var_name-placeholder-substitution) 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:
```json theme={null}
{
"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:
```bash theme={null}
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.
## Related pages
Use stateful mode when a STDIO server's cold start cost becomes a bottleneck.
Choose the right image and understand container filesystem access.
Register remote MCP servers over streamable HTTP.
See the exact JSON schema for STDIO registration files.