feat: support allowlisted intermediary header (#203)

Author: akolotov

.env.example

@@ -41,3 +41,7 @@ BLOCKSCOUT_MCP_USER_AGENT="Blockscout MCP"
 BLOCKSCOUT_MIXPANEL_TOKEN=""
 BLOCKSCOUT_MIXPANEL_API_HOST=""
 
+# Annotate MCP client name with an allowlisted intermediary when running in HTTP mode.
+BLOCKSCOUT_INTERMEDIARY_HEADER="Blockscout-MCP-Intermediary"
+BLOCKSCOUT_INTERMEDIARY_ALLOWLIST="ClaudeDesktop,HigressPlugin"
+

Dockerfile

@@ -34,5 +34,7 @@ ENV BLOCKSCOUT_RPC_POOL_PER_HOST="50"
 ENV BLOCKSCOUT_MCP_USER_AGENT="Blockscout MCP"
 # ENV BLOCKSCOUT_MIXPANEL_TOKEN="" # Intentionally commented out: pass at runtime to avoid embedding secrets in image
 ENV BLOCKSCOUT_MIXPANEL_API_HOST=""
+ENV BLOCKSCOUT_INTERMEDIARY_HEADER="Blockscout-MCP-Intermediary"
+ENV BLOCKSCOUT_INTERMEDIARY_ALLOWLIST="ClaudeDesktop,HigressPlugin"
 
 CMD ["python", "-m", "blockscout_mcp_server"]

SPEC.md

@@ -497,6 +497,8 @@ If the client name cannot be determined from the MCP session parameters, the ser
 
 This provides a clear audit trail, helping to diagnose issues that may be specific to certain client versions or protocol implementations. For stateless calls, such as those from the REST API where no client is present, this information is gracefully omitted.
 
+In HTTP streamable mode, an allowlisted intermediary identifier can annotate the client name. The header name is configured via `BLOCKSCOUT_INTERMEDIARY_HEADER` (default: `Blockscout-MCP-Intermediary`) and allowed values via `BLOCKSCOUT_INTERMEDIARY_ALLOWLIST` (default: `ClaudeDesktop,HigressPlugin`). After trimming, collapsing whitespace, and validating length (≤16), the intermediary is appended to the base client name as `base/variant`. Invalid or disallowed values are ignored.
+
 #### 3. Mixpanel Analytics for Tool Invocation
 
 To gain insight into tool usage patterns, the server can optionally report tool invocations to Mixpanel.
@@ -510,7 +512,7 @@ To gain insight into tool usage patterns, the server can optionally report tool
 
 - Tracked properties (per event):
   - Client IP address derived from the HTTP request, preferring proxy headers when present: `X-Forwarded-For` (first value), then `X-Real-IP`, otherwise connection `client.host`.
-  - MCP client name (or the HTTP `User-Agent` when the client name is unavailable).
+  - MCP client name (or the HTTP `User-Agent` when the client name is unavailable). When a valid intermediary header is present, the client name is recorded as `base/variant`.
   - MCP client version.
   - MCP protocol version.
   - Tool arguments (currently sent as-is, without truncation).

blockscout_mcp_server/client_meta.py

@@ -5,6 +5,8 @@
 from dataclasses import dataclass
 from typing import Any
 
+from blockscout_mcp_server.config import config
+
 UNDEFINED_CLIENT_NAME = "N/A"
 UNDEFINED_CLIENT_VERSION = "N/A"
 UNKNOWN_PROTOCOL_VERSION = "Unknown"
@@ -40,10 +42,39 @@ def get_header_case_insensitive(headers: Any, key: str, default: str = "") -> st
     return default
 
 
+def _parse_intermediary_header(value: str, allowlist_raw: str) -> str:
+    """Normalize and validate an intermediary header value.
+
+    Extracts the first non-empty entry from a comma-separated list, normalizes whitespace,
+    guards against invalid characters or length, and ensures the value is allowlisted.
+    Returns the normalized value if valid, otherwise an empty string.
+    """
+    if not value:
+        return ""
+    first_value = next(
+        (stripped for v in value.split(",") if (stripped := v.strip())),
+        "",
+    )
+    if not first_value:
+        return ""
+    normalized = " ".join(first_value.split())
+    if len(normalized) > 16:
+        return ""
+    if "/" in normalized:
+        return ""
+    if any(ord(c) < 32 or ord(c) == 127 for c in normalized):
+        return ""
+    allowlist = [stripped.lower() for v in allowlist_raw.split(",") if (stripped := v.strip())]
+    if normalized.lower() not in allowlist:
+        return ""
+    return normalized
+
+
 def extract_client_meta_from_ctx(ctx: Any) -> ClientMeta:
     """Extract client meta (name, version, protocol, user_agent) from an MCP Context.
 
     - name: MCP client name. If unavailable, defaults to "N/A" constant or falls back to user agent.
+            If an intermediary HTTP header is present, it is appended to the client name.
     - version: MCP client version. If unavailable, defaults to "N/A" constant.
     - protocol: MCP protocol version. If unavailable, defaults to "Unknown" constant.
     - user_agent: Extracted from HTTP request headers if available.
@@ -52,6 +83,7 @@ def extract_client_meta_from_ctx(ctx: Any) -> ClientMeta:
     client_version = UNDEFINED_CLIENT_VERSION
     protocol: str = UNKNOWN_PROTOCOL_VERSION
     user_agent: str = ""
+    intermediary: str = ""
 
     try:
         client_params = getattr(getattr(ctx, "session", None), "client_params", None)
@@ -70,9 +102,16 @@ def extract_client_meta_from_ctx(ctx: Any) -> ClientMeta:
         if request is not None:
             headers = request.headers or {}
             user_agent = get_header_case_insensitive(headers, "user-agent", "")
+            header_name = config.intermediary_header
+            allowlist_raw = config.intermediary_allowlist
+            if header_name and allowlist_raw:
+                intermediary_raw = get_header_case_insensitive(headers, header_name, "")
+                intermediary = _parse_intermediary_header(intermediary_raw, allowlist_raw)
         # If client name is still undefined, fallback to User-Agent
         if client_name == UNDEFINED_CLIENT_NAME and user_agent:
             client_name = user_agent
+        if intermediary:
+            client_name = f"{client_name}/{intermediary}"
     except Exception:  # pragma: no cover - tolerate any ctx shape
         pass
 

blockscout_mcp_server/config.py

@@ -39,5 +39,9 @@ class ServerConfig(BaseSettings):
     mixpanel_token: str = ""
     mixpanel_api_host: str = ""  # Optional custom API host (e.g., EU region)
 
+    # Composite client name configuration
+    intermediary_header: str = "Blockscout-MCP-Intermediary"
+    intermediary_allowlist: str = "ClaudeDesktop,HigressPlugin"
+
 
 config = ServerConfig()

dxt/manifest-dev.json

@@ -2,7 +2,7 @@
   "dxt_version": "0.1",
   "name": "blockscout-mcp-dev",
   "display_name": "Blockscout (dev)",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Contextual blockchain activity analysis via Blockscout APIs",
   "long_description": "This extension enables contextual blockchain activity analysis with multi-chain support, intelligent context optimization, smart response slicing, and seamless pagination. The server exposes blockchain data including balances, tokens, NFTs, contract metadata, transactions, and logs via MCP for comprehensive blockchain analysis. This extension acts as a proxy to the official Blockscout MCP server.",
   "author": {
@@ -26,7 +26,8 @@
         "${__dirname}/node_modules/mcp-remote/dist/proxy.js",
         "${user_config.blockscout_url}",
         "--transport", "http-only",
-        "--allow-http"
+        "--allow-http",
+        "--header", "Blockscout-MCP-Intermediary: ClaudeDesktop"
       ],
       "env": {}
     }

dxt/manifest.json

@@ -2,7 +2,7 @@
   "dxt_version": "0.1",
   "name": "blockscout-mcp",
   "display_name": "Blockscout",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Contextual blockchain activity analysis via Blockscout APIs",
   "long_description": "This extension enables contextual blockchain activity analysis with multi-chain support, intelligent context optimization, smart response slicing, and seamless pagination. The server exposes blockchain data including balances, tokens, NFTs, contract metadata, transactions, and logs via MCP for comprehensive blockchain analysis. This extension acts as a proxy to the official Blockscout MCP server.",
   "author": {
@@ -25,7 +25,8 @@
       "args": [
         "${__dirname}/node_modules/mcp-remote/dist/proxy.js",
         "https://mcp.blockscout.com/mcp/",
-        "--transport", "http-only"
+        "--transport", "http-only",
+        "--header", "Blockscout-MCP-Intermediary: ClaudeDesktop"
       ],
       "env": {}
     }

tests/test_analytics.py

@@ -72,3 +72,71 @@ def test_tracks_with_headers(monkeypatch):
         assert args[2]["tool_args"] == {"x": 2}
         assert args[2]["protocol_version"] == "2024-11-05"
         assert kwargs.get("meta") == {"ip": "203.0.113.5"}
+
+
+def test_tracks_with_intermediary_header(monkeypatch):
+    monkeypatch.setattr(server_config, "mixpanel_token", "test-token", raising=False)
+    headers = {
+        "x-forwarded-for": "203.0.113.5",
+        "user-agent": "pytest-UA",
+        "Blockscout-MCP-Intermediary": "ClaudeDesktop",
+    }
+    req = DummyRequest(headers=headers)
+    ctx = DummyCtx(request=req, client_name="node", client_version="1.0.0")
+    with patch("blockscout_mcp_server.analytics.Mixpanel") as mp_cls:
+        mp_instance = MagicMock()
+        mp_cls.return_value = mp_instance
+        analytics.set_http_mode(True)
+        analytics.track_tool_invocation(ctx, "tool_name", {"x": 2})
+        args, _ = mp_instance.track.call_args
+        assert args[2]["client_name"] == "node/ClaudeDesktop"
+
+
+def test_tracks_with_invalid_intermediary(monkeypatch):
+    monkeypatch.setattr(server_config, "mixpanel_token", "test-token", raising=False)
+    headers = {
+        "x-forwarded-for": "203.0.113.5",
+        "user-agent": "pytest-UA",
+        "Blockscout-MCP-Intermediary": "Unknown",
+    }
+    req = DummyRequest(headers=headers)
+    ctx = DummyCtx(request=req, client_name="node", client_version="1.0.0")
+    with patch("blockscout_mcp_server.analytics.Mixpanel") as mp_cls:
+        mp_instance = MagicMock()
+        mp_cls.return_value = mp_instance
+        analytics.set_http_mode(True)
+        analytics.track_tool_invocation(ctx, "tool_name", {"x": 2})
+        args, _ = mp_instance.track.call_args
+        assert args[2]["client_name"] == "node"
+
+
+def test_tracks_with_intermediary_and_user_agent_fallback(monkeypatch):
+    monkeypatch.setattr(server_config, "mixpanel_token", "test-token", raising=False)
+    headers = {
+        "x-forwarded-for": "203.0.113.5",
+        "user-agent": "pytest-UA",
+        "Blockscout-MCP-Intermediary": "HigressPlugin",
+    }
+    req = DummyRequest(headers=headers)
+    ctx = DummyCtx(request=req, client_name="", client_version="")
+    with patch("blockscout_mcp_server.analytics.Mixpanel") as mp_cls:
+        mp_instance = MagicMock()
+        mp_cls.return_value = mp_instance
+        analytics.set_http_mode(True)
+        analytics.track_tool_invocation(ctx, "tool_name", {"x": 2})
+        args, _ = mp_instance.track.call_args
+        assert args[2]["client_name"] == "pytest-UA/HigressPlugin"
+
+
+def test_tracks_with_intermediary_no_client_or_user_agent(monkeypatch):
+    monkeypatch.setattr(server_config, "mixpanel_token", "test-token", raising=False)
+    headers = {"Blockscout-MCP-Intermediary": "ClaudeDesktop"}
+    req = DummyRequest(headers=headers)
+    ctx = DummyCtx(request=req, client_name="", client_version="")
+    with patch("blockscout_mcp_server.analytics.Mixpanel") as mp_cls:
+        mp_instance = MagicMock()
+        mp_cls.return_value = mp_instance
+        analytics.set_http_mode(True)
+        analytics.track_tool_invocation(ctx, "tool_name", {"x": 2})
+        args, _ = mp_instance.track.call_args
+        assert args[2]["client_name"] == "N/A/ClaudeDesktop"

tests/test_client_meta.py

@@ -4,9 +4,11 @@
     UNDEFINED_CLIENT_NAME,
     UNDEFINED_CLIENT_VERSION,
     UNKNOWN_PROTOCOL_VERSION,
+    _parse_intermediary_header,
     extract_client_meta_from_ctx,
     get_header_case_insensitive,
 )
+from blockscout_mcp_server.config import config
 
 
 def test_extract_client_meta_full():
@@ -57,3 +59,88 @@ def test_get_header_case_insensitive_with_dict():
     assert get_header_case_insensitive(headers, "USER-AGENT") == "ua-test/1.0"
     assert get_header_case_insensitive(headers, "x-real-ip") == "1.2.3.4"
     assert get_header_case_insensitive(headers, "missing", "default") == "default"
+
+
+def _ctx_with_intermediary(value: str) -> SimpleNamespace:
+    headers = {"Blockscout-MCP-Intermediary": value}
+    request = SimpleNamespace(headers=headers)
+    client_info = SimpleNamespace(name="node", version="1.0.0")
+    client_params = SimpleNamespace(clientInfo=client_info, protocolVersion="2024-11-05")
+    return SimpleNamespace(
+        session=SimpleNamespace(client_params=client_params),
+        request_context=SimpleNamespace(request=request),
+    )
+
+
+def test_intermediary_header_merged(monkeypatch):
+    monkeypatch.setattr(
+        config,
+        "intermediary_allowlist",
+        "ClaudeDesktop,HigressPlugin",
+        raising=False,
+    )
+    ctx = _ctx_with_intermediary(" claudeDESKTOP ")
+    meta = extract_client_meta_from_ctx(ctx)
+    assert meta.name == "node/claudeDESKTOP"
+
+
+def test_intermediary_header_uses_user_agent_when_client_missing(monkeypatch):
+    monkeypatch.setattr(
+        config,
+        "intermediary_allowlist",
+        "ClaudeDesktop,HigressPlugin",
+        raising=False,
+    )
+    headers = {
+        "User-Agent": "ua-test/9.9.9",
+        "Blockscout-MCP-Intermediary": "HigressPlugin",
+    }
+    request = SimpleNamespace(headers=headers)
+    ctx = SimpleNamespace(request_context=SimpleNamespace(request=request))
+
+    meta = extract_client_meta_from_ctx(ctx)
+    assert meta.name == "ua-test/9.9.9/HigressPlugin"
+
+
+def test_intermediary_header_appends_when_no_client_and_no_user_agent(monkeypatch):
+    monkeypatch.setattr(
+        config,
+        "intermediary_allowlist",
+        "ClaudeDesktop,HigressPlugin",
+        raising=False,
+    )
+    ctx = _ctx_with_intermediary("HigressPlugin")
+    ctx.session.client_params.clientInfo.name = ""  # type: ignore[attr-defined]
+    ctx.session.client_params.clientInfo.version = ""  # type: ignore[attr-defined]
+    ctx.session.client_params.protocolVersion = None  # type: ignore[attr-defined]
+    ctx.request_context.request.headers.pop("Blockscout-MCP-Intermediary", None)
+    ctx.request_context.request.headers["Blockscout-MCP-Intermediary"] = "HigressPlugin"
+    ctx.request_context.request.headers.pop("User-Agent", None)
+
+    meta = extract_client_meta_from_ctx(ctx)
+    assert meta.name == "N/A/HigressPlugin"
+
+
+def test_parse_intermediary_header_allowlisted():
+    allowlist = "ClaudeDesktop,HigressPlugin"
+    assert _parse_intermediary_header(" claudeDESKTOP ", allowlist) == "claudeDESKTOP"
+
+
+def test_parse_intermediary_header_not_allowlisted():
+    allowlist = "ClaudeDesktop,HigressPlugin"
+    assert _parse_intermediary_header("Unknown", allowlist) == ""
+
+
+def test_parse_intermediary_header_invalid_char():
+    allowlist = "BadValue"
+    assert _parse_intermediary_header("Bad/Value", allowlist) == ""
+
+
+def test_parse_intermediary_header_too_long():
+    allowlist = "X" * 17
+    assert _parse_intermediary_header("X" * 17, allowlist) == ""
+
+
+def test_parse_intermediary_header_multiple_values():
+    allowlist = "ClaudeDesktop,HigressPlugin"
+    assert _parse_intermediary_header(" ,HigressPlugin,Other", allowlist) == "HigressPlugin"

tests/tools/test_decorators.py

@@ -1,4 +1,5 @@
 import logging
+from types import SimpleNamespace
 from unittest.mock import MagicMock
 
 import mcp.types as types
@@ -77,3 +78,26 @@ async def dummy_tool(a: int, ctx: Context) -> int:
     assert "Tool invoked: dummy_tool" in log_text
     assert "with args: {'a': 1}" in log_text
     assert "(Client: test-client, Version: 1.2.3, Protocol: 2024-11-05)" in log_text
+
+
+@pytest.mark.asyncio
+async def test_log_tool_invocation_with_intermediary(caplog: pytest.LogCaptureFixture, mock_ctx: Context) -> None:
+    caplog.set_level(logging.INFO, logger="blockscout_mcp_server.tools.decorators")
+
+    @log_tool_invocation
+    async def dummy_tool(a: int, ctx: Context) -> int:
+        return a
+
+    headers = {"Blockscout-MCP-Intermediary": "HigressPlugin"}
+    mock_ctx.request_context = SimpleNamespace(request=SimpleNamespace(headers=headers))
+    mock_ctx.session = MagicMock()
+    mock_ctx.session.client_params = types.InitializeRequestParams(
+        protocolVersion="2024-11-05",
+        capabilities=types.ClientCapabilities(),
+        clientInfo=types.Implementation(name="test-client", version="1.2.3"),
+    )
+
+    await dummy_tool(1, ctx=mock_ctx)
+
+    log_text = caplog.text
+    assert "(Client: test-client/HigressPlugin, Version: 1.2.3, Protocol: 2024-11-05)" in log_text