:deciduous_tree: JungleHub-Registry :deciduous_tree:

On-premise gateway infrastructure for unified access to your proprietary AI tools via MCP

JungleHub-Registry serves as the authoritative, single point of reference for all Model Context Protocol service instances operating within your corporate boundary.

🧑‍💻 Development teams leverage this platform to provision, administer, and maintain configurations for their MCP services and the functionalities they expose.

🤖 AI Agent instances (MCP Clients) utilize this centralized proxy to enumerate and invoke the aggregated capabilities from a singular, harmonized entry point.

JungleHub-Registry is the definitive convergence point for all your organizational AI agents' tool interactions!

Target Audience

1. Engineers integrating AI tools (e.g., those utilizing Claude or Cursor) via MCP Client interfaces.
2. Engineers deploying resilient, production-grade AI systems requiring inherent security, data governance, and granular authorization for tool access.
3. Enterprises seeking comprehensive visibility and governance over all communication flows between MCP Clients and Services, securely hosted within their private infrastructure 🔒

📋 Index of Contents

• Expedited Setup Guide
• Deployment Procedures
• Operational Usage
• Service Layer
  • Containerized Service Launch
  • Direct Host Execution of the Service
• Client Interaction
  • Integrating HTTP-Based MCP Endpoints
  • Integrating Local Process (STDIO) Based Services
  • Decommissioning Registered Services
• Connecting Claude Instances
• Connecting Cursor Instances
• Global Feature State Management (Enable/Disable)
• Functionality Groupings (Tool Groups)
• Credential Verification Mechanisms
• Advanced Organizational Features
  • Authorization Controls
  • Telemetry and Tracing (OpenTelemetry)
• Current Known Constraints
• Community Involvement

Expedited Setup Guide

This guide demonstrates the rapid deployment of the JungleHub-Registry service locally: 1. Initiate the service using docker compose for a local deployment. 2. Enroll a prototype MCP service into the registry. 3. Configure your local Claude instance to communicate through JungleHub-Registry to utilize your enrolled tools.

Service Initialization

bash curl -O https://raw.githubusercontent.com/mcpjungle/MCPJungle/refs/heads/main/docker-compose.yaml docker compose up -d

Service Registration

Acquire the junglehub command-line utility on your workstation via Homebrew or by directly downloading the executable from the Software Releases Repository. bash brew install mcpjungle/mcpjungle/junglehub

The CLI facilitates all administrative tasks within JungleHub-Registry.

Next, let's attach an existing MCP endpoint (e.g., context7) to JungleHub-Registry using the CLI. bash junglehub register --alias context7 --description "External Math Provider" --endpoint https://mcp.context7.com/mcp

Client Connection

Integrate JungleHub-Registry by setting the following configuration within your Claude tool configuration file:

{ "mcpServers": { "junglehub-proxy": { "command": "npx", "args": [ "mcp-remote", "http://localhost:8080/mcp", "--allow-http" ] } } }

Once JungleHub-Registry is established as an MCP source within Claude, prompt it with the following instruction: text Access the context7 service to fetch the documentation reference for the utility '/lodash/lodash'

Claude will then attempt to invoke the context7__get-library-docs function via the JungleHub-Registry proxy, which retrieves the specified library documentation.

Congratulations! You have successfully provisioned a remote MCP endpoint via JungleHub-Registry and executed one of its functions through an AI agent.

You are now encouraged to explore the system's documentation and the CLI for more advanced configurations.

Deployment Procedures

JungleHub-Registry is distributed as a self-contained executable binary.

Installation options include downloading from the Releases Archive or utilizing Homebrew:

bash brew install mcpjungle/mcpjungle/junglehub

Verify correct installation status:

bash junglehub version

[!IMPORTANT] On macOS systems, Homebrew is the mandated installation route as the statically compiled binary lacks necessary Apple Notarization certification (Reference).

JungleHub-Registry furnishes a Docker artifact, ideal for running the centralized registry component.

bash docker pull mcpjungle/mcpjungle

