HTTP API overview - mcpjungle

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 doesn’t enforce any authentication. 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

The REST API surface is organized into a few practical areas:

Servers: register, deregister, enable, and disable upstream MCP servers
Tools, prompts, and resources: list, inspect, invoke, and fetch content exposed through registered servers
Tool groups: create and manage curated subsets of tools for narrower MCP surfaces
Clients and users: enterprise-only identity and access management

Use the CLI and governance guides for the current workflows while the API reference remains consolidated on this overview page.

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" }

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.

​Base URL

​Authentication

​Access levels

​Example request

​Endpoint groups

​System endpoints

​GET /health

​GET /metadata

​MCP proxy endpoints

​Metrics endpoint

​Error shape

Base URL

Authentication

Access levels

Example request

Endpoint groups

System endpoints

`GET /health`

`GET /metadata`

MCP proxy endpoints

Metrics endpoint

Error shape