Skip to main content
This page is about upstream authentication: how Mcpjungle authenticates when it calls an upstream MCP server.

​
When you need this

Use upstream authentication when the MCP server you are registering requires some form of authentication (eg- static bearer token, custom headers, or OAuth). Typical examples:
  • SaaS-hosted MCP servers
  • Internal MCP servers behind an API gateway
  • Self-hosted MCP servers using static bearer-token auth
  • Hosted MCP servers that require OAuth approval during registration

​
Bearer token via CLI flag

If the upstream server accepts a standard bearer token, pass it at registration time: 
mcpjungle register \
  --name huggingface \
  --description "HuggingFace MCP Server" \
  --url https://huggingface.co/mcp \
  --bearer-token <your-hf-api-token>
Mcpjungle will send: 
Authorization: Bearer <your-hf-api-token>
on requests to that upstream server.

​
Bearer token in a config file

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

​
Custom headers

If the upstream server expects a non-standard authorization format or additional headers, use the headers field: 
{
  "name": "sourcegraph",
  "transport": "streamable_http",
  "url": "https://sourcegraph.mycompany.com/.api/mcp",
  "headers": {
    "Authorization": "token <your-sourcegraph-token>",
    "Custom-Header": "custom-value"
  }
}
If you set both bearer_token and headers.Authorization, the explicit header value should be treated as the more specific configuration.

​
Upstream OAuth during registration

Mcpjungle now supports OAuth flows for upstream HTTP MCP servers in beta. The simplest path is interactive CLI registration: 
mcpjungle register --name todoist --url https://ai.todoist.net/mcp
If the upstream MCP server requires OAuth:
  1. Mcpjungle first tries a normal unauthenticated registration.
  2. If the upstream server responds with 401 and advertises OAuth, the CLI opens your browser.
  3. You approve the OAuth request.
  4. Mcpjungle stores the resulting token and completes server registration.
This upstream OAuth support is currently beta.

​
OAuth fields in config files

You can also configure the upstream OAuth flow explicitly in the server JSON config: 
{
  "name": "todoist",
  "transport": "streamable_http",
  "url": "https://ai.todoist.net/mcp",
  "oauth_redirect_uri": "http://127.0.0.1:8085/oauth/callback",
  "oauth_client_id": "<optional pre-registered client id>",
  "oauth_client_secret": "<optional client secret>",
  "oauth_scopes": ["mcp.read"]
}
Field meanings:
  • oauth_redirect_uri: callback URI used during the upstream OAuth flow
  • oauth_client_id: optional pre-registered OAuth client ID
  • oauth_client_secret: optional client secret associated with oauth_client_id
  • oauth_scopes: optional scopes to request during authorization
If oauth_client_id is omitted, Mcpjungle attempts dynamic client registration when the upstream authorization server supports it.

​
Environment variable placeholders

JSON config files support ${VAR_NAME} placeholders in string fields, including bearer_token and header values: 
{
  "name": "affine-main",
  "transport": "streamable_http",
  "url": "https://app.affine.pro/api/workspaces/${AFFINE_WORKSPACE_ID}/mcp",
  "bearer_token": "${AFFINE_API_TOKEN}",
  "headers": {
    "X-Workspace": "${AFFINE_WORKSPACE_ID}"
  }
}
Placeholder expansion happens in the CLI process before the config is sent to Mcpjungle. See the configuration file reference for the full substitution rules.

​
STDIO servers and auth via environment variables

For STDIO-based MCP servers, authentication is typically passed through environment variables in the server config. Example: 
{
  "name": "my-stdio-server",
  "transport": "stdio",
  "command": "uvx",
  "args": ["my-server"],
  "env": {
    "API_TOKEN": "${API_TOKEN}"
  }
}
Mcpjungle will start the STDIO server process with those environment variables, allowing the upstream server to read its credentials from the process environment.

​
Important scope distinction

Two different authentication layers can exist in the same deployment:
  • Gateway authentication: Enterprise-mode clients authenticating to Mcpjungle.
  • Upstream authentication: Mcpjungle authenticating to a registered MCP server.
Those are separate concerns and use different configuration points.

​
Current limitations

Current upstream OAuth support has some limitations:
  • The feature is currently beta
  • It is only supported for streamable HTTP transport
  • The oauth token stored is scoped to the whole gateway, ie, per-user oauth login is currently not supported

Register servers

Register streamable HTTP MCP servers with CLI flags or config files.

Access control

Configure how MCP clients authenticate to the Mcpjungle gateway itself.

Clients and users

Manage human and machine identities in enterprise mode.

Limitations

Review the remaining OAuth constraints and other current gaps.