MCPJungle is an open source, self-hosted Gateway for all your Model Context Protocol Servers.

🧑‍💻 Developers use it to register & manage MCP servers and the tools they provide from a central place.

🤖 MCP Clients use it to discover and consume all these tools from a single "Gateway" MCP Server.

Who should use MCPJungle?

1. Developers using MCP Clients like Claude & Cursor that need to access MCP servers for tool-calling

2. Developers building production-grade AI Agents that need to access MCP servers with built-in security, privacy and Access Control.

3. Organisations wanting to view & manage all MCP client-server interactions from a central place. Hosted in their own datacenter 🔒

📋 Table of Contents

• Quick Start guide

• Installation

• Usage

  • Server

    • Running mcpjungle server inside Docker

    • Running mcpjungle server directly on the host machine

    • Shutting down the server

  • Client

    • Adding Streamable HTTP-based MCP servers

    • Adding STDIO-based MCP servers

    • Removing MCP servers

  • Cold-start problem & Stateful Connections

  • Connect to mcpjungle from Claude

  • Connect to mcpjungle from Cursor

  • Connect to mcpjungle from Copilot

  • Enabling/Disabling Tools globally

  • Prompts

  • Tool Groups

  • Authentication

  • Enterprise features

    • Access Control

    • OpenTelemetry

• Limitations

• Contributing

Quickstart guide

This quickstart guide will show you how to:

1. Start the MCPJungle server locally using docker compose

2. Register a simple MCP server in mcpjungle

3. Connect your Claude to mcpjungle to access your MCP tools

Start the server

Related MCP server: whistle-mcp

Register MCP servers

Download the mcpjungle CLI on your local machine either using brew or directly from the Releases Page.

The CLI lets you manage everything in mcpjungle.

Next, lets add an MCP server to mcpjungle using the CLI. For this example, we'll use context7.

Connect to mcpjungle

Use the following configuration for your Claude MCP servers config:

Once mcpjungle is added as an MCP to your Claude, try asking it the following:

Claude will then attempt to call the context7__get-library-docs tool via MCPJungle, which will return the documentation for the Lodash library.

Congratulations! 🎉

You have successfully registered a remote MCP server in MCPJungle and called one of its tools via Claude

You can now proceed to play around with the mcpjungle and explore the documentation & CLI for more details.

Installation

MCPJungle is shipped as a stand-alone binary.

You can either download it from the Releases Page or use Homebrew to install it:

Verify your installation by running

MCPJungle provides a Docker image which is useful for running the registry server (more about it later).

Usage

MCPJungle has a Client-Server architecture and the binary lets you run both the Server and the Client.

Server

The MCPJungle server is responsible for managing all the MCP servers registered in it and providing a unified MCP gateway for AI Agents to discover and call tools provided by these registered servers.

The gateway itself runs over streamable http transport and is accessible at the /mcp endpoint.

Running inside Docker

For running the MCPJungle server locally, docker compose is the recommended way:

This will start the MCPJungle server along with a persistent Postgres database container.

You can quickly verify that the server is running:

If you plan on registering stdio-based MCP servers that rely on npx or uvx, use mcpjungle's stdio tagged docker image instead.

This image is significantly larger. But it is very convenient and recommended for running locally when you rely on stdio-based MCP servers.

For example, if you only want to register remote mcp servers like context7 and deepwiki, you can use the standard (minimal) image.

But if you also want to use stdio-based servers like filesystem, time, github, etc., you should use the stdio-tagged image instead.

Production Deployment

The default MCPJungle Docker image is very lightweight - it only contains a minimal base image and the mcpjungle binary.

It is therefore suitable and recommended for production deployments.

For the database, we recommend you deploy a separate Postgres DB cluster and supply its endpoint to mcpjungle (see Database section below).

You can see the definitions of the standard Docker image and the stdio Docker image.

Running directly on host

You can also run the server directly on your host machine using the binary:

This starts the main registry server and MCP gateway, accessible on port 8080 by default.

Shutting down

It is important that the mcpjungle server shuts down gracefully to ensure proper cleanup.

The recommended way to stop the server process is to send a SIGTERM signal to it.

Database

The mcpjungle server relies on a database and by default, creates a SQLite DB file mcpjungle.db in the current working directory.

This is okay when you're just testing things out locally.

For more serious deployments, mcpjungle also supports Postgresql. You can supply the DSN to connect to it:

You can also supply postgres-specific env vars or files if you don't prefer using the DSN:

Client

Once the server is up, you can use the mcpjungle CLI to interact with it.

MCPJungle currently supports MCP servers using stdio and Streamable HTTP Transports.

Let's see how to register them in mcpjungle.

