Skip to content

Say at startup which HTTP-only flags a stdio run ignores, and refuse the ones it cannot ignore safely - #1090

Merged
jmrplens merged 6 commits into
issue-951c-stateful-sessionsfrom
issue-1045-stdio-http-flags
Sep 30, 2026
Merged

jmrplens merged 6 commits into
issue-951c-stateful-sessionsfrom
issue-1045-stdio-http-flags

Conversation

@jmrplens

@jmrplens jmrplens commented Sep 30, 2026 •

Copy link
Copy Markdown
Owner

Every flag main registers into httpConfig is parsed on every run, and a stdio run never reads that struct: main hands runWithContext a nil one unless the transport is HTTP, and runStdio builds its configuration from config.Load and the environment alone. So a stdio user who passed --rate-limit-rps=5 to switch the limiter on got no limiter and no message, one who passed --read-only got a server that writes, and one whose client configuration carried --gitlab-url https://gitlab.corp.example with the corporate token in its environment sent that token to https://gitlab.com, the instance stdio falls back to when GITLAB_URL is unset, at startup and before any tool was called. docs/development/documentation-audit-2026-09.md (D8) found the same for --action-timeout and left the warning as a code decision.

What a stdio run does now. Once the transport is explained, it names every flag it was given that lands in httpConfig, each with the variable stdio reads instead where there is one (--rate-limit-rps (on stdio set GITLAB_MCP_RATE_LIMIT_RPS), --max-request-body-bytes (on stdio set GITLAB_MCP_STDIO_MAX_LINE_BYTES), the line ceiling that bounds the same inbound message, --http-addr (stdio has no such setting)), and goes on ignoring them:

  • at WARN when the operator chose stdio, by default, with --transport=stdio or with --http=false;
  • under --transport=auto, a flag stdio has no setting for at all (the listener, the pool, the authentication gate) at INFO on a line of its own, since that command line was written for either transport and the container image's own command carries --http-addr: a warning on every docker run -i session of the published image would teach the reader of that log to skip warnings. A flag stdio has a variable for stays at WARN there, since a setting written once for either transport was plausibly meant for both.

The flags that refuse instead. The condition is what ignoring the value would cost, the rule config.RetiredEnvUses applies to the retired variable names. Ignoring most of these flags costs a setting. Two kinds cost more, and a stdio run given one exits 1 before serving, under --transport=auto as well, with one ERROR line each naming the flag and what to set instead:

  • --read-only or --safe-mode set to true, or an --exclude-tools naming anything: the three settings register row AUT-004 decides together, each withholding part of what the server serves, so ignoring one serves it (set_instead=GITLAB_MCP_READ_ONLY=true, GITLAB_MCP_EXCLUDE_TOOLS=project.delete).
  • a --gitlab-url none of whose instances is the one the stdio run connects to: ignoring it sends GITLAB_TOKEN to an instance the command line did not name, which is the reason HTTP mode refuses to choose an instance on a caller's behalf, applied here to the operator (set_instead=GITLAB_URL). The comparison is in the canonical form the HTTP allow-list uses, so a --gitlab-url naming that same instance however it is spelled is only named, and the instance stdio connects to is resolved the way config.Load resolves it.

A value that asks for nothing (--read-only=false, an --exclude-tools of blanks, an empty --gitlab-url) costs nothing when ignored and is only named. A refused flag is refused even when its variable already asks for the same thing, as a retired name is beside its replacement, and the refusal line is worded to hold then too: the flag has no effect here, so set the variable and remove the flag.

How the set is kept. httpOnlyFlags in cmd/server/http_only_flags.go names each flag with its stdio variable and, for the four above, the refusal. TestHTTPOnlyFlags_AreTheFlagsBoundToHTTPConfig reads the package's source for every flag.XxxVar(&hcfg.field, ...) and holds the table to it in both directions. TestHTTPOnlyFlags_NameVariablesStdioReads sets each named variable to two values and requires what stdio reads at startup, config.Load and the transport's own limits, to differ. TestHTTPOnlyFlags_NameEachFlagsOwnVariable holds each variable to the flag it is named for, through the HTTP environment overlay: set to two values with no flag passed, the one field it moves must be the field the flag is registered into, which a table sending --tier to GITLAB_MCP_TOOL_SURFACE fails (checked by making exactly that edit). --max-request-body-bytes, whose stdio variable HTTP mode has no variable for, is declared with its reason and held to moving nothing. The retired-name report, the transport line and this check run from one function, reportStartupConfiguration, since main was at the limit the maintainability linter accepts.

