Register STDIO-based MCP servers

Register local MCP servers that communicate over standard input/output — including filesystem, GitHub, and other npx or uvx-based servers.

MCPJungle supports MCP servers that use the STDIO transport. These servers run as child processes on the same machine as the MCPJungle server and communicate through standard input and output. Common examples include the filesystem, time, and github MCP servers distributed as npx or uvx packages.

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>"],
  "env": {
    "KEY": "value"
  }
}

Field	Required	Description
name	Yes	Unique identifier. No spaces, special characters, or consecutive underscores.
transport	Yes	Must be "stdio".
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.
env	No	Map of environment variables injected into the process environment at startup.

Examples

npx (filesystem)

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

Environment variable substitution

Config files support ${VAR_NAME} placeholders in any string field. The CLI resolves them from your shell environment before sending the request to MCPJungle:

{
  "name": "my-stdio-server",
  "transport": "stdio",
  "command": "uvx",
  "args": ["my-server", "--workspace", "${WORKSPACE_ID}"],
  "env": {
    "API_TOKEN": "${API_TOKEN}"
  }
}

Rules for substitution:

• Only the ${VAR_NAME} syntax is resolved — not $VAR_NAME.
• Placeholders can appear anywhere inside a string, including as a substring.
• Resolution runs in the CLI process, so the variable must be available in the shell where you run mcpjungle register.
• If a referenced variable is not set, the command fails with an error.
• Nested objects and string arrays are also resolved.

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.