From 77b186c3a599297da0cf19e923c66607ad7d74e7 Mon Sep 17 00:00:00 2001
From: Chen Ye <cye@alumni.brown.edu>
Date: Sun, 8 Feb 2026 16:07:31 -0800
Subject: feat(mcp): Support custom configurable HTTP headers (#2436)

* feat(mcp): Support custom configurable HTTP headers

* docs(mcp): Add KARAKEEP_CUSTOM_HEADERS documentation

* fix(mcp): Prioritize default headers and safely parse custom headers

* docs(mcp): Correct capitalization of Cloudflare headers
---
 apps/mcp/README.md     | 10 +++++++---
 apps/mcp/src/shared.ts | 12 ++++++++++++
 2 files changed, 19 insertions(+), 3 deletions(-)

diff --git a/apps/mcp/README.md b/apps/mcp/README.md
index 0d134c34..45b0d79f 100644
--- a/apps/mcp/README.md
+++ b/apps/mcp/README.md
@@ -1,6 +1,7 @@
 # Karakeep MCP Server
 
-This is the Karakeep MCP server, which is a server that can be used to interact with Karakeep from other tools.
+This is the Karakeep MCP server, which is a server that can be used to interact
+with Karakeep from other tools.
 
 ## Supported Tools
 
@@ -22,11 +23,12 @@ From NPM:
     "karakeep": {
       "command": "npx",
       "args": [
-        "@karakeep/mcp",
+        "@karakeep/mcp"
       ],
       "env": {
         "KARAKEEP_API_ADDR": "https://<YOUR_SERVER_ADDR>",
-        "KARAKEEP_API_KEY": "<YOUR_TOKEN>"
+        "KARAKEEP_API_KEY": "<YOUR_TOKEN>",
+        "KARAKEEP_CUSTOM_HEADERS": "{\"CF-Access-Client-Id\": \"...\", \"CF-Access-Client-Secret\": \"...\"}"
       }
     }
   }
@@ -46,6 +48,8 @@ From Docker:
         "KARAKEEP_API_ADDR=https://<YOUR_SERVER_ADDR>",
         "-e",
         "KARAKEEP_API_KEY=<YOUR_TOKEN>",
+        "-e",
+        "KARAKEEP_CUSTOM_HEADERS={\"CF-Access-Client-Id\": \"...\", \"CF-Access-Client-Secret\": \"...\"}",
         "ghcr.io/karakeep-app/karakeep-mcp:latest"
       ]
     }
diff --git a/apps/mcp/src/shared.ts b/apps/mcp/src/shared.ts
index a80c3620..b2ffff05 100644
--- a/apps/mcp/src/shared.ts
+++ b/apps/mcp/src/shared.ts
@@ -6,9 +6,21 @@ import { createKarakeepClient } from "@karakeep/sdk";
 const addr = process.env.KARAKEEP_API_ADDR;
 const apiKey = process.env.KARAKEEP_API_KEY;
 
+const getCustomHeaders = () => {
+  try {
+    return process.env.KARAKEEP_CUSTOM_HEADERS
+      ? JSON.parse(process.env.KARAKEEP_CUSTOM_HEADERS)
+      : {};
+  } catch (e) {
+    console.error("Failed to parse KARAKEEP_CUSTOM_HEADERS", e);
+    return {};
+  }
+};
+
 export const karakeepClient = createKarakeepClient({
   baseUrl: `${addr}/api/v1`,
   headers: {
+    ...getCustomHeaders(),
     "Content-Type": "application/json",
     authorization: `Bearer ${apiKey}`,
   },
-- 
cgit v1.2.3-70-g09d2