test/e2e/stdio/http_only_flags_test.go holds the behaviors against the binary: --rate-limit-rps=0.001 --rate-limit-burst=1 named at WARN and still ignored (three tool calls served, no limiter line); the image's --transport auto --http-addr 0.0.0.0:8080 named at INFO with no warning, and a --tool-surface added to it named at WARN; --read-only, --read-only beside GITLAB_MCP_READ_ONLY=true, and --exclude-tools each exiting 1 before serving with nothing on stdout; a --gitlab-url naming another instance exiting 1 with the instance GITLAB_URL names counting that no request reached it; and a --gitlab-url naming the same instance with a trailing slash served and named.

The curated -h says which flags a stdio server reads and which it refuses, and now lists -allow-private-instances and -description-substitutions, which it never did; TestPrintHelp_DocumentsEveryFlag reads the env-backed flags from their table so that cannot recur. The two cmd/server test comments that gave the stdio rate-limit reason as latency, which issue #1045 lists as its own work because #959's layer could not edit cmd/server, now give the one the rest of the tree states: the limiter refuses and never delays, so on stdio it would only refuse its one user's own calls (the same comment in internal/config/config.go was #1042's, which main now carries). Twelve documentation lines that said stdio ignores --rate-limit-rps "without a warning" are corrected, and the CLI and configuration references, the environment reference, the troubleshooting guide and the site's configuration and troubleshooting pages (English and Spanish), the exit-code table, CLAUDE.md and .github/copilot-instructions.md state the rule. internal/tenancy/decisions_allow.go (RTC-001) still says stdio accepts the flag and ignores it, which stays true; changing register text would make this a register change for no gain.

Not a limit. No register row, value, refusal or site changes: the refusal is a startup refusal of the operator's configuration, like the retired-name one, and not a refusal of a caller. make check-tenancy passes unchanged. The validation checklist therefore has nothing to answer: VAL-001 to VAL-009 describe a row there is none of, VAL-010 has no telemetry to carry, VAL-011 is this change (stdio is where it acts), and VAL-012 has no population to protect and no measurement to take.

Verified

Measured on this layer before it was rebased onto main at 5da9699, where main's server card change (#1061) sits in the same file; the two merged without a conflict. At its place in this stack on 50ef2cf, the layer built and vetted, the e2e gitlab, http and stdio packages compiled, the unit suites of cmd/server, internal/tenancy, internal/oauth and cmd/audit_tenancy passed, and make check-tenancy read the same 83 rows and 308 sites as the layer below. The stack now sits on b44ab96, which adds #1083, #1084 and #1085; they change the upstream register, indirect module versions and the site's package pins, none of them a file this stack writes, and every commit of the stack applied unchanged.

  • cmd/server, shuffled: coverage 100.0% of statements; race on the new and neighboring tests; go vet; golangci-lint --build-tags e2e and --build-tags stdioe2e clean.
  • gobco on cmd/server (a staged copy without the non-Linux twins, since gobco cannot instrument the package in place): 2118 of 2160 conditions both ways. The 42 left are the base's 42 at the same code (2082 of 2124 before this change); every condition this change adds, http_only_flags.go whole, is evaluated both ways.
  • gremlins (--workers 2 --timeout-coefficient 20) over cmd/server, scoped to the two files this change writes, at the layer's last commit before the rebase: 367 killed, 4 lived, 25 not covered, 0 timed out. http_only_flags.go has no survivor. All 29 are in main.go, none on a line this change writes, and they are the base's set on the same code shifted by the help text added here.
  • main.go therefore does not meet the gate on its own. Its 11 one-way conditions, 4 lived and 25 not-covered mutants are carried to The condition gate cannot instrument cmd/server: gobco panics on build-constrained duplicates #1017, whose cmd/server half is the package's closing pass, with the list; most of the not-covered ones are arithmetic in constant initializers, the class http_only_flags.go removed by spelling its variables out.
  • test/e2e/stdio, the whole module against the binary built from this tree: pass. test/e2e/gitlab/common and test/e2e/http compile.
  • make check-tenancy, check-dead-consts, check-test-file-names, check-test-subtests, check-test-goroutines, check-doc-tool-names, check-em-dash against both main and the layer below: pass. format_md_tables --check and markdownlint-cli2 on the changed pages: clean.

