---
title: "Add STDIO MCP servers"
description: "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

<Steps>
  <Step title="Write a config file">
    Create a JSON file describing your server. Here is an example for the official MCP filesystem server:

    ```json
    {
      "name": "filesystem",
      "transport": "stdio",
      "description": "Filesystem MCP server",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    }
    ```
  </Step>
  <Step title="Register with Mcpjungle">
    Pass the file to the `register` command with the `-c` flag:

    ```bash
    mcpjungle register -c ./filesystem.json
    ```

    Mcpjungle spawns the process, initializes the connection, loads its tool list, and registers the server.
  </Step>
</Steps>

## Config file format

The full set of fields for a STDIO server config:

```json
{
  "name": "<server-name>",
  "transport": "stdio",
  "description": "<description>",
  "command": "<command>",
  "args": ["<arg1>", "<arg2>"],
  "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

<CodeGroup>

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

```json uvx (custom server)
{
  "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}"
  }
}
```

</CodeGroup>

## 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
{
  "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.

<Tip>
If you need to expose a different directory, add a volume mount to your `docker-compose.yaml` and update the path in `args` accordingly.
</Tip>

## Using the stdio Docker image

STDIO-based servers that rely on `npx` or `uvx` require those tools to be present in the Mcpjungle container.

<Warning>
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.
</Warning>

Start Mcpjungle with the `stdio` image using the `MCPJUNGLE_IMAGE_TAG` environment variable:

```bash
MCPJUNGLE_IMAGE_TAG=latest-stdio docker compose up -d
```

<Note>
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`.
</Note>

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

<CardGroup cols={2}>
  <Card title="Session modes" icon="clock" href="/guides/session-modes">
    Use stateful mode when a STDIO server's cold start cost becomes a bottleneck.
  </Card>
  <Card title="Docker deployment" icon="docker" href="/deployment/docker">
    Choose the right image and understand container filesystem access.
  </Card>
  <Card title="Register HTTP servers" icon="server" href="/guides/register-http-servers">
    Register remote MCP servers over streamable HTTP.
  </Card>
  <Card title="Config file reference" icon="file-code" href="/reference/config-file">
    See the exact JSON schema for STDIO registration files.
  </Card>
</CardGroup>