Operational Usage

JungleHub-Registry operates using a Client-Server topology; the binary supports execution of both roles.

Service Layer

The JungleHub-Registry service component manages the catalog of registered MCP endpoints and furnishes a unified intermediary for AI Agents to discover and invoke capabilities exposed by these registered endpoints.

The gateway interface communicates via a streamable HTTP transport mechanism, exposed at the /mcp URI path.

Containerized Service Launch

Docker Compose is the preferred methodology for initializing the JungleHub-Registry service locally: shell

docker-compose.yaml is optimized for individual, local utility deployment.

JungleHub-Registry defaults to 'development' operational mode.

curl -O https://raw.githubusercontent.com/mcpjungle/MCPJungle/refs/heads/main/docker-compose.yaml

docker compose up -d

docker-compose.prod.yaml is configured for organizational deployment on remote infrastructure for multi-user access.

JungleHub-Registry defaults to 'enterprise' operational mode, activating advanced features.

curl -O https://raw.githubusercontent.com/mcpjungle/MCPJungle/refs/heads/main/docker-compose.prod.yaml

docker compose -f docker-compose.prod.yaml up -d

[!NOTE] The 'enterprise' operational mode supersedes the former 'production' designation. Configuration parameters remain unchanged.

This action launches the JungleHub-Registry service alongside a containerized, persistent PostgreSQL database instance.

Confirm service availability by querying the health check endpoint: bash curl http://localhost:8080/health

If you intend to catalog local process (stdio) based MCP services requiring executables like npx or uvx, you must utilize the stdio tagged Docker image for JungleHub-Registry: bash MCPJUNGLE_IMAGE_TAG=latest-stdio docker compose up -d

[!NOTE] If employing docker-compose.yaml, this image tag is the default. Only specify the stdio tag when using docker-compose.prod.yaml.

This specific image carries a larger footprint but offers superior convenience when relying on stdio-driven MCP providers.

For instance, if your usage is restricted to remote endpoints like context7 and deepwiki, the standard (minimal) image suffices.

However, for incorporating stdio providers such as filesystem, time, or github, the stdio-tagged variant is essential.

[!NOTE] If your stdio providers depend on execution tools other than npx or uvx, you must construct a bespoke Docker image incorporating those dependencies alongside the JungleHub-Registry binary.

Production Deployment Strategy

The default JungleHub-Registry Docker Image is highly streamlined, containing merely a minimal base environment and the junglehub executable.

This minimalism renders it the recommended choice for large-scale production rollouts.

For the data persistence layer, deploying a dedicated Postgres database cluster and supplying its connection string to JungleHub-Registry is advised (refer to the Database Configuration section).

You can review the structure of the standard Dockerfile and the stdio Dockerfile.

Direct Host Execution of the Service

The service engine can be initiated directly utilizing the compiled binary:

bash junglehub start

This command launches the primary registry broker and MCP conduit, exposed by default on TCP port 8080.

Database Configuration

The JungleHub-Registry service mandates a functional data store; by default, it provisions an embedded SQLite database within the execution directory.

This default is acceptable for initial local validation. Alternatively, you can configure an external PostgreSQL data source using a Data Source Name (DSN):

bash export DATABASE_URL=postgres://admin:root@localhost:5432/junglehub_db

Execution via container

docker run mcpjungle/mcpjungle:latest

Or direct execution

junglehub start

Client Interaction

Once the central service is operational, the junglehub CLI tool becomes the interface for system management.

JungleHub-Registry supports MCP services utilizing both stdio and the Streamable HTTP communication protocols.

Let's examine the registration process.

Integrating HTTP-Based MCP Endpoints

Suppose you operate a streamable HTTP MCP service locally, accessible at http://127.0.0.1:8000/mcp, offering foundational arithmetic functions such as add, subtract, etc.

You can register this service within JungleHub-Registry: bash junglehub register --alias calculator --description "Offers fundamental arithmetic operations" --endpoint http://127.0.0.1:8000/mcp