The top of the stack

This layer was the top of the tenancy stack (#950, the two parts of #951 and this one) when it was written, so it also carries the refresh of the committed artifacts the layers below leave stale, in its own commit; the layers since stacked above it refresh them again at the new top. The README statistics and the testing reference move, since the stack adds tests; the golden snapshots, the llms files, the token footprint, the request inventory, the LobeHub manifest and the site stats were regenerated and came out unchanged, since no layer moves the served surface or a request a handler sends. CLAUDE.md and docs/development/cmd-utilities.md take the text the lower layers proposed: the identity cache and verification ceiling (ADM-005, ADM-014) and the held-call and stateful session ceilings (HLD-011, HLD-010) in the environment table, the HTTP flag table and the OAuth routing section, and the bench_resources held and sessions modes with their make targets.

At the top, with the freshness gates checked rather than deferred: every check of CI's generated-artifacts job passes (check-openplugin, check-stats, check-doc-links, check-plan-untracked and check-em-dash run locally, the rest on the remote runner), as do check-e2e-static, check-tenancy, check-request-inventory and the e2e harness's own tests; the whole unit suite passes (275 packages); golangci-lint with the e2e, httpe2e and stdioe2e tags over cmd/audit_tenancy, cmd/bench_resources, cmd/server, internal/oauth, internal/tenancy, test/e2e/http and test/e2e/stdio reports nothing; the unit suites of those packages pass shuffled twice; test/e2e/http passes (605 tests, the 7 Docker-only proxy and balancer cases skipped) and test/e2e/stdio passes (107 tests), both against the binary built at the top; markdownlint is clean on every page the stack changes.

Decisions I took here

  • --read-only and --safe-mode set to true, an --exclude-tools naming anything, and a --gitlab-url naming no instance stdio connects to refuse a stdio start (exit 1) instead of warning. The issue allows a warning or a refusal; the rule config.RetiredEnvUses already applies to the retired names is what ignoring the value would cost, and nobody reads a stdio server's stderr.
  • A start that still sets the retired bare EXCLUDE_TOOLS refuses as well, by the same rule: ignoring it serves what the operator removed, exactly as ignoring --exclude-tools does. The rule lives in config.protectionNames in internal/config, so a layer of its own higher in this stack makes that change, beside the retired GITLAB_READ_ONLY and GITLAB_SAFE_MODE it already refused.
  • Under --transport=auto a flag stdio has no setting for is named at INFO, not WARN, because the published image's own command passes --http-addr and a warning would fire on every docker run -i session. A flag with a stdio variable stays at WARN there, and the refusals apply under auto too.
  • The refusal is a startup refusal of the operator's configuration, not a caller refusal, so no register row was added and check-tenancy is unchanged.
  • "HTTP-only" means exactly the flags registered into httpConfig, held in both directions by a test that reads the source. --tool-surface, --tier and --tls-cert are also read by --tool-search and --probe, which exit before a transport is chosen.
  • One WARN line lists every ignored flag with its stdio variable, and each refused flag gets an ERROR line of its own. A refused flag is refused even when its variable already asks for the same thing.
  • --gitlab-url is compared in the canonical form the HTTP allow-list uses; an empty value, or one naming the same instance however it is spelled, is only named, and a spelling either side cannot normalize matches nothing and refuses. The instance stdio connects to is resolved in cmd/server the way config.Load resolves it (trim GITLAB_URL, fall back to config.DefaultGitLabURL), held together by TestStdioInstance_IsTheOneConfigLoadResolves, rather than by exporting config's resolver.
  • The stdio variable names in httpOnlyFlags are written as literals, not as config.EnvPrefix plus a name, so gremlins has no unreachable initializer mutants there; a test holds each spelling to a variable config.Load reads.
  • reportRetiredEnvNames, the transport line and this check run from one function, reportStartupConfiguration, in that order, to keep main under the maintainability limit.
  • CLAUDE.md was edited in this layer (the GITLAB_MCP_RATE_LIMIT_RPS row and the paragraph before the HTTP flag table), because the issue is about that text. The orphaned test comment for a TestRateLimit_DefaultsDifferByTransport that does not exist was removed with its stale latency reason.
  • The resolution of D8 in docs/development/documentation-audit-2026-09.md is marked "Resolved by issue 1045" rather than by a release number, which is not known yet.

Not done

  • A stdio run does not start honouring the HTTP flags (writing GITLAB_MCP_READ_ONLY from --read-only, for instance); that would change stdio's configuration model beyond what the issue asks, so it names or refuses them instead.
  • internal/tenancy/decisions_allow.go (RTC-001) still says stdio accepts --rate-limit-rps and ignores it, which stays true; changing register text would make this a register change for no gain.
  • main.go does not meet the house gate on its own: its 11 one-way conditions, 4 lived and 25 not-covered mutants predate this change and are carried to The condition gate cannot instrument cmd/server: gobco panics on build-constrained duplicates #1017's cmd/server half with the list.

Closes #1045.

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry @jmrplens, your pull request is larger than the review limit of 150,000 diff characters

@coderabbitai

coderabbitai Bot commented Sep 30, 2026 •

Copy link
Copy Markdown

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 59 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Repository: jmrplens/gitlab-mcp-server/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: d8c2560f-1c0e-4145-a5b2-f790c70690c5

📥 Commits

Reviewing files that changed from the base of the PR and between fb0a1d1 and 8649b06.

📒 Files selected for processing (27)
  • .github/copilot-instructions.md
  • CLAUDE.md
  • README.md
  • cmd/server/http_only_flags.go
  • cmd/server/http_only_flags_test.go
  • cmd/server/main.go
  • cmd/server/main_test.go
  • docs/concepts/security.md
  • docs/development/cmd-utilities.md
  • docs/development/documentation-audit-2026-09.md
  • docs/development/tenant-policy-spec.md
  • docs/development/testing/testing.md
  • docs/guides/http-server-mode.md
  • docs/guides/troubleshooting.md
  • docs/reference/cli.md
  • docs/reference/configuration.md
  • docs/reference/env.md
  • site/src/content/docs/configuration.mdx
  • site/src/content/docs/es/configuration.mdx
  • site/src/content/docs/es/operations/http-server.mdx
  • site/src/content/docs/es/operations/security.mdx
  • site/src/content/docs/es/operations/troubleshooting.mdx
  • site/src/content/docs/operations/http-server.mdx
  • site/src/content/docs/operations/security.mdx
  • site/src/content/docs/operations/troubleshooting.mdx
  • test/e2e/stdio/http_only_flags_test.go
  • test/e2e/stdio/rate_limit_test.go

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@jmrplens
jmrplens added this pull request to stack #1095 September 30, 2026 10:18
@jmrplens jmrplens added the v3.1.0 Targeted at the 3.1.0 release label Sep 30, 2026
@jmrplens jmrplens added this to the 3.1.0 milestone Sep 30, 2026
@jmrplens jmrplens changed the title issue 1045 stdio http flags Say at startup which HTTP-only flags a stdio run ignores, and refuse the ones it cannot ignore safely Sep 30, 2026
@github-actions github-actions Bot added the transport stdio and HTTP transports, the server process, and the transport e2e modules label Sep 30, 2026
@jmrplens
jmrplens force-pushed the issue-1045-stdio-http-flags branch from 716fb58 to bac52a8 Compare September 30, 2026 12:05
Every flag main registers into httpConfig is parsed on every run, and a
stdio run never reads that struct: main hands runWithContext a nil one
unless the transport is HTTP, and runStdio builds its configuration from
config.Load and the environment alone. So a stdio user who passed
--rate-limit-rps=5 to switch the limiter on got no limiter and no
message, and one who passed --read-only got a server that writes.

A stdio run now says so, once, after the transport is explained: one
WARN line naming each such flag with the variable stdio reads instead
where there is one. Under --transport=auto the same line is written at
INFO, because that command line was written for either transport; the
container image's own command carries --http-addr, and a warning on
every `docker run -i` session would teach the reader of that log to
skip warnings.

--read-only and --safe-mode asking to hold back writes refuse the start
instead, with the variable to set named. They are the two settings
config.RetiredEnvUses refuses a retired spelling of, for the same
reason: ignoring either serves writes on a deployment that asked for
reads, and the stdio servers most likely to carry one are the ones an
MCP client started with nobody reading their stderr. Set to false they
ask for nothing to be held back and are only named.

httpOnlyFlags is held to the registrations into httpConfig by a test
that reads the package's source in both directions, so a flag added to
the HTTP configuration cannot be left out; another test holds each
variable it names to a change in what config.Load returns, so the advice
cannot name a variable stdio does not read. The retired-name report, the
transport line and this check now run from one function, since main was
at the limit the maintainability check accepts. test/e2e/stdio holds all
three behaviours against the binary, the ignored bucket included.

The help's FLAGS section says which flags a stdio server reads, and the
two test comments that gave the stdio rate-limit reason as latency now
give the one the rest of the tree states: a limiter there refuses and
never delays, so it would only refuse its one user's own calls.

Closes #1045.
Twelve places said stdio accepts --rate-limit-rps and ignores it without
a warning, which stopped being true with the startup line the previous
commit adds. They now say stdio ignores the flag and says so at
startup, naming the variable instead.

The CLI reference and the site's configuration page (English and
Spanish) state the rule for the whole HTTP table rather than for one
row: every flag in it but --http is read in HTTP mode only, a stdio run
given one names it at WARN (INFO under --transport=auto), and
--read-only or --safe-mode asking to hold back writes refuses the start
with exit code 1. The --action-timeout row loses "does nothing", the
exit code table names the new refusal, CLAUDE.md states the rule beside
the HTTP flag table, and D8 of the September documentation audit, which
left the warning as a code decision, records how issue 1045 resolved
it.
gremlins reported every `config.EnvPrefix + "..."` in the httpOnlyFlags
initializer, and the two concatenated line constants, as mutants no test
covers: a concatenation in a package-level initializer is folded by the
compiler, so no test can reach the mutated form. Each is now one
literal. TestHTTPOnlyFlags_NameVariablesStdioReads already holds every
variable spelling to one config.Load reads, and the unit and stdio e2e
tests read the lines word for word, so nothing the concatenation
guarded is lost.
…itlab-url

