MCPJungle

📋 Índice

• Instalação
• Uso
  • Servidor
    • Executando o servidor mcpjungle dentro do Docker
    • Executando o servidor mcpjungle diretamente na máquina host
    • Desligando o servidor
  • Cliente
    • Adicionando servidores MCP baseados em HTTP transmissível
    • Adicionando servidores MCP baseados em STDIO
    • Removendo servidores MCP
    • URL personalizada para o servidor
  • Problema de inicialização a frio e Conexões com estado
  • Conectar ao mcpjungle a partir do Claude
  • Conectar ao mcpjungle a partir do Cursor
  • Conectar ao mcpjungle a partir do Copilot
  • Habilitando/Desabilitando Ferramentas globalmente
  • Prompts
  • Grupos de Ferramentas
  • Autenticação
  • Recursos empresariais
    • Controle de Acesso
    • OpenTelemetry
• Limitações
• Contribuindo

Instalação

MCPJungle é distribuído como um binário independente.

Você pode baixá-lo da página de Releases ou usar o Homebrew para instalá-lo:

brew install mcpjungle/mcpjungle/mcpjungle

Verifique sua instalação executando

mcpjungle version

[!IMPORTANT] No MacOS, você terá que usar o homebrew porque o binário compilado ainda não é Notarizado.

MCPJungle fornece uma imagem Docker que é útil para executar o servidor de registro (mais sobre isso depois).

docker pull ghcr.io/mcpjungle/mcpjungle

Uso

MCPJungle tem uma arquitetura Cliente-Servidor e o binário permite executar tanto o Servidor quanto o Cliente.

Servidor

O servidor MCPJungle é responsável por gerenciar todos os servidores MCP registrados nele e fornecer um gateway MCP unificado para Agentes de IA descobrirem e chamarem ferramentas fornecidas por esses servidores registrados.

O gateway em si roda sobre transporte HTTP transmissível e é acessível no endpoint /mcp.

Executando dentro do Docker

Para executar o servidor MCPJungle localmente, o docker compose é a forma recomendada:

# docker-compose.yaml is optimized for individuals running mcpjungle on their local machines for personal use.
# mcpjungle will run in `development` mode by default.
curl -O https://raw.githubusercontent.com/mcpjungle/MCPJungle/refs/heads/main/docker-compose.yaml

docker compose up -d

# docker-compose.prod.yaml is optimized for orgs deploying mcpjungle on a remote server for multiple users.
# mcpjungle will run in `enterprise` mode by default, which enables enterprise 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] O modo enterprise costumava ser chamado de modo production. O modo foi renomeado para maior clareza. Todo o resto permanece o mesmo.

Isso iniciará o servidor MCPJungle junto com um contêiner de banco de dados Postgres persistente.

Você pode verificar rapidamente se o servidor está em execução:

curl http://localhost:8080/health

Se você planeja registrar servidores MCP baseados em stdio que dependem de npx ou uvx, use a imagem docker com tag stdio do mcpjungle.

MCPJUNGLE_IMAGE_TAG=latest-stdio docker compose up -d

[!NOTE] Se você estiver usando docker-compose.yaml, esta já é a tag de imagem padrão. Você só precisa especificar a tag de imagem stdio se estiver usando docker-compose.prod.yaml.

Esta imagem é significativamente maior. Mas é muito conveniente e recomendada para execução local quando você depende de servidores MCP baseados em stdio.

Por exemplo, se você só quer registrar servidores MCP remotos como context7 e deepwiki, pode usar a imagem padrão (mínima).

Mas se você também quiser usar servidores baseados em stdio como filesystem, time, github, etc., deve usar a imagem com tag stdio.

[!NOTE] Se seus servidores stdio dependem de ferramentas diferentes de npx ou uvx, você terá que criar uma imagem Docker personalizada que inclua essas dependências junto com o binário mcpjungle.

Implantação em Produção

A imagem Docker padrão do MCPJungle é muito leve - contém apenas uma imagem base mínima e o binário mcpjungle.

