feat: add ability to override parameters using HTTP headers MCP-293 #748

gagik · 2025-11-24T14:15:42Z

This adds header and query param-based overrides.

gagik · 2025-11-24T14:16:22Z

src/transports/base.ts

-    protected async setupServer(): Promise<Server> {
+    protected async setupServer(request?: RequestContext): Promise<Server> {
+        // Apply config overrides from request context (headers and query parameters)
+        let userConfig = applyConfigOverrides({ baseConfig: this.userConfig, request });


should we make this config override opt-in?
Can it be problematic that people who update the MCP server don't release that others can override some other settings now?

Yeah the override should be opt-in using the --allowRequestOverrides flag. Just realised that I did not write this info in the ticket but its further explained in Goal#3 in the scope.

Copilot

Pull request overview

This PR adds the ability to override configuration parameters via HTTP headers and query parameters when using the HTTP transport. Overrides are applied automatically from request context before the createSessionConfig hook runs, with query parameters taking precedence over headers. Each config field defines its override behavior (not-allowed, override, merge, or custom logic).

Key changes:

New config override system with three behaviors: "not-allowed" (security-sensitive fields), "override" (simple replacement), and "merge" (arrays)
Conditional overrides for security flags (readOnly, indexCheck, disableEmbeddingsValidation) using custom logic
Request context (headers/query) passed through transport layer to config application

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/common/config/configOverrides.ts	New module implementing config override extraction and application logic
src/common/config/configUtils.ts	Added override behavior types, parseBoolean preprocessor, and oneWayOverride helper
src/common/config/userConfig.ts	Registered override behaviors for all config fields and added boolean preprocessors
src/transports/base.ts	Modified setupServer to accept RequestContext and apply overrides before createSessionConfig
src/transports/streamableHttp.ts	Extracts headers/query into RequestContext and passes to setupServer
tests/unit/common/config/configOverrides.test.ts	Comprehensive unit tests for override behaviors and edge cases
tests/integration/transports/configOverrides.test.ts	Integration tests verifying overrides work end-to-end via HTTP
tests/integration/transports/createSessionConfig.test.ts	Refactored to use helpers and verify createSessionConfig receives request context
tests/integration/server.test.ts	Updated test to check for insert-many instead of insert-one
package.json	Added --run flag to test script

tests/unit/common/config/configOverrides.test.ts

tests/integration/transports/configOverrides.test.ts

tests/integration/transports/createSessionConfig.test.ts

src/common/config/configOverrides.ts

Co-authored-by: Copilot <[email protected]>

coveralls · 2025-11-24T14:23:43Z

Pull Request Test Coverage Report for Build 19703979104

Details

242 of 251 (96.41%) changed or added relevant lines in 7 files are covered.
36 unchanged lines in 3 files lost coverage.
Overall coverage increased (+0.2%) to 80.415%

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
src/lib.ts	0	1	0.0%
src/common/config/configUtils.ts	48	50	96.0%
src/common/config/configOverrides.ts	112	118	94.92%

Files with Coverage Reduction	New Missed Lines	%
src/tools/mongodb/mongodbTool.ts	5	84.09%
src/common/session.ts	6	85.08%
src/tools/atlas/connect/connectCluster.ts	25	71.56%

Totals
Change from base Build 19701626410:	0.2%
Covered Lines:	6665
Relevant Lines:	8203

💛 - Coveralls

src/common/config/configOverrides.ts

himanshusinghs · 2025-11-24T14:42:07Z

src/transports/base.ts

-    protected async setupServer(): Promise<Server> {
+    protected async setupServer(request?: RequestContext): Promise<Server> {
+        // Apply config overrides from request context (headers and query parameters)
+        let userConfig = applyConfigOverrides({ baseConfig: this.userConfig, request });


Yeah the override should be opt-in using the --allowRequestOverrides flag. Just realised that I did not write this info in the ticket but its further explained in Goal#3 in the scope.

src/transports/base.ts

nirinchev

Haven't looked at the tests yet, but I figured it's better to leave the comments I have so far so you don't wait for the full review.

src/common/config/configOverrides.ts

src/common/config/configUtils.ts

nirinchev · 2025-11-25T08:53:43Z

src/common/config/configUtils.ts

+ * Preprocessor for boolean values that handles string "true"/"false" correctly.
+ * Zod's coerce.boolean() treats any non-empty string as true, which is not what we want.
+ */
+export function parseBoolean(val: unknown): unknown {


This function appears to treat any non-empty string as true too (except false and 0) - is this intentional?

yeah, this was a good balance between making sure old behaviors will work similar way (so if someone has --readonly=yes before, it'd still be true and not suddenly become false. while also making sure intentional setting of the value works too.
This helps us have the same logic for CLI and request parsing/validation. Though open to adjusting if there's concerns here.

I wonder if we should just error out if the string value is different from true/false/1/0? Because based on the same logic, if we have --readonly=no, that would now make the server readonly.

I'm open to this but it does mean this is a breaking change.
in latest v1.2.0 --readOnly no would make the server readOnly
--readOnly false would make the server write-able

Right, the question is if this is intentional - I would say this is more of a bugfix than a breaking change. Additionally, if we throw, it won't be a silent breaking change - we'll give users feedback about what to fix, which I think is a reasonable compromise.

okay apparently this preprocessing only really applies to these headers.
everything else is configured by yargs-parser... so it's about changing settings there

changed logic to be:

if "true" or "false" -> parse into boolean

any other value error with invalid boolean

note: this doesn't affect our CLI passing, this only affects query params. CLI stuff is handled by yargs-parser

nirinchev · 2025-11-25T08:58:58Z

src/common/config/userConfig.ts

        .default(300_000)
-        .describe("Time in milliseconds after which an export is considered expired and eligible for cleanup."),
+        .describe("Time in milliseconds after which an export is considered expired and eligible for cleanup.")
+        .register(configRegistry, { overrideBehavior: "override" }),


This sounds sketchy - can I setup my exports to timeout after a year, then flood the server storage with exports?

Good point. But what if the client wanted a smaller timeout of their export? We can cap the overridable max timeout to the server configured timeout? But yea if it becomes too complex, I am fine leaving it as well.

setting this to onlyLowerThanBaseValueOverride

src/common/config/userConfig.ts

nirinchev · 2025-11-25T09:01:07Z

src/common/config/userConfig.ts

-        .describe("When set to true, disables validation of embeddings dimensions."),
+        .describe("When set to true, disables validation of embeddings dimensions.")
+        .register(configRegistry, {
+            overrideBehavior: oneWayOverride(false),


Wonder why this is oneWayOverride?

if validation is enabled (i.e. disableValidation is false) then we would not want a client to disable validation and let the MCP server insert arbitrary data in a vector search field (which apparently breaks vector search)

By the way, I find the double negative to be confusing so it'd be great to rename this in general

nirinchev · 2025-11-25T09:01:49Z

src/common/config/userConfig.ts

        .default([])
-        .describe("An array of preview features that are enabled."),
+        .describe("An array of preview features that are enabled.")
+        .register(configRegistry, { overrideBehavior: "merge" }),


Why are we merging these arrays?

This is just following the scope document. Agree some can be adjusted cc: @himanshusinghs

This is based on understanding that individual clients might want to enable specific preview features for their session.

I think this should either be override (so you can remove features if needed) or not-allowed (so no experimental features can be enabled)

changed this to be only subset of base value (so you can disable preview features but not add any new ones)

src/transports/base.ts

…gagik/query-header-override

gagik · 2025-11-26T11:35:12Z

package.json

    "generate:arguments": "tsx scripts/generateArguments.ts",
    "pretest": "pnpm run build",
-    "test": "vitest --project eslint-rules --project unit-and-integration --coverage",
+    "test": "vitest --project eslint-rules --project unit-and-integration --coverage --run",


drive-by: makes it easier to for LLMs to run this... we can have test:watch if needed

himanshusinghs

I thought I submitted my review but I forgot to click the button. Overall its perfect 🚀 I left only one small thing to consider.

himanshusinghs · 2025-11-26T15:33:13Z

src/common/config/configOverrides.ts

+        throw new Error(`Invalid config key: ${key}`);
+    }
+
+    return fieldSchema.safeParse(value).data;


@gagik the safeparse would silently insert undefined when value is incorrect here

that seems fine right?

ah, right we could error in way which is more useful

yea I think we should error out instead because otherwise we might be overriding with potentially wrong values.

gagik added 3 commits November 24, 2025 14:46

feat: add ability to override parameters using HTTP headers MCP-293

0f2a594

chore: use custom overrides

132876e

add a common one way override function

f600d2a

gagik requested a review from a team as a code owner November 24, 2025 14:15

Copilot AI review requested due to automatic review settings November 24, 2025 14:15

gagik commented Nov 24, 2025

View reviewed changes

Copilot AI reviewed Nov 24, 2025

View reviewed changes

fix typo

1a3aab2

Co-authored-by: Copilot <[email protected]>

addaleax approved these changes Nov 24, 2025

View reviewed changes

src/common/config/configOverrides.ts Show resolved Hide resolved

himanshusinghs reviewed Nov 24, 2025

View reviewed changes

gagik added 7 commits November 24, 2025 16:40

chore: fix lint

3bce26e

chore: cleanup helper

c57dea4

chore: auto-replace

c21a707

chore: add allowRequestOverrides

82f38d0

chore: fix defaults

94b7863

chore: add boolean parsing edge cases

1b284e9

chore: run generate

b094b83

nirinchev reviewed Nov 25, 2025

View reviewed changes

gagik added 8 commits November 25, 2025 11:24

chore: remove override value print, add erroring when disabled, cleanup

acb1eba

cleanup parse boolean

83af6bc

feat: enforce secret overrides only from headers

24e8e92

chore: add conditional subset and lower than cases

386be02

chore: exporttimeout should only be lower than base

e6ab659

chore: fix tests

e752751

Merge branch 'main' of github.com:mongodb-js/mongodb-mcp-server into …

389eabd

…gagik/query-header-override

chore: adjust override behavior

d2731d8

gagik force-pushed the gagik/query-header-override branch from baf9bbe to d2731d8 Compare November 25, 2025 18:11

gagik added 2 commits November 25, 2025 19:15

chore: only error if there exist overrides

d11ec6b

Merge branch 'main' of github.com:mongodb-js/mongodb-mcp-server into …

bd93e3d

…gagik/query-header-override

gagik commented Nov 26, 2025

View reviewed changes

gagik added 2 commits November 26, 2025 13:25

chore: post-merge adjustments

dbacbda

chore: fix expeced defaults

3168bd5

gagik merged commit 3a21cd8 into main Nov 26, 2025
31 of 39 checks passed

gagik deleted the gagik/query-header-override branch November 26, 2025 15:24

himanshusinghs reviewed Nov 26, 2025

View reviewed changes

feat: add ability to override parameters using HTTP headers MCP-293 #748

feat: add ability to override parameters using HTTP headers MCP-293 #748

Uh oh!

Conversation

gagik commented Nov 24, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coveralls commented Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Test Coverage Report for Build 19703979104

Details

💛 - Coveralls

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

nirinchev left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gagik Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gagik Nov 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gagik Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

coveralls commented Nov 24, 2025 •

edited

Loading

gagik Nov 25, 2025 •

edited

Loading

gagik Nov 26, 2025 •

edited

Loading

gagik Nov 25, 2025 •

edited

Loading