Bearer Token Authentication for Streamable-HTTP Mode in MCP Ambari API

Bearer token authentication for streamable-http mode is enabled via the REMOTE_AUTH_ENABLE and REMOTE_SECRET_KEY environment variables (or --auth-enable and --secret-key CLI flags), which configure a StaticTokenVerifier that validates the Authorization: Bearer <token> header on every request.

The call518/mcp-ambari-api repository implements a FastMCP server that exposes Ambari management tools over HTTP using the streamable-http transport. When operating in this mode, the server supports optional Bearer token authentication to secure incoming requests, configured through either environment variables or command-line arguments parsed in src/mcp_ambari_api/mcp_main.py.

Configuration Methods

Authentication is controlled by two primary settings that determine whether the server requires a Bearer token and which secret key to accept.

Environment Variables

The server reads configuration from the environment at startup. In src/mcp_ambari_api/mcp_main.py (lines 3814–3816), the code checks for REMOTE_AUTH_ENABLE to determine if authentication should be activated:

• REMOTE_AUTH_ENABLE: Set to true (or any truthy value) to activate authentication
• REMOTE_SECRET_KEY: The secret string that becomes the only accepted Bearer token (lines 3817–3834)

When REMOTE_AUTH_ENABLE is truthy, the server passes REMOTE_SECRET_KEY to the authentication builder.

Command-Line Flags

You can override environment variables using CLI arguments parsed near line 3800:

• --auth-enable: Boolean flag to enable authentication
• --secret-key: String value specifying the required Bearer token

These flags take precedence over environment variables when explicitly provided.

How Authentication Works

When authentication is enabled, the code in src/mcp_ambari_api/mcp_main.py (line 3834) attaches a token verifier to the FastMCP instance:

if auth_enable:
    mcp.auth = _build_static_token_auth(secret_key)
else:
    mcp.auth = None

The _build_static_token_auth() function (lines 66–73) creates a StaticTokenVerifier using FastMCP's built-in authentication class:

def _build_static_token_auth(secret_key: str) -> StaticTokenVerifier:
    tokens = {
        secret_key: {
            "client_id": "ambari-api-client",
            "scopes": ["read", "write"],
        }
    }
    return StaticTokenVerifier(tokens=tokens)

This verifier checks every incoming request for an Authorization header formatted as:

Authorization: Bearer <REMOTE_SECRET_KEY>

If the header is missing or the token does not match the configured secret, the server returns 401 Unauthorized and rejects the request before any Ambari API call is performed. When running streamable-http without authentication, the server logs a warning: WARNING: streamable-http mode without authentication enabled!

Usage Examples

Enabling Authentication via Environment File

Create a .env file (based on the template in .env.example, lines 14–25):

FASTMCP_TYPE=streamable-http
FASTMCP_HOST=0.0.0.0
FASTMCP_PORT=8000

REMOTE_AUTH_ENABLE=true
REMOTE_SECRET_KEY=SuperSecretKey123

Start the server:

source .env
PYTHONPATH=./src uv run python -m mcp_ambari_api

Enabling Authentication via Command Line

PYTHONPATH=./src uv run python -m mcp_ambari_api \
    --type streamable-http \
    --host 0.0.0.0 \
    --port 8000 \
    --auth-enable true \
    --secret-key SuperSecretKey123

Making Authenticated Requests with cURL

Send the Bearer token in the Authorization header:

curl -H "Authorization: Bearer SuperSecretKey123" \
     http://localhost:8000/mcp \
     -d '{"tool":"get_cluster_info","args":{}}'

Omitting or providing an incorrect token results in 401 Unauthorized:

curl http://localhost:8000/mcp -d '{"tool":"get_cluster_info","args":{}}'

# → 401 Unauthorized

Python Client Example

Using httpx to include the authentication header:

import httpx
import json

url = "http://localhost:8000/mcp"
payload = {"tool": "get_cluster_info", "args": {}}
headers = {"Authorization": "Bearer SuperSecretKey123"}

resp = httpx.post(url, json=payload, headers=headers)
print(resp.json())

Summary

• Bearer token authentication for streamable-http is controlled by REMOTE_AUTH_ENABLE and REMOTE_SECRET_KEY environment variables or their CLI equivalents (--auth-enable and --secret-key).
• The implementation uses FastMCP's StaticTokenVerifier class configured in src/mcp_ambari_api/mcp_main.py (lines 66–73 and 3814–3836).
• When enabled, the server requires an Authorization: Bearer <token> header on every request.
• Requests without valid tokens receive a 401 Unauthorized response before reaching any Ambari API functions.

Frequently Asked Questions

How do I disable Bearer token authentication for local development?

Set REMOTE_AUTH_ENABLE to false or omit the --auth-enable flag when starting the server. According to the source code in mcp_main.py, when auth_enable evaluates to false, mcp.auth is set to None and the server accepts all requests without verifying tokens. Note that running without authentication generates a warning log message.

Can I configure multiple valid Bearer tokens for different clients?

No. The current implementation in _build_static_token_auth() (lines 66–73) creates a StaticTokenVerifier with exactly one token entry mapped to the client ID "ambari-api-client". To support multiple tokens, you would need to modify the function to populate the tokens dictionary with additional key-value pairs before the FastMCP server starts.

What HTTP status code is returned for invalid or missing tokens?

The server returns 401 Unauthorized when the Authorization header is missing, malformed, or contains a token that does not match the configured REMOTE_SECRET_KEY. This occurs at the FastMCP transport layer before the request reaches any business logic tools defined in functions.py.

Where is the Bearer token verification performed in the codebase?

The verification logic resides in src/mcp_ambari_api/mcp_main.py. Lines 3814–3836 handle the decision to enable authentication and assign the verifier to mcp.auth, while lines 66–73 define the _build_static_token_auth() helper that instantiates the StaticTokenVerifier with the configured secret key and scopes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}