If the service was launched using Docker Compose, and your operating system is not Linux, substitute the loopback address with the Docker gateway address (host.docker.internal): bash junglehub register --alias calculator --description "Offers fundamental arithmetic operations" --endpoint http://host.docker.internal:8000/mcp

The registry will then monitor this service and ingest its exposed capabilities.

Registration can alternatively be executed via a manifest file: bash cat ./calculator.json { "alias": "calculator", "transport": "streamable_http", "description": "Provides some basic math tools", "endpoint": "http://127.0.0.1:8000/mcp" }

junglehub register -c ./calculator.json

All functions sourced from this service are now discoverable via JungleHub-Registry:

bash junglehub list functions

Inspect function invocation signature

junglehub usage calculator__multiply

Execute a function

junglehub invoke calculator__multiply --payload '{"a": 100, "b": 50}'

[!NOTE] A function within JungleHub-Registry must be referenced by its standardized identifier, which adheres to the template <mcp-service-alias>__<function-name>. The separator between the service alias and the function name is a double underscore __.

E.g., If you register an MCP service alias codebase exposing a function named find_dependencies, invocation within JungleHub-Registry uses the canonical name codebase__find_dependencies.

Your MCP client must employ this canonical nomenclature when invoking the function through JungleHub-Registry.

The manifest file schema for enrolling a Streamable HTTP-based MCP service is:

{ "alias": "", "transport": "streamable_http", "description": "", "endpoint": "", "bearer_token": "" }

Integrating Local Process (STDIO) Based Services

Here is a sample configuration manifest (e.g., filesystem.json) for an MCP service utilizing the STDIO transport protocol:

{ "alias": "filesystem", "transport": "stdio", "description": "Local filesystem access mcp service", "executor": "npx", "arguments": ["-y", "@modelcontextprotocol/server-filesystem", "."] }

You enroll this MCP service into JungleHub-Registry by supplying its configuration file: bash

Save the JSON configuration to a file (e.g., filesystem.json)

junglehub register -c ./filesystem.json

The manifest file schema for enrolling an STDIO-based MCP service is:

{ "alias": "", "transport": "stdio", "description": "", "executor": "", "arguments": ["arguments", "to", "pass", "to", "the", "command"], "environment_vars": { "KEY": "value" } }

You can watch a brief tutorial on How to enroll an STDIO-based MCP service.

[!TIP] If your STDIO service encounters initialization failures or runtime exceptions, examine the JungleHub-Registry service logs to review its standard error stream output.

Constraint 🚧

JungleHub-Registry establishes a fresh communication channel upon every function invocation. This necessitates spawning a new child process for an stdio-based service per call.

While this introduces minor latency overhead, it guarantees complete isolation and prevents resource accumulation or memory exhaustion issues. Consequently, JungleHub-Registry currently lacks support for persistent, stateful sessions with registered MCP services.

We solicit community input via issue creation, discussions, or direct Discord contact to refine this execution model in upcoming iterations.

Crucial Consideration ⚠️

When JungleHub-Registry executes within a Docker environment, specific preparatory steps are required to facilitate access to host-level filesystem-interacting MCP services.

By default, the containerized JungleHub-Registry lacks inherent visibility into your host machine's file structure.

Therefore, you must: - Map the desired host directory into the container as a volume mount. - Specify this newly mounted path as the directory argument within the filesystem MCP service's execution command.

The default docker-compose.yaml provided maps the current working directory into the container at the /host location.

Thus, the filesystem MCP service configuration should utilize this mapping:

{ "alias": "filesystem", "transport": "stdio", "executor": "npx", "arguments": ["-y", "@modelcontextprotocol/server-filesystem", "/host"] }

This configuration grants the MCP service read/write access to the host machine's current working directory, accessible within the container at /host.

Consult DEVELOPMENT.md for exhaustive details on Docker volume interaction.

Decommissioning Registered Services

You possess the capability to excise a registered MCP service from the JungleHub-Registry catalog.