Portanto, é adequada e recomendada para implantações em produção.

Para o banco de dados, recomendamos implantar um cluster Postgres separado e fornecer seu endpoint ao mcpjungle (veja a seção Banco de Dados abaixo).

Você pode ver as definições da imagem Docker padrão e da imagem Docker stdio.

Executando diretamente no host

Você também pode executar o servidor diretamente na sua máquina host usando o binário:

mcpjungle start

Isso inicia o servidor de registro principal e o gateway MCP, acessível na porta 8080 por padrão.

Desligando

É importante que o servidor mcpjungle desligue corretamente para garantir a limpeza adequada.

A forma recomendada de parar o processo do servidor é enviar um sinal SIGTERM para ele.

Banco de Dados

O servidor mcpjungle depende de um banco de dados e, por padrão, cria um arquivo de banco de dados SQLite mcpjungle.db no diretório de trabalho atual.

Isso é aceitável quando você está apenas testando as coisas localmente.

Se você não fornecer configuração PostgreSQL ou um caminho SQLite personalizado, o mcpjungle usa ./mcpjungle.db.

Você pode opcionalmente definir um caminho de arquivo personalizado para o arquivo de banco de dados SQLite:

mcpjungle start --sqlite-db-path ./.mcpjungle.db

# or
export SQLITE_DB_PATH=/path/to/.mcpjungle.db
mcpjungle start

NOTA: Excluir esse arquivo SQLite remove todos os dados de servidores registrados e outros estados do MCPJungle armazenados nele.

Para implantações mais sérias, o mcpjungle também suporta Postgresql. Você pode fornecer o DSN para conectar-se a ele:

# You can supply the database DSN as an env var
export DATABASE_URL=postgres://admin:root@localhost:5432/mcpjungle_db

#run as container
docker run ghcr.io/mcpjungle/mcpjungle:latest

# or run directly
mcpjungle start

Você também pode fornecer variáveis de ambiente específicas do postgres ou arquivos se preferir não usar o DSN:

# host is mandatory if you're using postgres-specific env vars
export POSTGRES_HOST=localhost
export POSTGRES_PORT=5432

export POSTGRES_USER=admin
export POSTGRES_USER_FILE=/path/to/user-file

export POSTGRES_PASSWORD=secret
export POSTGRES_PASSWORD_FILE=/path/to/password-file

export POSTGRES_DB=mcpjungle_db
export POSTGRES_DB_FILE=/path/to/db-file

mcpjungle start

Cliente

Uma vez que o servidor esteja ativo, você pode usar o CLI do mcpjungle para interagir com ele.

MCPJungle atualmente suporta servidores MCP usando transportes stdio e HTTP transmissível.

[!NOTE] O suporte para SSE (eventos enviados pelo servidor) também existe, mas atualmente não é maduro.

Vamos ver como registrá-los no mcpjungle.

Registrando servidores baseados em HTTP transmissível

Digamos que você já esteja executando um servidor MCP HTTP transmissível localmente em http://127.0.0.1:8000/mcp que fornece ferramentas matemáticas básicas como add, subtract, etc.

Você pode registrar este servidor MCP com MCPJungle:

mcpjungle register --name calculator --description "Provides some basic math tools" --url http://127.0.0.1:8000/mcp

Se você usou docker compose para executar o servidor e não está no Linux, terá que usar host.docker.internal em vez do seu endereço de loopback local.

mcpjungle register --name calculator --description "Provides some basic math tools" --url http://host.docker.internal:8000/mcp

O registro agora começará a rastrear este servidor MCP e carregar suas ferramentas.

Você também pode fornecer um arquivo de configuração para registrar o servidor MCP:

cat ./calculator.json
{
  "name": "calculator",
  "transport": "streamable_http",
  "description": "Provides some basic math tools",
  "url": "http://127.0.0.1:8000/mcp"
}

mcpjungle register -c ./calculator.json