Registering streamable HTTP-based servers

Let's say you're already running a streamable http MCP server locally at http://127.0.0.1:8000/mcp which provides basic math tools like add, subtract, etc.

You can register this MCP server with MCPJungle:

If you used docker compose to run the server, and you're not on Linux, you will have to use host.docker.internal instead of your local loopback address.

The registry will now start tracking this MCP server and load its tools.

You can also provide a configuration file to register the MCP server:

All tools provided by this server are now accessible via MCPJungle:

The config file format for registering a Streamable HTTP-based MCP server is:

Registering STDIO-based servers

Here's an example configuration file (let's call it filesystem.json) for a MCP server that uses the STDIO transport:

You can register this MCP server in MCPJungle by providing the configuration file:

The config file format for registering a STDIO-based MCP server is:

You can also watch a quick video on How to register a STDIO-based MCP server.

Caveat ⚠️

When running mcpjungle inside Docker, you need some extra configuration to run the filesystem mcp server.

By default, mcpjungle inside container does not have access to your host filesystem.

So you must:

• mount the host directory you want to access as a volume in the container

• specify the mount path as the directory in the filesystem mcp server command args

The docker-compose.yaml provided by mcpjungle mounts the current working directory as /host in the container.

So you can use the following configuration for the filesystem mcp server:

Then, the mcp has access to /host, ie, the current working directory on your host machine.

See DEVELOPMENT.md for more details.

Deregistering MCP servers

You can remove a MCP server from mcpjungle.

Once removed, this mcp server and its tools are no longer available to you or your MCP clients.

Cold-start problem & Stateful Connections

By default, MCPJungle always creates a new connection with the upstream MCP server when a tool is called.

When the tool call is complete, the connection is closed.

This keeps the system clean and avoids memory leaks.

But sometimes this can cause a latency overhead. For eg- a new process is spawned every time you call a tool of a STDIO-based mcp server. If the server takes several seconds to start up, this slows down the tool call and the overall interaction.

To solve this, MCPJungle also supports stateful connections.

You can set the session_mode to stateful (default is stateless) in you MCP server configuration:

mcpjungle will create a new connection with this mcp server the first time you call one of its tools.

This connection is not closed when the tool call is complete. Subsequent tool calls to this server reuse the same connection, avoiding the cold-start overhead.

The connection is only closed when:

1. mcpjungle server is stopped

2. the mcp server is deregistered from mcpjungle

3. the connection times out after a period of inactivity. You can set the number of seconds using the SESSION_IDLE_TIMEOUT_SEC env var to configure this globally in mcpjungle server (default value is -1, which means no timeout).

When possible, it is recommended that you use stateless connections (default setting).

Integration with other MCP Clients

Assuming that MCPJungle is running on http://localhost:8080, use the following configurations to connect to it:

Claude

Cursor

You can watch a quick video on How to connect Cursor to MCPJungle.

Copilot

Follow Copilot's doc on configuraing a MCP server manually.

Your mcp.json config file should look like this after adding mcpjungle to it:

Enabling/Disabling Tools

You can disable and re-enable a specific tool or all the tools provided by an MCP Server.

If a tool is disabled, it is not available via the MCPJungle Proxy or any of the Tool Groups, so no MCP clients can view or call it.

You can disable and enable Prompts as well.

A disabled tool is still accessible via mcpjungle's HTTP API, so humans can still manage it from the CLI (or any other HTTP client).

Prompts

Mcpjungle supports Prompts.

When you register a new MCP server, if it provides prompts, they're registered in mcpjungle too.

Here are some examples of how you can interact with Prompts using the CLI:

Tool Groups

As you add more MCP servers to MCPJungle, the number of tools available through the Gateway can grow significantly.

If your MCP client is exposed to hundreds of tools through the gateway MCP, its performance may degrade.

MCPJungle allows you to expose only a subset of all available tools to your MCP clients using Tool Groups.

You can create a new group and only include specific tools that you wish to expose.

Once a group is created, mcpjungle returns a unique endpoint for it.

You can then configure your MCP client to use this group-specific endpoint instead of the main gateway endpoint.

Creating a Tool Group

You can create a new tool group by providing a JSON configuration file to the create group command.

You must specify a unique name for the group and define which tools to include using one or more of the following fields:

• included_tools: List specific tool names to include (e.g., ["filesystem__read_file", "time__get_current_time"])

• included_servers: Include ALL tools from specific MCP servers (e.g., ["time", "deepwiki"])

• excluded_tools: Exclude specific tools (useful when including entire servers)

Example 1: Cherry-picking specific tools

Here is an example of a tool group configuration file (claude-tools-group.json):