bash junglehub deregister calculator junglehub deregister filesystem

Upon removal, the associated service and all its functions become inaccessible to JungleHub-Registry and any connected MCP clients.

Integration with other MCP Clients

Assuming JungleHub-Registry is operating on http://localhost:8080, use the corresponding connection configurations below:

Claude

{ "mcpServers": { "junglehub-proxy": { "command": "npx", "args": [ "mcp-remote", "http://localhost:8080/mcp", "--allow-http" ] } } }

Cursor

{ "mcpServers": { "junglehub-proxy": { "url": "http://localhost:8080/mcp" } } }

You can view a brief instructional video on Connecting Cursor to JungleHub-Registry.

Global Feature State Management (Enable/Disable)

You maintain control over the availability of individual functions or the entire suite of functions provided by any registered MCP Service. If a function is marked as disabled, it is intentionally blocked by the JungleHub-Registry Proxy; thus, no connected MCP client can enumerate or invoke it.

bash

disable the get-library-docs function provided by the context7 service

junglehub disable context7__get-library-docs

re-enable the function

junglehub enable context7__get-library-docs

disable all functions offered by the context7 service

junglehub disable context7

re-enable all functions belonging to context7

junglehub enable context7

A disabled function remains accessible via JungleHub-Registry's direct HTTP interface, allowing administrative oversight via the CLI or other HTTP clients.

[!NOTE] Upon successful enrollment of a new service into JungleHub-Registry, all its associated functions are enabled by default.

Functionality Groupings (Tool Groups)

As you assimilate more MCP services into JungleHub-Registry, the volume of available functions through the Gateway can escalate dramatically. If an MCP client is presented with hundreds of functions via the Gateway MCP, its operational efficiency may suffer degradation.

JungleHub-Registry facilitates the exposure of a precisely curated subset of the total functions to your MCP clients via Functionality Groups.

You define a new group and specify precisely which functions are permitted entry into that group.

Upon group creation, JungleHub-Registry issues a unique endpoint URL specific to that group.

Your MCP client can then be configured to utilize this group-scoped endpoint instead of the primary, all-inclusive gateway address.

Creating a Functionality Group

A new functionality group is instantiated by submitting a JSON manifest file to the create group command.

You must declare a unique name for the group and specify the included functions using one or more of the following criteria fields: - included_functions: An explicit list of function identifiers to include (e.g., ["filesystem__read_file", "time__get_current_time"]) - included_services: Designate ALL functions sourced from specific MCP service aliases (e.g., ["time", "deepwiki"]) - excluded_functions: Specify functions to omit (particularly useful when incorporating entire services)

Example 1: Selective Function Inclusion

Consider this function group configuration file (claude-functions-group.json):

{ "name": "claude-functions", "description": "This group isolates functions intended for use by Claude Desktop", "included_functions": [ "filesystem__read_file", "deepwiki__read_wiki_contents", "time__get_current_time" ] }

This configuration exposes only three carefully selected functions, excluding the vast majority of those registered in JungleHub-Registry.

Example 2: Including Entire Services with Exemptions

It is possible to include all functions from designated services while optionally excluding specific ones:

{ "name": "claude-functions", "description": "All functions from time and deepwiki services, excluding time__convert_time", "included_services": ["time", "deepwiki"], "excluded_functions": ["time__convert_time"] }

This incorporates every function from the time and deepwiki services, with the sole exception of time__convert_time.

Example 3: Composite Inclusion Logic

All three criteria can be combined for maximal configuration specificity:

{ "name": "comprehensive-functions", "description": "A blend of manually selected functions, bulk service inclusion, and specific exclusions", "included_functions": ["filesystem__read_file"], "included_services": ["time"], "excluded_functions": ["time__convert_time"] }

This set includes filesystem__read_file plus every function from the time service, except for time__convert_time.

You create this group within JungleHub-Registry: bash $ junglehub create group -c ./claude-functions-group.json

Functionality Group claude-functions successfully provisioned It is reachable via the following streamable http endpoint:

http://127.0.0.1:8080/v0/groups/claude-functions/mcp

Subsequently, configure Claude (or any other MCP client) to route its requests to this group-specific address to access the restricted function set.

The client will exclusively perceive and be capable of invoking only these three functions, remaining oblivious to the broader set cataloged in JungleHub-Registry.

[!TIP] Execute junglehub list functions to review the complete catalog of available identifiers and select those appropriate for your group definitions.

You can also watch a Video Tutorial on Utilizing Functionality Groups.

[!NOTE] Exclusion logic is applied as the final filtering step. If a function is explicitly listed in included_functions but also appears in excluded_functions, it will ultimately be omitted from the resultant group definition.

Managing Functionality Groups

Administrative actions supported include listing all defined groups, retrieving detailed information for a specific group, and permanently removing a group.

bash

list all defined functionality groups

junglehub list groups

retrieve metadata for a specific group

junglehub get group claude-functions

delete a group

junglehub delete group claude-functions

Working with Functions within Groups

Functions can be listed and invoked scoped specifically to a group using the --group parameter:

bash

list functions confined to a specific group

junglehub list functions --group claude-functions

invoke a function within the specific group context

junglehub invoke filesystem__read_file --group claude-functions --payload '{"path": "README.md"}'

These group-scoped commands aid in validating function accessibility and ensuring correct operational context when interacting with filtered sets.

[!NOTE] If a function designated for inclusion in a group is subsequently deactivated globally or the defining service is removed, that function ceases to be available via the group's MCP interface. However, should the function be reactivated or its service re-enrolled later, its availability within the group is instantaneously restored.

Constraints 🚧 1. Updating the definition of an existing functionality group is not currently supported; deletion followed by recreation with the revised configuration file is required. 2. In the enterprise operational mode, group creation is presently restricted to administrative accounts. We are developing mechanisms to permit standard users to provision their own specialized groups.

Credential Verification Mechanisms

JungleHub-Registry incorporates support for authentication when connecting to Streamable HTTP MCP services that rely on static bearer tokens for securing access.

This is particularly beneficial for integrating external, cloud-hosted MCP services such as those provided by HuggingFace or Stripe, which necessitate an API key for authorization.

The credential can be supplied during the service registration process: bash

Supplying the --bearer-token argument instructs JungleHub-Registry to inject the Authorization: Bearer <token> header into all outbound communications to this specific service endpoint.

junglehub register --alias huggingface --description "HuggingFace MCP Broker" --endpoint https://huggingface.co/mcp --bearer-token

Alternatively, integrate the token within the service registration manifest: bash { "alias": "huggingface", "transport": "streamable_http", "endpoint": "https://huggingface.co/mcp", "description": "hugging face mcp server", "bearer_token": "" }

Support for full OAuth authorization flows is scheduled for a subsequent release!

Advanced Organizational Features 🔒

When deploying JungleHub-Registry within an organizational setting, utilizing the enterprise operational mode is strongly recommended: bash

Activate advanced organizational features by starting in enterprise mode

junglehub start --enterprise

Alternatively, set the operational mode via environment variable (valid values: development and enterprise)

export SERVER_MODE=enterprise junglehub start

Or utilize the enterprise Docker Compose manifest detailed previously

docker compose -f docker-compose.prod.yaml up -d

By default, the service runs in development mode, which is optimized for local, individual use.

In Enterprise mode, the server enforces stricter security protocols and unlocks advanced capabilities including external credential handling, Access Control Lists (ACLs), and advanced observability tooling.

After initiating the service in enterprise mode, you must perform an initial server setup from a client machine: bash junglehub init-server

This command establishes a primary administrative identity on the server and securely caches its corresponding API access token in your local configuration file (~/.mcpjungle.conf).

This token then permits authenticated interactions with the server via the junglehub CLI.

Authorization Controls

In development mode, every connected MCP client is granted unrestricted access to every registered MCP service via the JungleHub-Registry Proxy.