Todas as ferramentas fornecidas por este servidor agora estão acessíveis via MCPJungle:

mcpjungle list tools

# Check tool usage
mcpjungle usage calculator__multiply

# Call a tool
mcpjungle invoke calculator__multiply --input '{"a": 100, "b": 50}'

[!NOTE] Uma ferramenta no MCPJungle deve ser referida pelo seu nome canônico que segue o padrão <mcp-server-name>__<tool-name>. O nome do servidor e o nome da ferramenta são separados por um sublinhado duplo __.

ex- Se você registrar um servidor MCP github que fornece uma ferramenta chamada git_commit, você pode invocá-la no MCPJungle usando o nome github__git_commit.

Seu cliente MCP também deve usar este nome canônico para chamar a ferramenta via MCPJungle.

O formato do arquivo de configuração para registrar um servidor MCP baseado em HTTP transmissível é:

{
  "name": "<name of your mcp server>",
  "transport": "streamable_http",
  "description": "<description>",
  "url": "<url of the mcp server>",
  "bearer_token": "<optional bearer token for authentication>",
  "headers": {
    "<custom http header>": "<value>"
  }
}

Registrando servidores baseados em STDIO

Aqui está um exemplo de arquivo de configuração (vamos chamá-lo de filesystem.json) para um servidor MCP que usa o transporte STDIO:

{
  "name": "filesystem",
  "transport": "stdio",
  "description": "filesystem mcp server",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
}

Você pode registrar este servidor MCP no MCPJungle fornecendo o arquivo de configuração:

# Save the JSON configuration to a file (e.g., filesystem.json)
mcpjungle register -c ./filesystem.json

O formato do arquivo de configuração para registrar um servidor MCP baseado em STDIO é:

{
  "name": "<name of your mcp server>",
  "transport": "stdio",
  "description": "<description>",
  "command": "<command to run the mcp server, eg- 'npx', 'uvx'>",
  "args": ["arguments", "to", "pass", "to", "the", "command"],
  "env": {
    "KEY": "value"
  }
}

Você também pode assistir a um vídeo rápido sobre Como registrar um servidor MCP baseado em STDIO.

[!TIP] Se o seu servidor STDIO falhar ou lançar erros por algum motivo, verifique os logs do servidor mcpjungle para ver sua saída stderr.

Variáveis de ambiente em arquivos de configuração JSON

Quando você usa um arquivo de configuração JSON para registrar um servidor mcp ou criar outras entidades como grupos de ferramentas, o CLI pode resolver espaços reservados de variáveis de ambiente em valores de string antes de enviar a solicitação ao servidor.

• Apenas espaços reservados escritos como ${VAR_NAME} são resolvidos.
• Espaços reservados podem aparecer em qualquer lugar dentro de um valor de string, por exemplo prefix-${VAR_NAME}-suffix.
• A resolução acontece no processo do CLI, então a variável de ambiente deve estar disponível onde você executa o comando.
• Se uma variável de ambiente referenciada não estiver definida, o comando falha com um erro.
• Isso se aplica a campos de string em todo o JSON de configuração, incluindo objetos aninhados e arrays de strings.

Exemplo de configuração de servidor MCP:

{
  "name": "affine-main",
  "transport": "streamable_http",
  "description": "AFFiNE workspace MCP server",
  "url": "https://app.affine.pro/api/workspaces/${AFFINE_WORKSPACE_ID}/mcp",
  "bearer_token": "${AFFINE_API_TOKEN}",
  "headers": {
    "X-Workspace": "${AFFINE_WORKSPACE_ID}"
  }
}

Exemplo de configuração STDIO:

{
  "name": "my-stdio-server",
  "transport": "stdio",
  "command": "uvx",
  "args": ["my-server", "--workspace", "${WORKSPACE_ID}"],
  "env": {
    "API_TOKEN": "${API_TOKEN}"
  }
}

Ressalva ⚠️

Ao executar o mcpjungle dentro do Docker, você precisa de alguma configuração extra para executar o servidor mcp filesystem.

