Skip to main content

​
Mcpjungle server

The long-running HTTP service that you run either locally or deploy to a remote host machine. It exposes a REST API for managing mcpjungle registry itself and a streamable HTTP endpoint at /mcp for AI clients to connect to.

​
Data persistence

Mcpjungle stores all its data in a SQL database. By default, it uses SQLite with a local file. For production deployments, we recommend PostgreSQL. If you use the docker-compose.yaml provided in the repository, it will automatically start a PostgreSQL container and ensure connectivity.

​
Mcpjungle client

The mcpjungle CLI tool you run from your terminal to manage everything in the server. As of today, the CLI is the primary client, with a web-based GUI in the works. You can also build your own clients that talk to the server’s REST API for custom management interfaces or automation.

​
Upstream MCP server

An upstream MCP server is any MCP server you add in Mcpjungle. This mcp server then becomes accessible to AI clients that connect to Mcpjungle’s gateway endpoint.

​
Canonical names

​
Tools and Prompts

Mcpjungle assigns canonical names to tools and prompts so they remain unique across all registered servers. Tool format: 
<server-name>__<tool-name>
Prompt format: 
<server-name>__<prompt-name>
Examples: 
context7__get-library-docs
filesystem__read_file
huggingface__Model Details
So if 2 mcp servers - foo and bar - expose a tool called get_file, mcpjungle will expose them as foo__get_file and bar__get_file respectively. AI clients can discover and use these names.

​
Resources

Each resource in mcpjungle is assigned a new, unique URI which follows the below format: 
mcpj://res/<server-name>/<base64encode(original-resource-uri)>
eg- 
mcpj://res/foo_mcp/ZmlsZTovL3NhbXBsZS50eHQ
AI clients can discover and use these URIs to access mcp Resources.

​
Groups

By default, mcpjungle exposes all registered mcp servers (their tools, prompts and resources) at the main gateway endpoint /mcp. As you add more mcp servers, this can cause serious context overload for clients. Groups let you expose cherry-picked tools, prompts, and resources from registered servers at a separate MCP endpoint. Your client can then connect to the group’s endpoint to discover and use only those tools relevant to it. A group’s mcp is exposed at an endpoint of the format: Streamable http: 
/v0/groups/{group-name}/mcp
SSE: 
/v0/groups/{group-name}/sse
/v0/groups/{group-name}/message

​
Development mode vs Enterprise mode

Mcpjungle supports 2 operating modes.

​
Development mode

When you start mcpjungle server, it runs in development mode by default. This mode is ideal for individuals running mcpjungle locally for themselves. Use development mode when:
  • you want the shortest path to a working setup
  • you just need one clean MCP endpoint and minimal configuration hassle (sufficient for individual users)
  • you do not need governance or access control
In development mode, clients connecting to /mcp can access all registered servers.

​
Enterprise mode

This mode is ideal for teams running shared MCP infrastructure in an enterprise environment. Use enterprise mode when:
  • users need shared access to MCPs
  • you need authenticated client access to MCPs
  • you need Access Control
  • you need centralized management and governance features such as observability, audit logs, etc

​
Initialization

When mcpjungle server is started for the first time, it needs to be initialized. If running in development mode, initialization is automatic, and you can already start using mcpjungle. If running in enterprise mode, the server must be initialized by an administrator. Once a server is initialized, you cannot change its operating mode.

​
MCP Clients and Users

This concept is only relevant in enterprise mode. Enterprise mode distinguishes between two identity types:
  • MCP clients: Non-human identities AI clients like Cursor, Claude, Codex, custom agents, etc. They authenticate to the gateway and receive access to specific servers.
  • Users: Human operators who use the CLI or HTTP API. Standard users can inspect and use Mcpjungle, but write access remains restricted to admins.

​
Stateless versus stateful sessions

For each upstream server, Mcpjungle can manage connection lifecycle in one of two ways:
  • Stateless: Open a fresh connection for each tool call, then close it.
  • Stateful: Keep the connection open and reuse it across calls.
Stateless is the default and should remain your first choice. Stateful is mainly useful for STDIO servers with slow startup costs or servers that rely on persistent session state. Think of Mcpjungle as three layers:
  1. Upstream servers: The actual capabilities.
  2. Mcpjungle: The control plane and unified gateway.
  3. AI clients: Claude, Cursor, Copilot, or agents consuming MCPs.

​
Next steps

Register servers

Add remote HTTP-based MCP servers to the gateway.

Register STDIO servers

Add local process-based MCP servers such as filesystem or github.

Tool groups

Expose narrower tool subsets to specific clients.

Enterprise overview

Understand enterprise mode, client tokens, and shared deployment controls.