Repository navigation
feat(mcp): authenticated HTTP transport for remote serving - #10
Merged
Merged
Conversation
`kg serve` could only be reached as a local stdio pipe. Add first-class, opt-in remote serving over the HTTP transports with zero new dependencies. - `--host` / `--port`: bind address for the HTTP transports (default 127.0.0.1 — localhost only; widening the bind is a deliberate opt-in). - `KGRDBMS_MCP_TOKEN` env var: when set, streamable-http/sse require an `Authorization: Bearer <token>` header. The check is a small pure-ASGI wrapper using only the stdlib (`hmac.compare_digest`) over the uvicorn/starlette already pulled in by the `[mcp]` extra — no new dep, and the token is read from the environment, never a flag. - `--allow-host`: declares the Host header values clients connect by. The MCP transport enables DNS-rebinding protection with a localhost-only allowlist by default, which would 421 every off-localhost client; this rebuilds the allowlist for the real bind (bind host + localhost always allowed; `*` disables checking for proxy-fronted setups). stdio is unchanged: with no flags and no token, behavior is byte-for-byte identical. Auth governs the connection; the invariants + policy gate still governs what a connected client may change. Adds tests for the bearer wrapper and the host allowlist; documents it under "Serving remotely (authenticated)". Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
cunicopia-dev
added a commit
that referenced
this pull request
Jun 27, 2026
Authenticated HTTP transport for remote serving (--host/--port/--allow-host, KGRDBMS_MCP_TOKEN bearer auth; zero new deps; stdio unchanged). See #10. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds first-class, opt-in remote serving for the MCP server. Until now
kg servecould only be reached as a local stdio pipe; now the same engine and the same file can be served to other machines over the HTTP transports — with zero new dependencies.Changes
--host/--port— bind address for the HTTP transports. Default stays127.0.0.1:8000(localhost only); widening the bind is always a deliberate opt-in.KGRDBMS_MCP_TOKEN— when set, thestreamable-http/ssetransports requireAuthorization: Bearer <token>. The check is a ~15-line pure-ASGI wrapper using only the stdlib (hmac.compare_digest) over theuvicorn/starlettethat the[mcp]extra already installs. The token is read from the environment, never a flag, so it stays out of shell history and the process list.--allow-host— declares theHostheader values clients connect by. The MCP transport turns on DNS-rebinding protection with a localhost-only allowlist by default, which would421every off-localhost client; this rebuilds the allowlist for the actual bind (bind host + localhost always allowed;host:*wildcard matches any port;*disables checking for proxy-fronted setups).Philosophy fit
[mcp]already pulls in; the core staysdependencies = [].kg serveis byte-for-byte the same stdio server. HTTP is a--transportchoice.Tests
Adds coverage for the bearer wrapper (401 missing / 401 wrong / pass-through / lifespan passthrough) and the host allowlist (bind+localhost included;
*disables). Full suite green (129 passed).Docs
New README subsection "Serving remotely (authenticated)" with the
kg serve --transport streamable-httprecipe and client config.🤖 Generated with Claude Code