Por padrão, o mcpjungle dentro do container não tem acesso ao sistema de arquivos do seu host.

Então você deve:

• montar o diretório do host que deseja acessar como um volume no container
• especificar o caminho de montagem como o diretório nos argumentos do comando do servidor mcp de filesystem

O docker-compose.yaml fornecido pelo mcpjungle monta o diretório de trabalho atual como /host no container.

Então você pode usar a seguinte configuração para o servidor mcp de filesystem:

{
  "name": "filesystem",
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/host"]
}

Assim, o mcp tem acesso a /host, ou seja, o diretório de trabalho atual na sua máquina host.

Consulte DEVELOPMENT.md para mais detalhes.

Executando comandos CLI a partir de uma implantação Docker ou Kubernetes

Se o seu servidor MCPJungle estiver rodando em um container Docker remoto ou cluster Kubernetes, você também pode executar o binário mcpjungle diretamente dentro do container:

docker exec -it <container_name> /mcpjungle
kubectl -n <namespace> exec -it po/<pod_name> -- /mcpjungle

[!NOTE] A imagem padrão não inclui um shell. Execute /mcpjungle diretamente via docker exec ou kubectl exec.

Isso é útil para executar comandos CLI a partir do mesmo ambiente onde o servidor está rodando.

Cancelando o registro de servidores MCP

Você pode remover um servidor MCP do mcpjungle.

mcpjungle deregister calculator
mcpjungle deregister filesystem

Uma vez removido, este servidor mcp e suas ferramentas não estarão mais disponíveis para você ou seus clientes MCP.

Configurando uma URL de registro personalizada

Por padrão, a CLI se conecta ao servidor mcpjungle em http://127.0.0.1:8000.

Se o seu servidor estiver rodando em um host ou porta diferente (por exemplo, uma implantação remota), você pode configurar a URL de registro de duas maneiras:

Opção 1: Use a flag --registry

mcpjungle --registry http://my-server:9000 list tools

Opção 2: Defina no arquivo de configuração

Crie ou edite ~/.mcpjungle.conf:

registry_url: http://my-server:9000

Isso evita ter que passar a flag --registry em todos os comandos.

Problema de inicialização a frio e conexões com estado

Por padrão, o MCPJungle sempre cria uma nova conexão com o servidor MCP upstream quando uma ferramenta é chamada.

Quando a chamada da ferramenta é concluída, a conexão é fechada.

Isso mantém o sistema limpo e evita vazamentos de memória.

Mas às vezes isso pode causar uma sobrecarga de latência. Por exemplo, um novo processo é gerado toda vez que você chama uma ferramenta de um servidor mcp baseado em STDIO. Se o servidor levar vários segundos para iniciar, isso atrasa a chamada da ferramenta e a interação geral.

Para resolver isso, o MCPJungle também suporta conexões com estado.

Você pode definir o session_mode como stateful (o padrão é stateless) na configuração do seu servidor MCP:

{
  "name": "filesystem",
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
  "session_mode": "stateful"
}

O mcpjungle criará uma nova conexão com este servidor mcp na primeira vez que você chamar uma de suas ferramentas.

Esta conexão não é fechada quando a chamada da ferramenta é concluída. Chamadas subsequentes de ferramentas para este servidor reutilizam a mesma conexão, evitando a sobrecarga de inicialização a frio.

A conexão só é fechada quando:

1. o servidor mcpjungle é interrompido
2. o servidor mcp é removido do registro do mcpjungle
3. a conexão expira após um período de inatividade. Você pode definir o número de segundos usando a variável de ambiente SESSION_IDLE_TIMEOUT_SEC para configurar isso globalmente no servidor mcpjungle (o valor padrão é -1, o que significa sem timeout).

Quando possível, é recomendado que você use conexões sem estado (configuração padrão).

Integração com outros clientes MCP

Supondo que o MCPJungle esteja rodando em http://localhost:8080, use as seguintes configurações para conectar-se a ele:

