feat(middleware): Add AI agent friendly responses for unauthenticated requests

Add middleware that detects AI agents accessing frontend UI routes
(via Accept: text/markdown header) and returns helpful guidance
instead of HTML. The response includes:

- MCP server configuration with context-aware URLs
- REST API documentation links
- Token generation instructions

The middleware extracts org/project context from the URL path to
provide pre-configured MCP server URLs.

Fixes GH-106334
Co-Authored-By: Claude <noreply@anthropic.com>

Author: dcramer

src/sentry/conf/server.py

@@ -383,6 +383,7 @@ def env(
     "django.contrib.sessions.middleware.SessionMiddleware",
     "django.middleware.csrf.CsrfViewMiddleware",
     "sentry.middleware.auth.AuthenticationMiddleware",
+    "sentry.middleware.ai_agent.AIAgentMiddleware",
     "sentry.middleware.integrations.IntegrationControlMiddleware",
     "sentry.hybridcloud.apigateway.middleware.ApiGatewayMiddleware",
     "sentry.middleware.demo_mode_guard.DemoModeGuardMiddleware",

src/sentry/middleware/ai_agent.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+
+from django.http import HttpRequest, HttpResponse
+
+from sentry.utils import json
+
+logger = logging.getLogger(__name__)
+
+# Patterns to extract org and project from URL paths
+ORG_PATTERN = re.compile(r"^/organizations/([^/]+)/")
+PROJECT_PATTERN = re.compile(r"^/organizations/([^/]+)/projects/([^/]+)/")
+
+
+def _build_mcp_config(org_slug: str | None, project_slug: str | None) -> dict[str, Any]:
+    """Build the MCP server configuration object."""
+    path_segments = ["https://mcp.sentry.dev/mcp"]
+    if org_slug:
+        path_segments.append(org_slug)
+    if project_slug:
+        path_segments.append(project_slug)
+
+    return {
+        "mcpServers": {
+            "sentry": {
+                "url": "/".join(path_segments),
+            }
+        }
+    }
+
+
+def _extract_org_project_from_path(path: str) -> tuple[str | None, str | None]:
+    """Extract organization and project slugs from a URL path."""
+    if project_match := PROJECT_PATTERN.match(path):
+        return project_match.group(1), project_match.group(2)
+    if org_match := ORG_PATTERN.match(path):
+        return org_match.group(1), None
+    return None, None
+
+
+def _build_ai_agent_guidance(request: HttpRequest) -> str:
+    """Build context-aware guidance based on the request path."""
+    org_slug, project_slug = _extract_org_project_from_path(request.path)
+
+    mcp_config = _build_mcp_config(org_slug, project_slug)
+    mcp_config_json = json.dumps(mcp_config, indent=2)
+
+    return f"""\
+# Hey, you've hit the Sentry web UI
+
+This URL serves HTML for humans in browsers. You probably want one of these instead:
+
+## MCP Server (recommended for AI agents)
+
+This is an HTTP streaming MCP endpoint that uses OAuth for authentication.
+
+```json
+{mcp_config_json}
+```
+
+More info: https://mcp.sentry.dev
+
+## REST API (for scripts and integrations)
+
+```
+curl https://sentry.io/api/0/projects/ \\
+  -H "Authorization: Bearer <token>"
+```
+
+Your user can generate a token at: https://sentry.io/settings/account/api/auth-tokens/
+
+Docs: https://docs.sentry.io/api/
+"""
+
+
+def _accepts_markdown(request: HttpRequest) -> bool:
+    """Check if Accept header contains a markdown content type."""
+    accept = request.META.get("HTTP_ACCEPT", "").lower()
+    return "text/markdown" in accept or "text/x-markdown" in accept
+
+
+def _is_anonymous_request(request: HttpRequest) -> bool:
+    """Check if the request is anonymous (no authenticated user, no auth token)."""
+    if getattr(request, "auth", None) is not None:
+        return False
+
+    user = getattr(request, "user", None)
+    return user is None or user.is_anonymous
+
+
+class AIAgentMiddleware:
+    """
+    Middleware that intercepts unauthenticated frontend requests from AI agents
+    and returns helpful markdown guidance instead of HTML.
+
+    Detection criteria:
+    1. Request path does NOT start with /api/ (frontend routes only)
+    2. Accept header contains text/markdown or text/x-markdown
+    3. Request is anonymous (no authenticated user, no auth token)
+    """
+
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+    def __call__(self, request: HttpRequest) -> HttpResponse:
+        # Skip API routes - only intercept frontend UI routes
+        if request.path.startswith("/api/"):
+            return self.get_response(request)
+
+        if not _accepts_markdown(request):
+            return self.get_response(request)
+
+        if not _is_anonymous_request(request):
+            return self.get_response(request)
+
+        logger.info(
+            "ai_agent.guidance_served",
+            extra={
+                "path": request.path,
+                "user_agent": request.META.get("HTTP_USER_AGENT", ""),
+            },
+        )
+
+        guidance = _build_ai_agent_guidance(request)
+        return HttpResponse(guidance, content_type="text/markdown", status=200)

tests/sentry/middleware/test_ai_agent.py

@@ -0,0 +1,147 @@
+from unittest.mock import MagicMock, patch
+
+from django.contrib.auth.models import AnonymousUser
+from django.test import RequestFactory
+
+from sentry.middleware.ai_agent import AIAgentMiddleware, _accepts_markdown, _is_anonymous_request
+from sentry.testutils.cases import TestCase
+
+
+class AcceptsMarkdownTest(TestCase):
+    def setUp(self):
+        super().setUp()
+        self.factory = RequestFactory()
+
+    def test_accepts_text_markdown(self):
+        request = self.factory.get("/", HTTP_ACCEPT="text/markdown")
+        assert _accepts_markdown(request) is True
+
+    def test_accepts_text_x_markdown(self):
+        request = self.factory.get("/", HTTP_ACCEPT="text/x-markdown")
+        assert _accepts_markdown(request) is True
+
+    def test_rejects_text_plain(self):
+        request = self.factory.get("/", HTTP_ACCEPT="text/plain")
+        assert _accepts_markdown(request) is False
+
+    def test_rejects_application_json(self):
+        request = self.factory.get("/", HTTP_ACCEPT="application/json")
+        assert _accepts_markdown(request) is False
+
+    def test_no_accept_header(self):
+        request = self.factory.get("/")
+        assert _accepts_markdown(request) is False
+
+    def test_case_insensitive(self):
+        request = self.factory.get("/", HTTP_ACCEPT="TEXT/MARKDOWN")
+        assert _accepts_markdown(request) is True
+
+
+class IsAnonymousRequestTest(TestCase):
+    def setUp(self):
+        super().setUp()
+        self.factory = RequestFactory()
+
+    def test_anonymous_user_no_auth(self):
+        request = self.factory.get("/")
+        request.user = AnonymousUser()
+        request.auth = None
+        assert _is_anonymous_request(request) is True
+
+    def test_anonymous_user_with_auth(self):
+        request = self.factory.get("/")
+        request.user = AnonymousUser()
+        request.auth = MagicMock()
+        assert _is_anonymous_request(request) is False
+
+    def test_authenticated_user(self):
+        request = self.factory.get("/")
+        request.user = self.create_user()
+        request.auth = None
+        assert _is_anonymous_request(request) is False
+
+
+class AIAgentMiddlewareTest(TestCase):
+    def setUp(self):
+        super().setUp()
+        self.factory = RequestFactory()
+        self.middleware = AIAgentMiddleware(get_response=lambda r: MagicMock(status_code=401))
+
+    def make_anonymous_request(self, path: str, **kwargs):
+        request = self.factory.get(path, **kwargs)
+        request.user = AnonymousUser()
+        request.auth = None
+        return request
+
+    def test_returns_guidance_for_anonymous_markdown_request(self):
+        request = self.make_anonymous_request(
+            "/organizations/test-org/issues/", HTTP_ACCEPT="text/markdown"
+        )
+
+        response = self.middleware(request)
+
+        assert response.status_code == 200
+        assert response["Content-Type"] == "text/markdown"
+        content = response.content.decode()
+        assert "Hey, you've hit the Sentry web UI" in content
+        assert "https://mcp.sentry.dev/mcp/test-org" in content
+
+    def test_includes_project_in_mcp_url(self):
+        request = self.make_anonymous_request(
+            "/organizations/my-org/projects/my-project/", HTTP_ACCEPT="text/markdown"
+        )
+
+        response = self.middleware(request)
+
+        assert response.status_code == 200
+        assert "https://mcp.sentry.dev/mcp/my-org/my-project" in response.content.decode()
+
+    def test_base_mcp_url_without_org_context(self):
+        request = self.make_anonymous_request("/settings/", HTTP_ACCEPT="text/markdown")
+
+        response = self.middleware(request)
+
+        assert response.status_code == 200
+        assert "https://mcp.sentry.dev/mcp" in response.content.decode()
+
+    def test_authenticated_user_passes_through(self):
+        request = self.factory.get("/organizations/test-org/", HTTP_ACCEPT="text/markdown")
+        request.user = self.create_user()
+        request.auth = None
+
+        assert self.middleware(request).status_code == 401
+
+    def test_auth_token_passes_through(self):
+        request = self.factory.get("/organizations/test-org/", HTTP_ACCEPT="text/markdown")
+        request.user = AnonymousUser()
+        request.auth = MagicMock()
+
+        assert self.middleware(request).status_code == 401
+
+    def test_non_markdown_accept_passes_through(self):
+        request = self.make_anonymous_request("/organizations/test-org/", HTTP_ACCEPT="text/html")
+
+        assert self.middleware(request).status_code == 401
+
+    def test_api_path_passes_through(self):
+        request = self.make_anonymous_request("/api/0/projects/", HTTP_ACCEPT="text/markdown")
+
+        assert self.middleware(request).status_code == 401
+
+    @patch("sentry.middleware.ai_agent.logger.info")
+    def test_logs_request(self, mock_logger: MagicMock):
+        request = self.make_anonymous_request(
+            "/organizations/test-org/",
+            HTTP_ACCEPT="text/markdown",
+            HTTP_USER_AGENT="Claude-Code/1.0",
+        )
+
+        self.middleware(request)
+
+        mock_logger.assert_called_once_with(
+            "ai_agent.guidance_served",
+            extra={
+                "path": "/organizations/test-org/",
+                "user_agent": "Claude-Code/1.0",
+            },
+        )