Skip to content

Open source, privacy-first web analytics. Lightweight, cookie-free Google Analytics alternative. Self-hosted or cloud.

Add skeleton for MCP feature (#6594)

Artur Patad777fb9628fb
diff --git a/lib/plausible_web/controllers/mcp/mcp_controller.ex b/lib/plausible_web/controllers/mcp/mcp_controller.ex
new file mode 100644
index 0000000000..642549c8c6
--- /dev/null
+++ b/lib/plausible_web/controllers/mcp/mcp_controller.ex
@@ -0,0 +1,27 @@
+defmodule PlausibleWeb.MCP.MCPController do
+ @moduledoc """
+ Model Context Protocol (MCP) endpoint over Streamable HTTP, implementing the
+ stateless `2026-07-28` revision of the protocol.
+ """
+
+ use PlausibleWeb, :controller
+
+ @doc """
+ Answers a single JSON-RPC request (https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http#sending-messages).
+ """
+ def handle(conn, _params) do
+ conn
+ |> put_status(501)
+ |> json(%{error: "not_implemented"})
+ end
+
+ @doc """
+ Handles `GET` and `DELETE` verbs that earlier MCP versions used for session management by rejecting them.
+ This implementation is not backwards-compatible (https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http#earlier-streamable-http-revisions).
+ """
+ def not_supported(conn, _params) do
+ conn
+ |> put_status(405)
+ |> json(%{error: "method_not_allowed", error_description: "Use POST for MCP."})
+ end
+end
diff --git a/lib/plausible_web/controllers/oauth/authorize_controller.ex b/lib/plausible_web/controllers/oauth/authorize_controller.ex
new file mode 100644
index 0000000000..e39a5664b0
--- /dev/null
+++ b/lib/plausible_web/controllers/oauth/authorize_controller.ex
@@ -0,0 +1,30 @@
+defmodule PlausibleWeb.OAuth.AuthorizeController do
+ @moduledoc """
+ OAuth 2.1 authorization module.
+ """
+
+ use PlausibleWeb, :controller
+
+ @doc """
+ Validates an incoming [authorization request](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1#name-authorization-request)
+ and renders the consent screen for the logged-in user.
+ """
+ def authorize_form(conn, _params) do
+ not_implemented(conn)
+ end
+
+ @doc """
+ Turns the user's approve/deny decision into an
+ [authorization response](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1#name-authorization-response),
+ redirecting back to the client with a code or an error.
+ """
+ def authorize(conn, _params) do
+ not_implemented(conn)
+ end
+
+ defp not_implemented(conn) do
+ conn
+ |> put_status(501)
+ |> json(%{error: "not_implemented"})
+ end
+end
diff --git a/lib/plausible_web/controllers/oauth/metadata_controller.ex b/lib/plausible_web/controllers/oauth/metadata_controller.ex
new file mode 100644
index 0000000000..cf70ecd9f2
--- /dev/null
+++ b/lib/plausible_web/controllers/oauth/metadata_controller.ex
@@ -0,0 +1,30 @@
+defmodule PlausibleWeb.OAuth.MetadataController do
+ @moduledoc """
+ Serves the discovery documents an MCP client walks to learn how to authenticate for `/mcp` endpoint.
+ """
+
+ use PlausibleWeb, :controller
+
+ @doc """
+ Serves the [RFC 9728 Protected Resource Metadata](https://www.rfc-editor.org/rfc/rfc9728.html#name-protected-resource-metadata)
+ naming `/mcp` as the resource and pointing at the authorization server that
+ protects it.
+ """
+ def protected_resource(conn, _params) do
+ not_implemented(conn)
+ end
+
+ @doc """
+ Serves the [RFC 8414 Authorization Server Metadata](https://www.rfc-editor.org/rfc/rfc8414.html#section-2)
+ advertising the authorize and token endpoints and the grants they accept.
+ """
+ def authorization_server(conn, _params) do
+ not_implemented(conn)
+ end
+
+ defp not_implemented(conn) do
+ conn
+ |> put_status(501)
+ |> json(%{error: "not_implemented"})
+ end
+end
diff --git a/lib/plausible_web/controllers/oauth/token_controller.ex b/lib/plausible_web/controllers/oauth/token_controller.ex
new file mode 100644
index 0000000000..b2cd7e6c34
--- /dev/null
+++ b/lib/plausible_web/controllers/oauth/token_controller.ex
@@ -0,0 +1,17 @@
+defmodule PlausibleWeb.OAuth.TokenController do
+ @moduledoc """
+ OAuth 2.1 token endpoint. Public client (PKCE, no client authentication).
+ """
+
+ use PlausibleWeb, :controller
+
+ @doc """
+ Exchanges an authorization code or a refresh token for an access token at the
+ [token endpoint](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1#name-token-endpoint).
+ """
+ def token(conn, _params) do
+ conn
+ |> put_status(501)
+ |> json(%{error: "not_implemented"})
+ end
+end
diff --git a/lib/plausible_web/router.ex b/lib/plausible_web/router.ex
index f2474fcec1..35e6c389bf 100644
--- a/lib/plausible_web/router.ex
+++ b/lib/plausible_web/router.ex
@@ -109,6 +109,16 @@ defmodule PlausibleWeb.Router do
forward "/sent-emails-api", Bamboo.SentEmailApiPlug
end
+ # OAuth 2.1 discovery documents
+ scope "/.well-known", PlausibleWeb do
+ pipe_through :external_api
+
+ get "/oauth-protected-resource", OAuth.MetadataController, :protected_resource
+ get "/oauth-protected-resource/mcp", OAuth.MetadataController, :protected_resource
+
+ get "/oauth-authorization-server", OAuth.MetadataController, :authorization_server
+ end
+
on_ee do
live_session :customer_support,
on_mount: PlausibleWeb.Live.SuperAdminLiveAuth do
@@ -453,6 +463,10 @@ defmodule PlausibleWeb.Router do
post "/activate", AuthController, :activate
get "/login", AuthController, :login_form
post "/login", AuthController, :login
+
+ get "/login/oauth/authorize", OAuth.AuthorizeController, :authorize_form
+ post "/login/oauth/authorize", OAuth.AuthorizeController, :authorize
+
get "/password/request-reset", AuthController, :password_reset_request_form
post "/password/request-reset", AuthController, :password_reset_request
get "/2fa/setup/force-initiate", AuthController, :force_initiate_2fa_setup
@@ -471,6 +485,19 @@ defmodule PlausibleWeb.Router do
post "/error_report", ErrorReportController, :submit_error_report
end
+ scope "/login/oauth", PlausibleWeb do
+ pipe_through :external_api
+ post "/token", OAuth.TokenController, :token
+ end
+
+ scope "/", PlausibleWeb do
+ pipe_through :external_api
+
+ post "/mcp", MCP.MCPController, :handle
+ get "/mcp", MCP.MCPController, :not_supported
+ delete "/mcp", MCP.MCPController, :not_supported
+ end
+
scope "/", PlausibleWeb do
pipe_through [:shared_link]