This group exposes only 3 handpicked tools instead of all available tools.

Example 2: Including entire servers with exclusions

You can also include all tools from specific servers and optionally exclude some:

This includes ALL tools from the time and deepwiki servers except time__convert_time.

Example 3: Mixing approaches

You can combine all three fields for maximum flexibility:

This includes filesystem__read_file plus all tools from the time server except time__convert_time.

You can create this group in mcpjungle:

You can then configure Claude (or any other MCP client) to use this group-specific endpoint to access the MCP server.

The client will then ONLY see and be able to use these 3 tools and will not be aware of any other tools registered in MCPJungle.

You can also watch a Video on using Tool Groups.

Limitation 🚧

Prompts are currently not supported in Tool Groups. We're working to fix this issue 🛠️

Managing tool groups

You can currently perform operations like listing all groups, viewing details of a specific group and deleting a group.

Working with tools in groups

You can list and invoke tools within specific groups using the --group flag:

These commands provide group-scoped operations, making it easier to work with tools within specific contexts and validate that tools are available in your groups.

Limitations 🚧

1. Currently, you cannot update an existing tool group. You must delete the group and create a new one with the modified configuration file.

2. In enterprise mode, currently only an admin can create a Tool Group. We're working on allowing standard Users to create their own groups as well.

Authentication

MCPJungle currently supports authentication if your Streamable HTTP MCP Server accepts static tokens for auth.

This is useful when using SaaS-provided MCP Servers like HuggingFace, Stripe, etc. which require your API token for authentication.

You can supply your token while registering the MCP server:

Or from your configuration file

If you need to supply a custom value for the Authorization header or add additional custom headers, you can use the headers field in the config file:

Support for Oauth flow is coming soon!

Enterprise Features 🔒

If you're running MCPJungle in your organisation, we recommend running the Server in the enterprise mode:

By default, mcpjungle server runs in development mode which is ideal for individuals running it locally.

In Enterprise mode, the server enforces stricter security policies and will provide additional features like Authentication, ACLs, observability and more.

After starting the server in enterprise mode, you must initialize it by running the following command on your client machine:

This will create an admin user in the server and store its API access token in your home directory (~/.mcpjungle.conf).

You can then use the mcpjungle cli to make authenticated requests to the server.

Access Control

In development mode, all MCP clients have full access to all the MCP servers registered in MCPJungle Proxy.

enterprise mode lets you control which MCP clients can access which MCP servers.

Suppose you have registered 2 MCP servers calculator and github in MCPJungle in enterprise mode.

By default, no MCP client can access these servers. You must create an MCP Client in mcpjungle and explicitly allow it to access the MCP servers.

Mcpjungle creates an access token for your client. Configure your client or agent to send this token in the Authorization header when making requests to the mcpjungle proxy.

For example, you can add the following configuration in Cursor to connect to MCPJungle:

A client that has access to a particular server this way can view and call all the tools provided by that server.

Creating mcp clients from the config file

You can also create an MCP client by providing a JSON configuration file:

When creating a client from a config file, you must provide a custom access token because mcpjungle cannot print the generated token to the console.

Supplying custom access tokens in config files

There are 3 ways to provide the access token from configuration file:

1. Directly in the access_token field: Only use this for testing purposes. Not recommended for production, especially if you're committing the config file to version control.

2. From a file using the access_token_ref.file field: The file should contain only the token string.

3. From an environment variable using the access_token_ref.env field: The env var should contain the token string.

Creating user accounts

In addition to MCP clients, you can also create User accounts in mcpjungle for human users.

A user has a very limited set of privileges compared to an admin in the enterprise mode. For example, they can view and use MCP servers, but they don't have write permissions in mcpjungle.

The config file format for creating a user is similar to that of an MCP client:

Again, when using the config file, you must provide a custom access token.

OpenTelemetry

MCPJungle supports Prometheus-compatible OpenTelemetry Metrics for observability.

• In enterprise mode, OpenTelemetry is enabled by default.

• In development mode, telemetry is disabled by default. You can enable it by setting the OTEL_ENABLED environment variable to true before starting the server:

Once the mcpjungle server is started, metrics are available at the /metrics endpoint.

Current limitations 🚧

We're not perfect yet, but we're working hard to get there!

1. MCPJungle does not support OAuth flow for authentication yet

This is a work in progress.

We're collecting more feedback on how people use OAuth with MCP servers, so feel free to start a Discussion or open an issue to share your use case.

Contributing 💻

We welcome contributions from the community!

• For contribution guidelines and standards, see CONTRIBUTION.md

• For development setup and technical details, see DEVELOPMENT.md

Join our Discord community to connect with other contributors and maintainers.