> ## 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.
# CLI configuration file
> Reference for ~/.mcpjungle.conf
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:
```yaml theme={null}
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
Base URL of the Mcpjungle server the CLI connects to. Set this to avoid passing `--registry` on every command.
```yaml theme={null}
registry_url: http://my-server:9000
```
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).
```yaml theme={null}
access_token: 1YHf2LwE1LXtp5lW_vM-gmdYHlPHdqwnILitBhXE4Aw
```
### Value precedence
When the CLI resolves the registry URL it uses the following order, highest priority first:
1. `--registry` flag passed explicitly on the command line
2. `registry_url` set in `~/.mcpjungle.conf`
3. 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 ` 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](/reference/cli-enterprise).
***
## 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.
```json theme={null}
{
"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 `.
```json theme={null}
{
"name": "calculator",
"transport": "streamable_http",
"description": "Provides basic math tools",
"url": "http://127.0.0.1:8000/mcp",
"bearer_token": "",
"oauth_redirect_uri": "http://127.0.0.1:8085/oauth/callback",
"oauth_client_id": "",
"oauth_client_secret": "",
"oauth_scopes": ["mcp.read"],
"headers": {
"": ""
}
}
```
| 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 ` 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 `.
```json theme={null}
{
"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 `.
```json theme={null}
{
"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 `__` 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 ` (enterprise mode).
```json theme={null}
{
"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:
1. `access_token`
2. `access_token_ref.file`
3. `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 ` (enterprise mode).
```json theme={null}
{
"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.