The review of this change found the refusal set chosen by analogy with the
retired-name table rather than by the rule that table states, which is what
ignoring a value would cost. Two flags cost more than a setting when a stdio
run ignores them, and both only warned:

- --exclude-tools names tools the operator asked not to exist, and register
  row AUT-004 decides it together with --read-only and --safe-mode. A stdio
  run given --exclude-tools project.delete logged one line and served
  project.delete.
- --gitlab-url is read in HTTP mode only, and a stdio run connects to the
  instance GITLAB_URL names, https://gitlab.com when it is unset. An MCP
  client configured with --gitlab-url for a self-managed instance and that
  instance's token in its environment sent the token to gitlab.com at
  startup, before any tool was called. HTTP mode refuses to choose an
  instance for a caller for exactly this reason.

Both now refuse the start, under --transport=auto too: --exclude-tools when
it names anything (read with config.ParseCSV, as both transports read it),
and --gitlab-url when none of the instances it names is the one stdio
connects to, compared in the canonical form the HTTP allow-list uses, so a
flag naming that same instance however it is spelled is only reported. The
instance stdio connects to is resolved the way config.Load resolves it, and a
test holds the two together.

The refusal line of the withholding flags now holds when the variable is
already set beside the flag, which is still refused, as a retired name is
beside its replacement: it says the flag has no effect and asks for it to be
removed, rather than that the server would serve what it withholds.

