Umami is a privacy-first web and product analytics platform. Traffic, campaigns, behavior, conversions, and revenue in one place. No cookies, no surveillance, self-hosted or in the cloud.
TypeScript analyticsaudience-segmentationchartscohort-analysisgoogle-analyticsproduct-analyticsstatisticsuser-journeyweb-analytics
Gate MCP endpoint behind MCP_ENABLED flag
Mike Cao2b7eb29a0e50
diff --cc README.mdindex e0ebef01b,6b55a27f6..c641cee3a--- a/README.md+++ b/README.md@@@ -54,6 -54,10 +54,9 @@@ Optional: set `TWO_FACTOR_ENCRYPTION_KEauthentication. Generate one with `openssl rand -hex 32`. Two-factor authentication is unavailableand cannot be required until this key is set.-MCP and its OAuth endpoints are disabled by default. To enable them, set `MCP_ENABLED=1` and-`OAUTH_ISSUER` to Umami's public URL. Dynamic client registration remains disabled unless-`OAUTH_DCR_ENABLED=1` is also set.++MCP is disabled by default. Set `MCP_ENABLED=1` to enable the `/mcp` endpoint, then++authenticate with an API key generated under Settings → API keys.+The connection URL format:```bashdiff --cc docker-compose.test.ymlindex 8c68caced,8c68caced..5e923bc92--- a/docker-compose.test.yml+++ b/docker-compose.test.yml@@@ -38,6 -38,6 +38,7 @@@ x-umami-env: &umami-enDISABLE_BOT_CHECK: "1"DISABLE_TELEMETRY: "1"DISABLE_UPDATES: "1"++ MCP_ENABLED: "1"services:db:diff --cc packages/mcp/README.mdindex a89ffec51,9799667ec..59de9b28b--- a/packages/mcp/README.md+++ b/packages/mcp/README.md@@@ -51,16 -55,12 +51,16 @@@ MCP client with the Streamable HTTP endhttps://your-umami.example.com/mcp```-The client discovers `/.well-known/oauth-protected-resource/mcp`, sends you to Umami to sign in-and approve access (`websites:read`, `analytics:read`), and receives an OAuth token. No API key-is pasted anywhere. Clients register via Client ID Metadata Documents; dynamic client registration-is available only when `OAUTH_DCR_ENABLED=1` is set.+Set the authorization header using your key:++```text+Authorization: Bearer umami_<your-api-key>+```-Self-hosted instances can alternatively pass an API key (`umami_…`) as the bearer token.+Use a client that supports bearer tokens or custom authorization headers. The endpoint accepts+self-hosted API keys; browser login tokens are not supported. Tools are read-only and respect+the key owner's existing user/team permissions. Revoke the key in Settings to disconnect access.- Set `MCP_DISABLED=1` to disable the endpoint.++MCP is disabled by default. Set `MCP_ENABLED=1` to enable the endpoint.## Local / stdiodiff --cc src/app/mcp/route.test.tsindex 000000000,000000000..4f2d0f41fnew file mode 100644--- /dev/null+++ b/src/app/mcp/route.test.ts@@@ -1,0 -1,0 +1,40 @@@++import { afterEach, beforeEach, expect, test, vi } from 'vitest';++import { authenticateMcpRequest } from '@/lib/mcp/auth';++import { DELETE, GET, POST } from './route';++++vi.mock('@umami/mcp', () => ({++ createUmamiMcpHttpHandler: () => ({ fetch: vi.fn() }),++}));++vi.mock('@/lib/mcp/auth', () => ({++ authenticateMcpRequest: vi.fn(),++ mcpAuthErrorResponse: () => new Response(null, { status: 401 }),++}));++++beforeEach(() => {++ vi.mocked(authenticateMcpRequest).mockReset();++ vi.mocked(authenticateMcpRequest).mockResolvedValue({++ ok: false,++ status: 401,++ error: 'invalid_request',++ description: 'Missing bearer API key.',++ });++});++++afterEach(() => vi.unstubAllEnvs());++++test.each([undefined, '', '0', 'true'])('MCP stays disabled for MCP_ENABLED=%s', async value => {++ vi.stubEnv('MCP_ENABLED', value);++ for (const handler of [GET, POST, DELETE]) {++ const response = await handler(new Request('http://localhost/mcp'));++ expect(response.status).toBe(404);++ }++ expect(authenticateMcpRequest).not.toHaveBeenCalled();++});++++test('MCP_ENABLED=1 enables API-key authentication', async () => {++ vi.stubEnv('MCP_ENABLED', '1');++ const request = new Request('http://localhost/mcp');++ const response = await POST(request);++ expect(response.status).toBe(401);++ expect(authenticateMcpRequest).toHaveBeenCalledWith(request);++});diff --cc src/app/mcp/route.tsindex a1eb97da4,4f6caad27..2755910d7--- a/src/app/mcp/route.ts+++ b/src/app/mcp/route.ts@@@ -38,7 -38,7 +38,7 @@@ const handler = createUmamiMcpHttpHandl});async function handle(request: Request) {- if (process.env.MCP_DISABLED === '1') {- if (!isOAuthEnabled()) {++ if (process.env.MCP_ENABLED !== '1') {return new Response(null, { status: 404 });}