enterprise mode introduces granular control, enabling you to dictate precisely which MCP clients can interface with specific MCP services.

Assume you have registered two services, calculator and codebase, in enterprise mode. By default, no MCP client possesses access rights to these services. You must explicitly define MCP Clients within JungleHub-Registry and grant them explicit permissions to the desired services.

bash

Provision a new MCP client intended for use by the Cursor IDE; grant it access to calculator and codebase services

junglehub create mcp-client cursor-local --allow "calculator, codebase"

MCP client 'cursor-local' instantiated successfully! Permitted Services: calculator,codebase

Access Token: 1YHf2LwE1LXtp5lW_vM-gmdYHlPHdqwnILitBhXE4Aw This token must be transmitted in the Authorization: Bearer {token} HTTP header for subsequent requests.

JungleHub-Registry generates a unique access token for the client. This token must be supplied by the client configuration when making requests to the JungleHub-Registry proxy, typically in the Authorization header.

For instance, configuring Cursor to connect securely to JungleHub-Registry might involve this addition:

{ "mcpServers": { "junglehub-proxy": { "url": "http://localhost:8080/mcp", "headers": { "Authorization": "Bearer 1YHf2LwE1LXtp5lW_vM-gmdYHlPHdqwnILitBhXE4Aw" } } } }

A client successfully authenticated against a specific service via this token gains full visibility and invocation rights for all functions belonging to that authorized service.

[!NOTE] If the --allow flag is omitted during client creation, the new MCP client will be denied access to all registered MCP services by default.

Telemetry and Tracing (OpenTelemetry)

JungleHub-Registry incorporates Prometheus-compatible OpenTelemetry Metrics support for comprehensive system diagnostics.

• In enterprise mode, OpenTelemetry telemetry collection is activated automatically.
• In development mode, telemetry is dormant by default. Activation requires setting the OTEL_ENABLED environment variable to true prior to service startup:

bash

Activate OpenTelemetry metrics collection

export OTEL_ENABLED=true

Optionally, append supplementary metadata to every metric point generated

export OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=enterprise

Initiate the service

junglehub start

Once the JungleHub-Registry service is running, telemetry data streams are available on the /metrics endpoint.

Current Known Constraints 🚧

We are continuously refining the platform, though certain limitations persist:

1. JungleHub-Registry does not sustain persistent network links to registered MCP Services

When invoking a function from a Streamable HTTP service, JungleHub-Registry establishes a transient connection to handle the request.

Similarly, invoking a function from a STDIO service mandates the initiation of a new communication channel and the launch of a new subprocess to execute that service.

Upon request servicing, this temporary subprocess is terminated.

Therefore, a new stdio process is initiated for every single function call.

This pattern introduces moderate execution overhead but guarantees system stability by precluding resource leakage. It also means that stateful interactions with your MCP providers are currently unsupported.

We intend to enhance this connection methodology in upcoming releases and welcome community suggestions on ideal state management approaches!

2. Lack of Integrated OAuth Flow Support for Service Authentication.

Support for standardized OAuth grant flows is actively under development.

We are gathering data on diverse organizational requirements for OAuth integration with external MCP services; please contribute your specific workflow via a Discussion thread or issue report to inform our implementation strategy.

Community Involvement 💻

Contributions from the wider community are highly valued!

• For contribution protocols and style mandates, consult CONTRIBUTION.md
• For development environment setup and architectural insights, see DEVELOPMENT.md

Join our Discord community to network with other developers and project maintainers.

== See also == Rating site Review site TestFreaks, product review aggregator company

== References ==

=== Bibliography === Needleman, Rafe (20 September 2006). "Wize: tallies user feedback". cnet.com. CBS Interactive. Archived from the original on 17 August 2010. Retrieved 18 July 2010. Needleman, Rafe (19 October 2006). "Still more reviews aggregators: Retrevo, DigitalAdvisor, and TheFind". cnet.com. CBS Interactive. Archived from the original on 16 August 2010. Retrieved 18 July 2010.