--max-request-body-bytes names GITLAB_MCP_STDIO_MAX_LINE_BYTES, the stdio
ceiling on the same inbound message, instead of saying stdio has no such
setting. The variable test reads what stdio reads at startup, config.Load and
the transport's own limits, and a second test holds each variable to the flag
it is named for through the HTTP environment overlay, which a table sending
--tier to GITLAB_MCP_TOOL_SURFACE would have passed before.

Under --transport=auto only a flag stdio has no setting for at all is named
at INFO; a setting stdio has a variable for stays at WARN, since a command
line written once for either transport plausibly meant it for both.

The curated help lists -allow-private-instances and -description-substitutions,
which it never did, and TestPrintHelp_DocumentsEveryFlag reads the env-backed
flags from their table so that cannot recur. helpEntry matches a line that
starts with the name, since the help's stdio paragraph now names flags.
The stdio rule now refuses a start for --exclude-tools as well as
--read-only and --safe-mode, and for a --gitlab-url naming no instance the
stdio run connects to, and names only the flags stdio has no setting for at
INFO under --transport=auto. The pages that state the rule follow it:

- CLAUDE.md said every flag of the HTTP table lands in httpConfig, which the
  four telemetry rows of that same table contradict; the sentence now leaves
  them out and states the refusals by what ignoring them costs.
