:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import json
from collections.abc import Iterator
from typing import Any
from urllib.parse import urljoin, urlparse
from django.http import HttpResponse, StreamingHttpResponse
from django.http.response import HttpResponseBase
from django.utils import timezone
import httpx
import structlog
from posthog.api.streaming import sse_streaming_response
from posthog.security.pinned_httpx import pinned_client
from posthog.security.pinned_requests import SSRFBlockedError
from posthog.security.url_validation import is_url_allowed
from posthog.settings import SERVER_GATEWAY_INTERFACE
from ee.hogai.utils.asgi import SyncIterableToAsync
from .models import MCPAuditEvent, MCPGatewayServer, MCPServerInstallation, MCPServerInstallationTool
from .oauth import TokenRefreshError, TokenRefreshRejectedError, is_token_expiring, refresh_installation_token
from .oauth_credentials import oauth_credentials_source_is_allowed
from .policy import GatewayCaller, PolicyContext, legacy_state_for_caller
from .url_policy import resolve_mcp_url_policy, trust_environment_proxy
logger = structlog.get_logger(__name__)
UPSTREAM_TIMEOUT = 180
MAX_PROXY_BODY_SIZE = 1_048_576 # 1 MB
MAX_LOGGED_MISSING_TOOLS = 20
REDIRECT_STATUS_CODES = {301, 302, 307, 308}
# JSON-RPC error codes used by per-tool approval enforcement. -32000..-32099 is
# the implementation-defined server-error range; we deliberately use distinct
# codes so clients can tell "needs approval" apart from "disabled" apart from
# the batch-level rejection, which is not tied to any individual item.
TOOL_NEEDS_APPROVAL_CODE = -32001
TOOL_DISABLED_CODE = -32002
BATCH_REJECTED_CODE = -32000
METHOD_NOT_FOUND_CODE = -32601
def _normalized_origin(url: str) -> tuple[str, str, int | None] | None:
parsed = urlparse(url)
try:
port = parsed.port
except ValueError:
return None
if port is None:
if parsed.scheme == "https":
port = 443
elif parsed.scheme == "http":
port = 80
return parsed.scheme, (parsed.hostname or "").lower(), port
def validated_same_origin_redirect_url(original_url: str, response: httpx.Response) -> str | None:
"""Return a safe redirect target for MCP URL canonicalization, or None.
MCP servers commonly redirect `/mcp` to `/mcp/`. Retrying with credentials is
only safe when the redirect stays on exactly the same origin; SSRF-safe is
not the same as credential-safe.
"""
if response.status_code not in REDIRECT_STATUS_CODES:
return None
location = response.headers.get("location")
if not location:
return None
redirect_url = urljoin(original_url, location)
original_origin = _normalized_origin(original_url)
redirect_origin = _normalized_origin(redirect_url)
if not original_origin or not redirect_origin or original_origin != redirect_origin:
logger.warning(
"Upstream MCP redirect rejected: target is cross-origin",
original_url=original_url,
redirect_url=redirect_url,
)
return None
allowed, reason = is_url_allowed(redirect_url)
if not allowed:
logger.warning(
"Upstream MCP redirect rejected by SSRF protection",
original_url=original_url,
redirect_url=redirect_url,
reason=reason,
)
return None
return redirect_url
def send_mcp_request_with_same_origin_redirect(
client: httpx.Client,
method: str,
url: str,
*,
headers: dict[str, str],
content: bytes | None = None,
stream: bool = False,
) -> tuple[httpx.Response, str]:
request_kwargs: dict[str, Any] = {"headers": headers}
if content is not None:
request_kwargs["content"] = content
upstream_request = client.build_request(method, url, **request_kwargs)
upstream_response = client.send(upstream_request, stream=stream)
redirect_url = validated_same_origin_redirect_url(url, upstream_response)
if not redirect_url:
return upstream_response, url
upstream_response.close()
redirected_request = client.build_request(method, redirect_url, **request_kwargs)
return client.send(redirected_request, stream=stream), redirect_url
def build_upstream_auth_headers(installation: MCPServerInstallation) -> dict[str, str]:
if installation.template and not oauth_credentials_source_is_allowed(
installation.template.oauth_credentials_source, installation.team_id
):
raise TokenRefreshRejectedError("OAuth app is not available for this project")
sensitive = installation.sensitive_configuration or {}
if installation.auth_type == "api_key":
api_key = sensitive.get("api_key")
if not api_key:
return {}
return {"Authorization": f"Bearer {api_key}"}
if installation.auth_type == "oauth":
access_token = sensitive.get("access_token")
if not access_token:
return {}
return {"Authorization": f"Bearer {access_token}"}
return {}
def ensure_valid_token(installation: MCPServerInstallation) -> None:
if not is_token_expiring(installation.sensitive_configuration or {}):
return
refresh_installation_token(installation)
def validate_installation_auth(
installation: MCPServerInstallation,
) -> tuple[bool, HttpResponse | None]:
"""Validate that the installation has valid auth credentials.
Returns (True, None) if auth is valid, or (False, error_response) if not.
"""
if not installation.is_enabled or (
installation.template
and not oauth_credentials_source_is_allowed(
installation.template.oauth_credentials_source, installation.team_id
)
):
logger.warning(
"Proxy auth failed: server is disabled",
installation_id=str(installation.id),
url=installation.url,
)
return False, HttpResponse(
'{"error": "Server is disabled"}',
content_type="application/json",
status=403,
)
sensitive = installation.sensitive_configuration or {}
if sensitive.get("needs_reauth"):
logger.warning(
"Proxy auth failed: needs re-authentication", installation_id=str(installation.id), url=installation.url
)
return False, HttpResponse(
'{"error": "Installation needs re-authentication"}',
content_type="application/json",
status=401,
)
if installation.auth_type == "oauth":
if not sensitive.get("access_token"):
logger.warning(
"Proxy auth failed: no OAuth credentials", installation_id=str(installation.id), url=installation.url
)
return False, HttpResponse(
'{"error": "No credentials configured"}',
content_type="application/json",
status=401,
)
try:
ensure_valid_token(installation)
except TokenRefreshRejectedError:
# refresh_installation_token has flagged the installation, unless a concurrent
# request had already replaced the credential the provider turned down. Say the
# refresh was rejected either way rather than leaving the caller to read a
# permanent failure as a retryable one.
logger.warning("OAuth token refresh rejected", installation_id=str(installation.id))
return False, HttpResponse(
'{"error": "Installation needs re-authentication"}',
content_type="application/json",
status=401,
)
except TokenRefreshError:
logger.warning("OAuth token refresh failed", installation_id=str(installation.id))
return False, HttpResponse(
'{"error": "Authentication failed"}',
content_type="application/json",
status=401,
)
if installation.auth_type == "api_key" and not sensitive.get("api_key"):
logger.warning(
"Proxy auth failed: no API key configured", installation_id=str(installation.id), url=installation.url
)
return False, HttpResponse(
'{"error": "No credentials configured"}',
content_type="application/json",
status=401,
)
return True, None
def _jsonrpc_error(request_id: Any, code: int, message: str) -> dict[str, Any]:
return {"jsonrpc": "2.0", "id": request_id, "error": {"code": code, "message": message}}
def _is_tools_call(item: Any) -> bool:
return isinstance(item, dict) and item.get("method") == "tools/call"
def _gateway_decision(policy_context: PolicyContext, tool: MCPServerInstallationTool) -> tuple[str, bool]:
"""Map a resolved policy onto an audit decision and whether to block.
approved via the caller's own scope (or a legacy per-installation approval)
reads as a human having approved it; approved via team baseline/rule is
auto. needs_approval blocks at the proxy — approval happens in PostHog, not
inline — and is recorded as pending."""
resolved = policy_context.resolve(tool.tool_name, tool.annotations)
if resolved.state == "do_not_use":
return "blocked", True
if resolved.state == "needs_approval":
return "pending", True
if resolved.decided_by in ("scope", "legacy"):
return "approved", False
return "auto", False
def resolve_call_decision(
tool: MCPServerInstallationTool,
policy_context: PolicyContext | None,
*,
caller_owns_installation: bool,
) -> tuple[str, str | None]:
"""Decide one tool call outside the JSON-RPC proxy path.
Returns ``(audit_decision, block_reason)`` where ``block_reason`` is None when
the call may proceed, else one of ``"removed"``, ``"needs_approval"`` or
``"disabled"``. Shares :func:`_gateway_decision` with the proxy so policy
resolution cannot diverge between the two entry points; the proxy keeps its own
JSON-RPC error mapping because its wire format is fixed by the MCP spec.
"""
if tool.removed_at is not None:
return "blocked", "removed"
if policy_context is not None:
decision, blocked = _gateway_decision(policy_context, tool)
if not blocked:
return decision, None
return decision, "needs_approval" if decision == "pending" else "disabled"
# Pre-gateway installations fall back to the cached per-tool approval flag.
state = legacy_state_for_caller(tool.approval_state, caller_owns_installation=caller_owns_installation)
if state == "approved":
return "approved", None
if state == "needs_approval":
return "pending", "needs_approval"
return "blocked", "disabled"
def record_tool_call_audit(
installation: MCPServerInstallation,
gateway_server: MCPGatewayServer,
caller: GatewayCaller,
actor_label: str,
tool_name: str,
decision: str,
) -> None:
"""Audit a single tool call. Same writer the proxy uses, one entry at a time."""
_write_audit_events(installation, gateway_server, caller, actor_label, [(tool_name, decision)])
def _evaluate_tool_call(
tools_by_name: dict[str, MCPServerInstallationTool],
item: dict[str, Any],
policy_context: PolicyContext | None,
audit_entries: list[tuple[str, str]] | None,
*,
caller_owns_installation: bool,
) -> dict[str, Any] | None:
"""Check a single JSON-RPC item against the installation's tool approval state.
Returns a JSON-RPC error object to send back (short-circuiting the upstream
call), or ``None`` to let the call pass through. With a ``policy_context``,
the effective state comes from the gateway policy engine instead of the raw
per-installation approval flag, and each decision is appended to
``audit_entries`` as ``(tool_name, decision)``.
"""
if not _is_tools_call(item):
return None
params = item.get("params") or {}
tool_name = params.get("name") if isinstance(params, dict) else None
request_id = item.get("id")
if not tool_name or not isinstance(tool_name, str):
return _jsonrpc_error(request_id, METHOD_NOT_FOUND_CODE, "tools/call missing 'name' parameter")
tool = tools_by_name.get(tool_name)
if tool is None:
return _jsonrpc_error(
request_id,
METHOD_NOT_FOUND_CODE,
f"Tool '{tool_name}' is not registered for this installation",
)
if tool.removed_at is not None:
return _jsonrpc_error(
request_id,
METHOD_NOT_FOUND_CODE,
f"Tool '{tool_name}' is no longer available on the upstream server",
)
if policy_context is not None:
decision, blocked = _gateway_decision(policy_context, tool)
if audit_entries is not None:
audit_entries.append((tool_name, decision))
if not blocked:
return None
if decision == "pending":
return _jsonrpc_error(
request_id,
TOOL_NEEDS_APPROVAL_CODE,
f"Tool '{tool_name}' requires approval before it can be called",
)
return _jsonrpc_error(
request_id,
TOOL_DISABLED_CODE,
f"Tool '{tool_name}' is blocked by team policy",
)
state = legacy_state_for_caller(tool.approval_state, caller_owns_installation=caller_owns_installation)
if state == "approved":
return None
if state == "needs_approval":
return _jsonrpc_error(
request_id,
TOOL_NEEDS_APPROVAL_CODE,
f"Tool '{tool_name}' requires approval before it can be called",
)
if state == "do_not_use":
return _jsonrpc_error(
request_id,
TOOL_DISABLED_CODE,
f"Tool '{tool_name}' has been disabled by the user",
)
return None
def _requested_tool_names(data: dict[str, Any] | list[Any]) -> set[str]:
names: set[str] = set()
for item in data if isinstance(data, list) else [data]:
if not _is_tools_call(item):
continue
params = item.get("params") or {}
name = params.get("name") if isinstance(params, dict) else None
if isinstance(name, str) and name:
names.add(name)
return names
def _unresolvable_tool_names(tools: dict[str, MCPServerInstallationTool], requested: set[str]) -> set[str]:
"""The requested names no live row answers. A row marked removed counts as a
miss, so a tool the upstream server brings back is picked up by a re-listing."""
return {name for name in requested if tools.get(name) is None or tools[name].removed_at is not None}
def _tools_by_name(installation: MCPServerInstallation, requested: set[str]) -> dict[str, MCPServerInstallationTool]:
"""The installation's tool rows, re-listed from upstream on a miss.
These rows are the policy registry rather than a performance cache: a call
whose tool has no row cannot be resolved against policy, so it is refused.
An installation whose connect-time listing never landed therefore refuses
every call until a person presses "Refresh tools". Re-listing once on a miss
repairs that without waiting for them, and covers a tool the upstream server
renamed after the last listing.
"""
tools = {t.tool_name: t for t in installation.tools.all()}
if not _unresolvable_tool_names(tools, requested):
return tools
from .tools import resync_installation_tools # noqa: PLC0415 — tools.py imports this module
if resync_installation_tools(installation):
tools = {t.tool_name: t for t in installation.tools.all()}
missing = _unresolvable_tool_names(tools, requested)
if missing:
logger.warning(
"MCP tool call refers to an unregistered tool",
installation_id=str(installation.id),
url=installation.url,
# A batch carries as many names as the body allows, and the size limit
# is checked further down, so log a sample rather than all of them.
missing_tools=sorted(missing)[:MAX_LOGGED_MISSING_TOOLS],
missing_tool_count=len(missing),
registered_tool_count=len(tools),
)
return tools
def enforce_tool_approval(
installation: MCPServerInstallation,
data: dict[str, Any] | list[Any],
policy_context: PolicyContext | None = None,
audit_entries: list[tuple[str, str]] | None = None,
*,
caller_user_id: int | None,
) -> HttpResponse | None:
"""Inspect a JSON-RPC body and short-circuit tools/call that isn't approved.
Returns an HttpResponse when at least one tool call is blocked, or None to
pass the request through unchanged. Non-tools/call methods are always
passed through; unknown tool names return a JSON-RPC method-not-found error
without hitting the upstream server.
"""
caller_owns_installation = caller_user_id is not None and caller_user_id == installation.user_id
if isinstance(data, list):
if not any(_is_tools_call(item) for item in data):
return None
# Pre-fetch the installation's tools once to avoid N queries on batched tools/call.
tools_by_name = _tools_by_name(installation, _requested_tool_names(data))
responses: list[dict[str, Any]] = []
any_blocked = False
any_passthrough = False
for item in data:
blocked = _evaluate_tool_call(
tools_by_name, item, policy_context, audit_entries, caller_owns_installation=caller_owns_installation
)
if blocked is not None:
responses.append(blocked)
any_blocked = True
else:
any_passthrough = True
# Mixed batches (some blocked, some passthrough) can't be safely split
# without reshuffling responses. Reject the whole batch so clients retry
# individual calls — this matches the spec's guidance to keep batches atomic.
# Use a batch-level code rather than TOOL_NEEDS_APPROVAL_CODE: passthrough
# items like tools/list have no per-item approval concept, so signaling
# "approval needed" on them would mislead client retry logic.
if any_blocked and any_passthrough:
if audit_entries is not None:
audit_entries[:] = [entry for entry in audit_entries if entry[1] in ("blocked", "pending")]
return HttpResponse(
json.dumps(
[
_jsonrpc_error(
(item.get("id") if isinstance(item, dict) else None),
BATCH_REJECTED_CODE,
"Batch rejected: it contains a tool call that requires approval or is disabled; "
"send items individually",
)
for item in data
]
),
content_type="application/json",
status=200,
)
if any_blocked:
return HttpResponse(json.dumps(responses), content_type="application/json", status=200)
return None
if not _is_tools_call(data):
return None
tools_by_name = _tools_by_name(installation, _requested_tool_names(data))
blocked = _evaluate_tool_call(
tools_by_name, data, policy_context, audit_entries, caller_owns_installation=caller_owns_installation
)
if blocked is None:
return None
return HttpResponse(json.dumps(blocked), content_type="application/json", status=200)
def _write_audit_events(
installation: MCPServerInstallation,
gateway_server: MCPGatewayServer,
caller: GatewayCaller,
actor_label: str,
entries: list[tuple[str, str]],
credential_owner_id: int | None = None,
grant_scope: str = "",
) -> None:
"""Best-effort audit trail — a failed insert must never break the proxy."""
try:
MCPAuditEvent.objects.for_team(gateway_server.team_id, canonical=True).bulk_create(
[
MCPAuditEvent(
team_id=gateway_server.team_id,
gateway_server=gateway_server,
installation=installation,
actor_user_id=caller.user_id,
actor_service_account_id=caller.service_account_id,
actor_label=actor_label,
credential_owner_id=credential_owner_id,
grant_scope=grant_scope,
server_name=gateway_server.name,
tool_name=tool_name,
decision=decision,
)
for tool_name, decision in entries
]
)
if any(decision in ("auto", "approved") for _, decision in entries):
MCPServerInstallation.objects.filter(pk=installation.pk).update(last_used_at=timezone.now())
except Exception:
logger.exception("Failed to write MCP gateway audit events", installation_id=str(installation.id))
def proxy_mcp_request(
request: Any,
installation: MCPServerInstallation,
*,
caller: GatewayCaller | None = None,
gateway_server: MCPGatewayServer | None = None,
actor_label: str = "",
credential_owner_id: int | None = None,
grant_scope: str = "",
) -> HttpResponseBase:
"""Forward one MCP request upstream, enforcing tool policy and auditing it.
`credential_owner_id` and `grant_scope` describe the agent grant the call
rides, so the audit trail answers whose connection an agent used. Both are
empty for member calls, where the actor already is the credential owner.
"""
verdict = resolve_mcp_url_policy(installation.url, installation.team_id)
if not verdict.allowed:
logger.warning("SSRF: blocked proxy request", url=installation.url, reason=verdict.reason)
return HttpResponse(
json.dumps({"error": f"URL not allowed: {verdict.reason}"}),
content_type="application/json",
status=400,
)
data = request.data
if not data or not isinstance(data, (dict, list)):
logger.warning("Proxy request rejected: invalid request body", url=installation.url)
return HttpResponse(
'{"error": "Request body must be valid JSON"}',
content_type="application/json",
status=400,
)
policy_context: PolicyContext | None = None
audit_entries: list[tuple[str, str]] = []
if gateway_server is not None and caller is not None:
policy_context = PolicyContext(
team_id=installation.team_id,
caller=caller,
gateway_server=gateway_server,
installation=installation,
)
enforcement_response = enforce_tool_approval(
installation,
data,
policy_context,
audit_entries,
caller_user_id=caller.user_id if caller is not None and caller.kind == "member" else None,
)
if gateway_server is not None and caller is not None and audit_entries:
_write_audit_events(
installation,
gateway_server,
caller,
actor_label,
audit_entries,
credential_owner_id=credential_owner_id,
grant_scope=grant_scope,
)
if enforcement_response:
return enforcement_response
body = json.dumps(data).encode()
if len(body) > MAX_PROXY_BODY_SIZE:
logger.warning("Proxy request rejected: body too large", url=installation.url, body_size=len(body))
return HttpResponse(
'{"error": "Request body too large"}',
content_type="application/json",
status=413,
)
auth_headers = build_upstream_auth_headers(installation)
headers = {
"Content-Type": "application/json",
"Accept": "application/json, text/event-stream",
**auth_headers,
}
for header_name in request.headers:
if header_name.lower().startswith("x-posthog-") and header_name.lower() not in {
"x-posthog-mcp-mode",
"x-posthog-mcp-store",
}:
headers[header_name] = request.headers[header_name]
# Store policy must see leaf tools, and shared credentials must not expand nested connectors.
headers["x-posthog-mcp-mode"] = "tools"
headers["x-posthog-mcp-store"] = "true"
mcp_session_id = request.headers.get("mcp-session-id")
if mcp_session_id:
headers["Mcp-Session-Id"] = mcp_session_id
client = pinned_client(
installation.url,
verdict.pinned_ips,
timeout=UPSTREAM_TIMEOUT,
trust_env=trust_environment_proxy(installation.url, installation.team_id),
)
try:
upstream_response, upstream_url = send_mcp_request_with_same_origin_redirect(
client,
"POST",
installation.url,
content=body,
headers=headers,
stream=True,
)
except (SSRFBlockedError, httpx.ProxyError):
client.close()
logger.warning("Upstream MCP connection blocked by URL or proxy policy")
return HttpResponse(
'{"error": "Upstream MCP connection blocked. Ask an administrator to check the outbound proxy configuration."}',
content_type="application/json",
status=502,
)
except httpx.ConnectError:
client.close()
logger.warning("Upstream MCP server unreachable", url=installation.url)
return HttpResponse(
'{"error": "Upstream MCP server unreachable"}',
content_type="application/json",
status=502,
)
except httpx.TimeoutException:
client.close()
logger.warning("Upstream MCP server timed out", url=installation.url)
return HttpResponse(
'{"error": "Upstream MCP server timed out"}',
content_type="application/json",
status=502,
)
except Exception:
client.close()
raise
content_type = upstream_response.headers.get("content-type", "")
if "text/event-stream" in content_type:
return _build_sse_response(upstream_response, client)
# Read body then close to avoid memory leaks from buffered responses
try:
upstream_response.read()
finally:
client.close()
if upstream_response.status_code >= 400:
logger.warning(
"Upstream MCP server returned error",
url=upstream_url,
status_code=upstream_response.status_code,
response_body=upstream_response.text[:500] if upstream_response.text else "",
)
response = HttpResponse(
upstream_response.content,
content_type=upstream_response.headers.get("content-type", "application/json"),
status=upstream_response.status_code,
)
upstream_session_id = upstream_response.headers.get("mcp-session-id")
if upstream_session_id:
response["Mcp-Session-Id"] = upstream_session_id
return response
def _stream_upstream(upstream_response: httpx.Response, client: httpx.Client) -> Iterator[bytes]:
try:
yield from upstream_response.iter_bytes(4096)
finally:
upstream_response.close()
client.close()
def _build_sse_response(upstream_response: httpx.Response, client: httpx.Client) -> HttpResponseBase:
stream = _stream_upstream(upstream_response, client)
astream = SyncIterableToAsync(stream) if SERVER_GATEWAY_INTERFACE == "ASGI" else stream
response = sse_streaming_response(astream, endpoint="mcp_store_proxy")
if not isinstance(response, StreamingHttpResponse):
# Over-cap rejection: the generator that owns these resources never
# starts, so its finally never runs. Close them here (both closes are
# idempotent) instead of leaking them until the upstream timeout.
upstream_response.close()
client.close()
return response
upstream_session_id = upstream_response.headers.get("mcp-session-id")
if upstream_session_id:
response["Mcp-Session-Id"] = upstream_session_id
return response