Claude

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

Cursor

{
  "mcpServers": {
    "mcpjungle": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Você pode assistir a um vídeo rápido sobre Como conectar o Cursor ao MCPJungle.

Copilot

Siga a documentação do Copilot sobre configurando um servidor MCP manualmente.

Seu arquivo de configuração mcp.json deve ficar assim após adicionar o mcpjungle a ele:

{
  "servers": {
    "mcpjungle": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

[!NOTE] Você pode ter que clicar em Start para o Copilot realmente começar a interagir com o mcpjungle.

Habilitando/Desabilitando Ferramentas

Você pode desabilitar e reabilitar uma ferramenta específica ou todas as ferramentas fornecidas por um Servidor MCP.

Se uma ferramenta estiver desabilitada, ela não estará disponível via Proxy MCPJungle ou qualquer um dos Grupos de Ferramentas, então nenhum cliente MCP pode visualizá-la ou chamá-la.

Você também pode desabilitar e habilitar Prompts.

# disable the `get-library-docs` tool provided by the `context7` MCP server
mcpjungle disable tool context7__get-library-docs

# re-enable the tool
mcpjungle enable tool context7__get-library-docs

# disable all tools in context7
mcpjungle disable tool context7

# disable the whole `context7` MCP server (disables all tools & prompts)
mcpjungle disable server context7

# re-enable `context7`
mcpjungle enable server context7

# disable a prompt
mcpjungle disable prompt "huggingface_Model Details"

# disable all prompts in context7
mcpjungle disable prompt context7

Uma ferramenta desabilitada ainda é acessível via API HTTP do mcpjungle, então humanos ainda podem gerenciá-la a partir da CLI (ou qualquer outro cliente HTTP).

[!NOTE] Quando um novo servidor é registrado no MCPJungle, todas as suas ferramentas e prompts estão habilitados por padrão.

Prompts

O Mcpjungle suporta Prompts.

Quando você registra um novo servidor MCP, se ele fornecer prompts, eles também são registrados no mcpjungle.

Aqui estão alguns exemplos de como você pode interagir com Prompts usando a CLI:

# list all prompts provided by the huggingface mcp
$ mcpjungle list prompts --server huggingface

# Retrieve the "Model Details" prompt, supply custom arguments
$ mcpjungle get prompt "huggingface__Model Details" --arg model_id="openai/gpt-oss-120b"

Grupos de Ferramentas

À medida que você adiciona mais servidores MCP ao MCPJungle, o número de ferramentas disponíveis através do Gateway pode crescer significativamente.

Se o seu cliente MCP estiver exposto a centenas de ferramentas através do gateway MCP, seu desempenho pode degradar.

O MCPJungle permite que você exponha apenas um subconjunto de todas as ferramentas disponíveis aos seus clientes MCP usando Grupos de Ferramentas.

Você pode criar um novo grupo e incluir apenas ferramentas específicas que deseja expor.

Uma vez que um grupo é criado, o mcpjungle retorna um endpoint exclusivo para ele.

Você pode então configurar seu cliente MCP para usar este endpoint específico do grupo em vez do endpoint principal do gateway.

Criando um Grupo de Ferramentas

Você pode criar um novo grupo de ferramentas fornecendo um arquivo de configuração JSON para o comando create group.

Você deve especificar um name exclusivo para o grupo e definir quais ferramentas incluir usando um ou mais dos seguintes campos:

• included_tools: Liste nomes específicos de ferramentas para incluir (por exemplo, ["filesystem__read_file", "time__get_current_time"])
• included_servers: Inclua TODAS as ferramentas de servidores MCP específicos (por exemplo, ["time", "deepwiki"])
• excluded_tools: Exclua ferramentas específicas (útil ao incluir servidores inteiros)

Exemplo 1: Selecionando ferramentas específicas

Aqui está um exemplo de um arquivo de configuração de grupo de ferramentas (claude-tools-group.json):

{
  "name": "claude-tools",
  "description": "This group only contains tools for Claude Desktop to use",
  "included_tools": [
    "filesystem__read_file",
    "deepwiki__read_wiki_contents",
    "time__get_current_time"
  ]
}

Este grupo expõe apenas 3 ferramentas escolhidas a dedo em vez de todas as ferramentas disponíveis.

Exemplo 2: Incluindo servidores inteiros com exclusões

Você também pode incluir todas as ferramentas de servidores específicos e opcionalmente excluir algumas:

{
  "name": "claude-tools",
  "description": "All tools from time and deepwiki servers except time__convert_time",
  "included_servers": ["time", "deepwiki"],
  "excluded_tools": ["time__convert_time"]
}

Isso inclui TODAS as ferramentas dos servidores time e deepwiki, exceto time__convert_time.

Exemplo 3: Misturando abordagens

Você pode combinar todos os três campos para máxima flexibilidade:

{
  "name": "comprehensive-tools",
  "description": "Mix of manual tools, server inclusion, and exclusions",
  "included_tools": ["filesystem__read_file"],
  "included_servers": ["time"],
  "excluded_tools": ["time__convert_time"]
}

Isso inclui filesystem__read_file mais todas as ferramentas do servidor time, exceto time__convert_time.

Você pode criar este grupo no mcpjungle:

$ mcpjungle create group -c ./claude-tools-group.json

Tool Group claude-tools created successfully
It is now accessible at the following streamable http endpoint:

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

Você pode então configurar o Claude (ou qualquer outro cliente MCP) para usar este endpoint específico do grupo para acessar o servidor MCP.

O cliente então verá e poderá usar APENAS essas 3 ferramentas e não estará ciente de nenhuma outra ferramenta registrada no MCPJungle.

[!TIP] Você pode executar mcpjungle list tools para ver todas as ferramentas disponíveis e escolher as que deseja incluir no seu grupo.

Você também pode assistir a um Vídeo sobre como usar Grupos de Ferramentas.

[!NOTE] A exclusão é sempre aplicada no final. Então, se você adicionar uma ferramenta a included_tools e também listá-la em excluded_tools, ela será excluída do grupo final.

Limitação 🚧

Prompts atualmente não são suportados em Grupos de Ferramentas. Estamos trabalhando para corrigir este problema 🛠️

Gerenciando grupos de ferramentas

Você pode atualmente realizar operações como listar todos os grupos, visualizar detalhes de um grupo específico e excluir um grupo.

# list all tool groups
mcpjungle list groups

# view details of a specific group
mcpjungle get group claude-tools

# delete a group
mcpjungle delete group claude-tools

Trabalhando com ferramentas em grupos

Você pode listar e invocar ferramentas dentro de grupos específicos usando a flag --group:

# list tools in a specific group
mcpjungle list tools --group claude-tools

# invoke a tool from a specific group context
mcpjungle invoke filesystem__read_file --group claude-tools --input '{"path": "README.md"}'

Esses comandos fornecem operações com escopo de grupo, facilitando o trabalho com ferramentas em contextos específicos e validando que as ferramentas estão disponíveis em seus grupos.

[!NOTE] Se uma ferramenta estiver incluída em um grupo, mas for posteriormente desabilitada globalmente ou excluída, ela não estará disponível via endpoint MCP do grupo.

Mas se a ferramenta for reabilitada ou adicionada novamente mais tarde, ela se tornará automaticamente disponível no grupo novamente.

Limitações 🚧

1. Atualmente, você não pode atualizar um grupo de ferramentas existente. Você deve excluir o grupo e criar um novo com o arquivo de configuração modificado.
2. No modo enterprise, atualmente apenas um administrador pode criar um Grupo de Ferramentas. Estamos trabalhando para permitir que Usuários padrão criem seus próprios grupos também.

Autenticação

O MCPJungle atualmente suporta autenticação se o seu Servidor MCP HTTP Streamable aceitar tokens estáticos para autenticação.

Isso é útil ao usar Servidores MCP fornecidos como SaaS, como HuggingFace, Stripe, etc., que exigem seu token de API para autenticação.

Você pode fornecer seu token ao registrar o servidor MCP:

# If you specify the `--bearer-token` flag, MCPJungle will add the `Authorization: Bearer <token>` header to all requests made to this MCP server.
mcpjungle register --name huggingface --description "HuggingFace MCP Server" --url https://huggingface.co/mcp --bearer-token <your-hf-api-token>

Ou a partir do seu arquivo de configuração

{
  "name": "huggingface",
  "transport": "streamable_http",
  "url": "https://huggingface.co/mcp",
  "description": "hugging face mcp server",
  "bearer_token": "<your-hf-api-token>"
}

Se você precisar fornecer um valor personalizado para o cabeçalho Authorization ou adicionar cabeçalhos personalizados adicionais, você pode usar o campo headers no arquivo de configuração:

{
  "name": "sourcegraph",
  "transport": "streamable_http",
  "url": "https://sourcegraph.mycompany.com/.api/mcp",
  "headers": {
    "Authorization": "token <your-sourcegraph-token>",
    "Custom-Header": "custom-value"
  }
}

Suporte para fluxo Oauth está chegando em breve!

Recursos Empresariais 🔒

Se você está executando o MCPJungle na sua organização, recomendamos executar o Servidor no modo enterprise:

# enable enterprise features by running in enterprise mode
mcpjungle start --enterprise

# you can also specify the server mode as environment variable (valid values are `development` and `enterprise`)
export SERVER_MODE=enterprise
mcpjungle start

# Or use the enterprise-mode docker compose file as described above
docker compose -f docker-compose.prod.yaml up -d

Por padrão, o servidor mcpjungle roda no modo development, que é ideal para indivíduos executando-o localmente.

No modo Empresarial, o servidor aplica políticas de segurança mais rigorosas e fornecerá recursos adicionais como Autenticação, ACLs, observabilidade e mais.

Após iniciar o servidor no modo empresarial, você deve inicializá-lo executando o seguinte comando na sua máquina cliente:

mcpjungle init-server

Isso criará um usuário administrador no servidor e armazenará seu token de acesso à API no seu diretório inicial (~/.mcpjungle.conf).

Você pode então usar a CLI do mcpjungle para fazer solicitações autenticadas ao servidor.

Controle de Acesso

No modo development, todos os clientes MCP têm acesso total a todos os servidores MCP registrados no Proxy MCPJungle.

O modo enterprise permite que você controle quais clientes MCP podem acessar quais servidores MCP.

Suponha que você tenha registrado 2 servidores MCP calculator e github no MCPJungle no modo empresarial.

Por padrão, nenhum cliente MCP pode acessar esses servidores. Você deve criar um Cliente MCP no mcpjungle e permitir explicitamente que ele acesse os servidores MCP.

# Create a new MCP client for your Cursor IDE to use. It can access the calculator and github MCP servers
mcpjungle create mcp-client cursor-local --allow "calculator, github"

MCP client 'cursor-local' created successfully!
Servers accessible: calculator,github

Access token: 1YHf2LwE1LXtp5lW_vM-gmdYHlPHdqwnILitBhXE4Aw
Send this token in the `Authorization: Bearer {token}` HTTP header.

O Mcpjungle cria um token de acesso para o seu cliente. Configure seu cliente ou agente para enviar este token no cabeçalho Authorization ao fazer solicitações ao proxy mcpjungle.

[!TIP] Você também pode fornecer um token de acesso personalizado para seus clientes mcp e contas de usuário usando a flag --access-token. Isso é útil quando você deseja gerenciar tokens você mesmo, talvez através de um servidor de identidade central.

Por exemplo, você pode adicionar a seguinte configuração no Cursor para conectar-se ao MCPJungle:

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

Um cliente que tem acesso a um servidor específico desta forma pode visualizar e chamar todas as ferramentas fornecidas por esse servidor.

[!NOTE] Se você não especificar a flag --allow, o cliente MCP não poderá acessar nenhum servidor MCP.

Criando clientes mcp a partir do arquivo de configuração

Você também pode criar um Cliente MCP fornecendo um arquivo de configuração JSON:

{
	"name": "foobar",
	"allowed_servers": ["deepwiki", "time"],
	"access_token": "my_secret_token_123",
    "access_token_ref": {
        "file": "/path/to/token-file.txt",
        "env": "ENV_VAR_NAME"
    }
}

Ao criar um cliente a partir de um arquivo de configuração, você deve fornecer um token de acesso personalizado porque o mcpjungle não pode imprimir o token gerado no console.

Fornecendo tokens de acesso personalizados em arquivos de configuração

Existem 3 maneiras de fornecer o token de acesso a partir do arquivo de configuração:

1. Diretamente no campo access_token: Use apenas para fins de teste. Não recomendado para produção, especialmente se você estiver commitando o arquivo de configuração no controle de versão.
2. De um arquivo usando o campo access_token_ref.file: O arquivo deve conter apenas a string do token.
3. De uma variável de ambiente usando o campo access_token_ref.env: A variável de ambiente deve conter a string do token.

Você também pode usar espaços reservados ${VAR_NAME} em outros lugares no mesmo arquivo de configuração JSON. Por exemplo:

{
  "name": "${MCP_CLIENT_NAME}",
  "allowed_servers": ["${PRIMARY_SERVER}", "time"],
  "access_token_ref": {
    "env": "CLIENT_TOKEN_ENV_NAME"
  }
}

Criando contas de usuário

Além de clientes MCP, você também pode criar contas de Usuário no mcpjungle para usuários humanos.

Um usuário tem um conjunto de privilégios muito limitado em comparação com um administrador no modo empresarial. Por exemplo, eles podem visualizar e usar servidores MCP, mas não têm permissões de escrita no mcpjungle.

# Auto-generates a secret for user
mcpjungle create user bob
# Specify a custom access token for user
mcpjungle create user alice --access-token alice_token_123
# Create user from config file
mcpjungle create user --conf /path/to/user-config.json

O formato do arquivo de configuração para criar um usuário é semelhante ao de um cliente MCP:

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

Novamente, ao usar o arquivo de configuração, você deve fornecer um token de acesso personalizado.

Assim como outros arquivos de configuração JSON no MCPJungle, os arquivos de configuração de usuário também suportam placeholders ${VAR_NAME} em campos de string.

OpenTelemetry

O MCPJungle suporta métricas OpenTelemetry compatíveis com Prometheus para observabilidade.

• No modo enterprise, o OpenTelemetry é habilitado por padrão.
• No modo development, a telemetria é desabilitada por padrão. Você pode habilitá-la definindo a variável de ambiente OTEL_ENABLED como true antes de iniciar o servidor:

# enable OpenTelemetry metrics
export OTEL_ENABLED=true

# optionally, set additional attributes to be added to all metrics
export OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=enterprise

# start the server
mcpjungle start

Uma vez que o servidor mcpjungle é iniciado, as métricas estão disponíveis no endpoint /metrics.

Limitações atuais 🚧

Ainda não somos perfeitos, mas estamos trabalhando duro para chegar lá!

1. O MCPJungle ainda não suporta fluxo OAuth para autenticação

Isso é um trabalho em andamento.

Estamos coletando mais feedback sobre como as pessoas usam OAuth com servidores MCP, então sinta-se à vontade para iniciar uma Discussão ou abrir uma issue para compartilhar seu caso de uso.

Contribuindo 💻

Aceitamos contribuições da comunidade!

• Para diretrizes e padrões de contribuição, veja CONTRIBUTION.md
• Para configuração de desenvolvimento e detalhes técnicos, veja DEVELOPMENT.md

Junte-se à nossa comunidade no Discord para se conectar com outros contribuidores e mantenedores.