- The CLI reference said every flag below -http is read in HTTP mode only,
  which the -tool-search and -probe rows of the same page contradict; it now
  says a server serving HTTP is the only reader, and lists both refusals.
- The configuration reference gained the stdio rule in its HTTP Server Mode
  introduction, the refusals beside the retired-name ones, and a transport
  qualifier on the flags in its loading order.
- The environment reference says which of its flags a stdio run reads.
- The troubleshooting guide and the site's troubleshooting pages (English
  and Spanish) list the two new startup failures with what to set instead,
  and the site's configuration pages state the refusals.
- The -rate-limit-rps row of the CLI reference and the rate-limit row of the
  Copilot instructions say stdio names the flag at startup, as the rest of
  the tree does.
- The documentation audit's D8 resolution records the final rule.

A re-padded troubleshooting row carried an em dash; it is rewritten without.
The four layers below leave the committed artifacts to the top of the
stack. Regenerated here: the README statistics and the testing
reference, which count the tests this stack adds. The golden
snapshots, the llms files, the token footprint, the request
inventory, the LobeHub manifest and the site stats were regenerated
too and came out unchanged, since no layer moves the served surface
or a request a handler sends.

CLAUDE.md and docs/development/cmd-utilities.md take the text the
layers proposed rather than wrote: the identity cache and verification
ceiling of issue 950 (ADM-005, ADM-014) in the environment table, the
flag table and the OAuth routing section; the held-call ceiling
(HLD-011) and the stateful session ceiling (HLD-010) of issue 951 in
the same three places and in the bench_resources line, with its held
and sessions modes and their make targets. The routing section now
counts the nine invariants it lists.
@jmrplens
jmrplens force-pushed the issue-1045-stdio-http-flags branch from bac52a8 to 8649b06 Compare September 30, 2026 13:04
@sonarqubecloud

Copy link
Copy Markdown

@jmrplens
jmrplens merged commit 783f3ef into main Sep 30, 2026
6 checks passed
@jmrplens
jmrplens deleted the issue-1045-stdio-http-flags branch September 30, 2026 15:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

transport stdio and HTTP transports, the server process, and the transport e2e modules v3.1.0 Targeted at the 3.1.0 release

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Warn at startup when a flag only HTTP mode reads is passed to a stdio server

1 participant