MCPJungle HTTP API overview

Base URL, authentication, access levels, and a complete map of every endpoint group and MCP proxy surface exposed by the MCPJungle gateway server.

The MCPJungle server exposes two families of HTTP endpoints: a REST management API under /api/v0 for registering servers, invoking tools, and administering the system, and a set of MCP proxy endpoints that AI agents connect to directly. All responses are JSON unless otherwise noted.

Base URL

http://localhost:8080

The port is 8080 by default. Every REST management endpoint is prefixed with /api/v0. MCP proxy endpoints sit at the root and under /v0.

Authentication

In development mode the server accepts all requests without credentials. In enterprise mode every request must carry a bearer token:

Authorization: Bearer <your-access-token>

Tokens are created per-user or per-MCP-client when you call POST /api/v0/users or POST /api/v0/clients. The admin token is returned when the server is initialized with POST /init.

Requests that arrive without a valid token in enterprise mode receive 401 Unauthorized. Requests from a user-role token that target admin-only endpoints receive 403 Forbidden.

Access levels

Role	What it can do
Admin	Full read/write access to all endpoints. Required for registering servers, managing clients, users, and tool groups.
User	Read access and tool invocation. Can list servers, tools, prompts, and resources, and can call POST /api/v0/tools/invoke.

MCP clients (non-human agents) authenticate with their own tokens and are further restricted to the servers listed in their allow list.

Example request

curl http://localhost:8080/api/v0/servers \
  -H "Authorization: Bearer YOUR_TOKEN"

Endpoint groups

Servers

Register, deregister, enable, and disable upstream MCP servers. Admin-only write operations; users can list.

Tools

List, fetch, invoke, enable, and disable tools. Also covers prompt listing and rendering.

Tool groups

Create and manage named subsets of tools to expose targeted MCP surfaces to specific clients.

Clients and users

Enterprise-only endpoints for managing MCP clients and human users, including token issuance.

System endpoints

These endpoints sit outside the /api/v0 prefix and require no authentication.

GET /health

Returns 200 OK when the server is running.

{ "status": "ok" }

GET /metadata

Returns the running server version.

{ "version": "0.4.2" }

POST /init

One-time endpoint to initialize the server. Sets the operating mode (dev or enterprise) and creates the initial admin user in enterprise mode. Once initialized, this endpoint returns an error.

MCP proxy endpoints

These endpoints implement the Model Context Protocol and are the connection targets for AI agents and MCP clients.

Endpoint	Transport	Description
ANY /mcp	Streamable HTTP	Global MCP proxy. Exposes all enabled tools across all registered servers.
ANY /sse	SSE	Legacy SSE transport for the global proxy. Use /mcp for new integrations.
ANY /message	SSE	SSE message handler (companion to /sse).
GET /v0/groups/:name/mcp	Streamable HTTP	Tool-group-scoped MCP proxy. Only exposes tools in the named group.
ANY /v0/groups/:name/sse	SSE	SSE transport for a specific tool group.
ANY /v0/groups/:name/message	SSE	SSE message handler for a specific tool group.

Point your MCP client at /mcp for full access or at /v0/groups/:name/mcp to restrict it to a named tool group. The streamable HTTP transport is preferred over SSE for new integrations.

Metrics endpoint

GET /metrics

Exposed only when MCPJungle is started with OpenTelemetry enabled. Returns Prometheus-format metrics. This endpoint is not secured by the standard bearer-token middleware — secure it at the network level if needed.

Error shape

All error responses share a common JSON envelope:

{ "error": "human-readable error message" }

Status	Meaning
400	Invalid input — check the request body or query parameters.
401	Missing or invalid bearer token.
403	Token is valid but the role is insufficient.
404	The requested resource does not exist.
409	Conflict — e.g., a server with that name is already registered.
500	Internal server error.