CLI configuration file

The Mcpjungle CLI reads a YAML configuration file at ~/.mcpjungle.conf on startup. It stores two values: the URL of the Mcpjungle server and an access token for authenticated requests. Most users never edit this file by hand — mcpjungle init-server and mcpjungle login write to it automatically.

Client config file (`~/.mcpjungle.conf`)

Location and format

The file lives in your home directory and uses YAML syntax:

registry_url: http://my-server:9000
access_token: 1YHf2LwE1LXtp5lW_vM-gmdYHlPHdqwnILitBhXE4Aw

Both fields are optional. If either is absent the CLI falls back to its default value or prompts you to supply it via a CLI flag.

Supported fields

registry_url

string

default:"http://127.0.0.1:8080"

Base URL of the Mcpjungle server the CLI connects to. Set this to avoid passing --registry on every command.

registry_url: http://my-server:9000

access_token

string

Bearer token sent in the Authorization: Bearer header with every API request. Required when the server runs in enterprise mode. Populated automatically by mcpjungle init-server (admin token) or mcpjungle login (user token).

access_token: 1YHf2LwE1LXtp5lW_vM-gmdYHlPHdqwnILitBhXE4Aw

Value precedence

When the CLI resolves the registry URL it uses the following order, highest priority first:

--registry flag passed explicitly on the command line
registry_url set in ~/.mcpjungle.conf
Built-in default (http://127.0.0.1:8080)

If you pass --registry manually but registry_url is not yet in your config file, the CLI prints a tip suggesting you add it to avoid repeating the flag.

Populating the file automatically

~/.mcpjungle.conf is usually created or updated in one of two ways:

mcpjungle init-server writes the initial admin credentials during enterprise bootstrap
mcpjungle login <user-token> stores a user token for later authenticated CLI use

You can also edit the file manually if needed. For the enterprise bootstrap flow and login workflow, see Enterprise operations.

JSON config file formats

Several mcpjungle commands accept a -c / --conf flag pointing to a JSON file instead of inline CLI flags. This section documents every supported JSON format.

`${VAR_NAME}` placeholder substitution

All JSON config files support environment variable placeholders in string fields. Before sending the request to the server, the CLI expands every ${VAR_NAME} occurrence using the current shell environment. Rules:

Only ${VAR_NAME} syntax is recognized — not $VAR_NAME.
Placeholders can appear anywhere inside a string, including as a substring: "prefix-${VAR}-suffix".
Substitution runs in the CLI process, so the variable must be set in the environment where you run the command.
Placeholders resolve in all string fields, including nested objects and string arrays.
If a referenced variable is not set, the command fails with a descriptive error.

{
  "name": "${MCP_SERVER_NAME}",
  "transport": "streamable_http",
  "url": "https://api.example.com/workspaces/${WORKSPACE_ID}/mcp",
  "bearer_token": "${API_TOKEN}"
}

Register a Streamable HTTP server

Used with mcpjungle register -c <file>.

{
  "name": "calculator",
  "transport": "streamable_http",
  "description": "Provides basic math tools",
  "url": "http://127.0.0.1:8000/mcp",
  "bearer_token": "<optional bearer token>",
  "oauth_redirect_uri": "http://127.0.0.1:8085/oauth/callback",
  "oauth_client_id": "<optional pre-registered client id>",
  "oauth_client_secret": "<optional client secret>",
  "oauth_scopes": ["mcp.read"],
  "headers": {
    "<custom-header>": "<value>"
  }
}

Field	Type	Required	Description
`name`	string	Yes	Unique name for this server in Mcpjungle.
`transport`	string	Yes	Must be `"streamable_http"`.
`description`	string	No	Human-readable description.
`url`	string	Yes	Full URL of the MCP server endpoint.
`bearer_token`	string	No	If set, Mcpjungle adds `Authorization: Bearer <token>` to every upstream request.
`oauth_redirect_uri`	string	No	Redirect URI used if the upstream MCP server requires OAuth during registration.
`oauth_client_id`	string	No	Optional pre-registered OAuth client ID.
`oauth_client_secret`	string	No	Optional OAuth client secret paired with `oauth_client_id`.
`oauth_scopes`	string array	No	Optional list of scopes to request during upstream OAuth authorization.
`headers`	object	No	Additional HTTP headers to forward. A `"Authorization"` entry here overrides `bearer_token`.

Upstream OAuth support is currently beta.For interactive CLI use, you usually do not need to set oauth_redirect_uri manually. Mcpjungle can provision a localhost callback automatically when the upstream MCP server actually requires OAuth.

Register a STDIO server

Used with mcpjungle register -c <file>.

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

Field	Type	Required	Description
`name`	string	Yes	Unique name for this server in Mcpjungle.
`transport`	string	Yes	Must be `"stdio"`.
`description`	string	No	Human-readable description.
`command`	string	Yes	Executable to run the MCP server process (e.g., `"npx"`, `"uvx"`).
`args`	string array	No	Arguments passed to `command`.
`env`	object	No	Environment variables injected into the server process.
`session_mode`	string	No	Connection lifecycle: `"stateless"` (default) creates a new process per call; `"stateful"` keeps the process alive between calls.

Create a tool group

Used with mcpjungle create group -c <file>.

{
  "name": "claude-tools",
  "description": "Tools exposed to Claude Desktop",
  "included_tools": [
    "filesystem__read_file",
    "time__get_current_time"
  ],
  "included_servers": ["deepwiki"],
  "excluded_tools": ["deepwiki__search"]
}

Field	Type	Required	Description
`name`	string	Yes	Unique name for the tool group.
`description`	string	No	Human-readable description.
`included_tools`	string array	No	Explicit list of tools to include, in `<server>__<tool>` format.
`included_servers`	string array	No	Server names whose entire tool set is included.
`excluded_tools`	string array	No	Tools to remove from the final set. Exclusions are always applied last, regardless of how a tool was included.

At least one of included_tools or included_servers should be set, otherwise the group will be empty.

Create an MCP client

Used with mcpjungle create mcp-client --conf <file> (enterprise mode).

{
  "name": "cursor-local",
  "allowed_servers": ["calculator", "github"],
  "access_token": "my_secret_token_123",
  "access_token_ref": {
    "file": "/run/secrets/mcpjungle_token",
    "env": "MCPJUNGLE_CLIENT_TOKEN"
  }
}

Field	Type	Required	Description
`name`	string	Yes	Unique name for this MCP client.
`allowed_servers`	string array	No	Server names the client may access. Use `"*"` to allow all servers. Omit to deny all.
`access_token`	string	No	Inline token value. For testing only.
`access_token_ref.file`	string	No	Path to a plain-text file containing only the token string.
`access_token_ref.env`	string	No	Name of an environment variable containing the token string.

When creating a client from a config file, you must supply a token via access_token or access_token_ref. Mcpjungle cannot print a generated token back to the console when reading from a file.

Token supply strategies

For MCP client and user config files, there are three ways to supply a custom token:

access_token
access_token_ref.file
access_token_ref.env

Use access_token only for testing or throwaway setups. For anything more serious, prefer file- or environment-based secrets.

Create a user account

Used with mcpjungle create user --conf <file> (enterprise mode).

{
  "name": "charlie",
  "access_token": "charlies_secret_token",
  "access_token_ref": {
    "file": "/path/to/token-file.txt",
    "env": "CHARLIE_TOKEN"
  }
}

Field	Type	Required	Description
`name`	string	Yes	Unique username.
`access_token`	string	No	Inline token value. For testing only.
`access_token_ref.file`	string	No	Path to a plain-text file containing only the token string.
`access_token_ref.env`	string	No	Name of an environment variable containing the token string.

The same ${VAR_NAME} placeholder substitution applies to user config files. When using a config file you must supply a token — Mcpjungle cannot print a generated one to the console.

Documentation Index

​Client config file (~/.mcpjungle.conf)

​Location and format

​Supported fields

​Value precedence

​Populating the file automatically

​JSON config file formats

​${VAR_NAME} placeholder substitution

​Register a Streamable HTTP server

​Register a STDIO server

​Create a tool group

​Create an MCP client

​Token supply strategies

​Create a user account

Client config file (`~/.mcpjungle.conf`)

Location and format

Supported fields

Value precedence

Populating the file automatically

JSON config file formats

`${VAR_NAME}` placeholder substitution

Register a Streamable HTTP server

Register a STDIO server

Create a tool group

Create an MCP client

Token supply strategies

Create a user account