@mateusz-klatt/snapper-mcp
v0.16.0
Published
Lightweight stdio-to-HTTP MCP bridge from Claude Desktop / Claude Code to Snapper /api/mcp, with a `watch` subcommand that streams live signal + order events as JSONL via the /api/auth/ws_token endpoint.
Maintainers
Readme
@mateusz-klatt/snapper-mcp
Lightweight stdio-to-HTTP Model Context Protocol bridge. Spawns as a
subprocess, speaks MCP over stdio to Claude Desktop / Claude Code, and
proxies every request to a Snapper backend's /api/mcp endpoint with
Bearer-token auth.
What is this
Snapper is a multi-tenant trading platform. Its backend exposes MCP at
/api/mcp, guarded by Bearer-JWT auth, feature flag, and per-principal
rate limiting. MCP hosts (Claude Desktop, Claude Code) speak MCP over
stdio — they spawn a subprocess and exchange JSON-RPC frames over
stdin/stdout. @mateusz-klatt/snapper-mcp is the stdio ⇄ HTTP bridge that
makes that conversation work.
It is a thin TypeScript bridge using Node's built-in fetch, plus
@modelcontextprotocol/sdk for MCP framing. No OAuth, no telemetry.
Standalone hosts (Claude Desktop, systemd, plain CLI) can provide
credentials through CLI flags, a hardened --config JSON file, or
environment variables. Claude Code plugin installs write a
0600-mode env.json into the per-plugin ${CLAUDE_PLUGIN_DATA}
directory at proxy startup so the skill-armed monitor process can
read its credentials via --config=PATH; the file is owned by the
plugin's data dir and is overwritten atomically on every proxy
startup.
Install
Three install paths, in recommended order. All three end at the same runtime — pick whichever matches your MCP host.
Option 1 — Claude Code plugin (recommended)
In any Claude Code session:
/plugin marketplace add mateusz-klatt/snapper-mcp
/plugin install snapper-mcp@mateusz-klatt-snapper-mcpClaude Code prompts for two values:
- Snapper API URL — your backend's
/api/mcpendpoint. - Access token — paste from Snapper's AI Integration page (the config-snippet generator). The same token authenticates both the proxy MCP server and the watch monitor.
Plugin changes installed mid-session need /reload-plugins (or a
Claude Code restart) before the MCP server starts. After reloading,
/mcp list should show the snapper server connected.
The plugin manifest threads both credentials (SNAPPER_BASE_URL,
SNAPPER_ACCESS_TOKEN) into the proxy MCP subprocess as env vars via
${user_config.KEY} interpolation. The proxy then writes a
0600-mode env.json snapshot into ${CLAUDE_PLUGIN_DATA} at
startup so the skill-armed watch monitor can read the same values
via --config="${CLAUDE_PLUGIN_DATA}/env.json". The manifest marks the token
as sensitive: true; the host controls storage of its user configuration.
The bridge's own credential copy is the protected env.json described above.
Option 2 — Claude Desktop manual config
Add to your Claude Desktop config
(~/Library/Application Support/Claude/claude_desktop_config.json on
macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):
{
"mcpServers": {
"snapper": {
"command": "npx",
"args": ["-y", "@mateusz-klatt/snapper-mcp"],
"env": {
"SNAPPER_BASE_URL": "https://your-snapper-instance.example.com/api/mcp",
"SNAPPER_ACCESS_TOKEN": "<generated via Snapper UI: AI Integration>"
}
}
}
}Restart Claude Desktop; the Snapper server shows up in the MCP Servers settings panel.
Option 2b — Multi-CLI installer (snapper-mcp integrate)
Configure MCP tool access and interactive-only session wake across any of the
supported coding CLIs (claude, codex, copilot, antigravity, kimi,
grok, cursor, or all):
npm install -g @mateusz-klatt/snapper-mcp
SNAPPER_BASE_URL="https://snapper.example.com/api/mcp" \
SNAPPER_ACCESS_TOKEN="<delegate-jwt>" \
snapper-mcp integrate all
# Headless / container MCP wiring without interactive wake hooks:
snapper-mcp integrate all --no-wake --config /path/to/config.json
# Inspect configured CLIs and credential validity offline:
snapper-mcp doctor
# Cleanly remove Snapper entries and restore prior user config files:
snapper-mcp integrate --remove allCredentials are stored in a mode-0600 JSON file inside the user's private
snapper-mcp state directory (or read from --config PATH) and are never
embedded into CLI hook commands or process arguments. On Windows, POSIX mode
bits do not enforce NTFS ACLs; keep the credential file under the default
%APPDATA%\snapper-mcp\config.json path inside the user profile or verify
NTFS read permissions are restricted to the current user when passing a custom
--config PATH.
For claude, snapper-mcp integrate claude writes a local plugin bundle under
the snapper-mcp state directory and registers snapper@snapper-local in
Claude Code's user configuration (~/.claude/settings.json and
~/.claude/plugins/). All client-facing snapper-mcp watch --client <cli>
modes default to --actionable-only and emit fixed, content-free attention
notices rather than raw backend frame payloads unless --all-frames is
explicitly passed. Interactive wake hooks verify terminal attachment and client
argument grammar before arming so non-interactive print runs (-p, --print,
codex exec) never emit extra lines or continuation turns.
Option 3 — Direct CLI / custom hosts
SNAPPER_BASE_URL="..." SNAPPER_ACCESS_TOKEN="..." \
npx -y @mateusz-klatt/snapper-mcp
npm install -g @mateusz-klatt/snapper-mcp
SNAPPER_BASE_URL="..." SNAPPER_ACCESS_TOKEN="..." snapper-mcpRequires Node 26+ (uses Node's built-in fetch, AbortController,
and ESM top-level await). CI validates the declared minimum
(Node 26) across Ubuntu / macOS / Windows.
Configuration
Two environment variables are the common MCP-host configuration shape:
| Variable | Required? | Purpose |
| --- | --- | --- |
| SNAPPER_BASE_URL | yes | URL of Snapper's /api/mcp endpoint. |
| SNAPPER_ACCESS_TOKEN | yes | Long-lived AI delegate JWT for Bearer auth (generated in Snapper UI). The same token authenticates both the proxy MCP server and the watch monitor. |
See .env.example for placeholder values.
Direct CLI runs also accept --base-url, --access-token, and
--config=PATH. Resolution order is CLI flags, then a JSON config
file, then environment variables. Config files can contain the same
top-level SNAPPER_BASE_URL / SNAPPER_ACCESS_TOKEN keys shown
above; on POSIX systems the bridge refuses world-writable files and
warns when the file is group- or world-readable.
Multi-profile support
Run multiple Snapper instances (prod + staging, prod + local dev) from one bridge install. Select a profile at spawn time:
SNAPPER_PROFILE=prod snapper-mcp
# or
snapper-mcp --profile=prodWhen a profile is selected, the bridge reads
SNAPPER_PROFILE_<UPPER>_BASE_URL and
SNAPPER_PROFILE_<UPPER>_ACCESS_TOKEN instead of the bare top-level
vars (hard isolation — no accidental cross-profile fallback). Profile
names match ^[a-z0-9]{1,32}$. CLI flag wins over env var.
CLI --base-url / --access-token flags still override the selected
profile; otherwise config/env lookup is profile-scoped.
The --config JSON file may carry a profiles block:
{
"profiles": {
"prod": { "SNAPPER_BASE_URL": "https://snapper.example.com/api/mcp", "SNAPPER_ACCESS_TOKEN": "..." },
"staging": { "SNAPPER_BASE_URL": "https://staging.example.com/api/mcp", "SNAPPER_ACCESS_TOKEN": "..." }
}
}Verify a profile offline before spawning the bridge:
snapper-mcp check --profile=prodGenerating tokens
Snapper's AI Integration screen creates delegates and generates their configuration snippets.
Each delegate emits a single long-lived (~3-month / 90-day) access JWT. Paste
the value into SNAPPER_ACCESS_TOKEN; the same token powers both the
proxy MCP server and the optional push-wakeup monitor.
Each delegate has configurable caps: per-instrument quantity,
max open orders, rolling 24h USD notional, and 60-second cancel rate.
Tokens are bound to the delegate's permissions + wallet scope; revoke
the delegate in-place via POST /api/ai-delegates/{id}/deactivate to
revoke the backend token inventory and evict verify caches via
admin.user_deactivated.
Logging
All bridge logs go to stderr exclusively. Stdout is reserved for MCP JSON-RPC frames — any stray write there corrupts the protocol stream and Claude Desktop disconnects.
Verbosity knob: set SNAPPER_MCP_LOG_LEVEL=debug for transport-level
diagnostics (URL, HTTP status, error_code). Valid levels:
debug / info (default) / warn / error. Timestamps in the log
prefix: SNAPPER_MCP_LOG_TIMESTAMPS=1.
For structured-log pipelines, set SNAPPER_MCP_LOG_FORMAT=json to
switch every stderr line to a single-line JSON object:
{"t":"2026-05-02T16:00:00.000Z","lvl":"info","prefix":"bridge","msg":"connected","rest":[{"req":42}]}The t field is always present in JSON mode regardless of
SNAPPER_MCP_LOG_TIMESTAMPS. Pipe through jq for filtering:
SNAPPER_MCP_LOG_FORMAT=json snapper-mcp 2>bridge.log
# In a separate terminal, inspect stderr without mixing in MCP stdout:
jq 'select(.lvl=="error")' bridge.logError instances in the rest arguments serialise as {name, message,
stack}; circular objects fall back to String(value) rather than
throwing.
Authentication
On every outbound HTTP request, the bridge injects
Authorization: Bearer ${SNAPPER_ACCESS_TOKEN} while preserving any
Accept / Content-Type / other headers the SDK set.
On 401 the bridge writes a single-line stderr message — once per session — and propagates the 401 response to the MCP host. The host surfaces the auth error as a protocol error; the operator recreates the AI delegate in Snapper to recover.
Watch subcommand
snapper-mcp watch opens a long-lived WebSocket session against
Snapper's /api/ws endpoint and writes one JSONL frame per line to
stdout. A Claude Code plugin monitor (or any host that can read a
subprocess's stdout) consumes the JSONL stream as push-style wakeup.
snapper-mcp watch --topic signals. --topic orders.events.Default subscription: signals., orders.events., ai_reviews., and
ai_research. if no --topic is given. Each prefix MUST end with . to
address a topic family root. The ai_reviews. family carries review-request
and decision-ack frames, while ai_research. carries committed research-round
wakes. A monitoring host can therefore wake its consumer when either kind of
work needs attention.
The watch session mints a one-shot WebSocket token via
POST /api/auth/ws_token using the same SNAPPER_ACCESS_TOKEN
configured for the proxy.
Check subcommand
snapper-mcp check runs an offline diagnostic on the configured
access token + base URL — no network. Useful for validating the
contents of SNAPPER_ACCESS_TOKEN (sub, role, expiry, and any
scope/scopes claim present) without burning the token on a failed
bridge-up. This is an offline decode only; server-side signature,
inventory revocation, wallet scope, and permission checks still happen
on the Snapper backend.
snapper-mcp check
# base URL: https://snapper.example.com/api/mcp/
# access token:
# alg: HS256
# sub: ai-claudedesktop-a1b2c3
# role: ai_delegate
# exp: 2026-08-01T00:00:00.000Z (in 90.5d)
# status: validExit codes:
0— token decoded, base URL parsed, expiry OK.1— env validation failed (missing or malformed inputs).2— token decoded but is already expired or has noexpclaim.
The same --config=PATH, --access-token, and --base-url flags
the proxy + watch subcommands accept also work for check.
Arming the monitor: the wake skill
Installing the plugin starts no background process. Run /wake in the
session that should answer review requests: the manifest declares the
monitor with when: "on-skill-invoke:snapper-mcp:wake", so the host
arms it in response to that invocation. A session that never runs
/wake never connects, so several open sessions do not compete for the
same request or burn tokens waiting. The monitor is not restored when a
session resumes — run /wake again to re-arm it.
Note the qualified skill name in that trigger. The host matches
when against on-skill-invoke:<plugin name>:<skill>; a bare
on-skill-invoke:wake never matches and the monitor silently never
arms. The skill verifies the monitor started and arms it itself if the
host did not, so the plugin still works where the trigger is unsupported.
Credentials come from the --config=PATH JSON file the proxy MCP server
seeds into ${CLAUDE_PLUGIN_DATA}/env.json at startup, so both
processes share one SNAPPER_ACCESS_TOKEN. Because the host expands
${CLAUDE_PLUGIN_DATA} itself, the monitor always reads this plugin's
own data directory.
Development
See CONTRIBUTING.md for the dev workflow
(npm install, npm test, npm run build).
License
Apache License, Version 2.0. See NOTICE for attribution. Third-party dependencies retain their own licenses.
Revisions through the last-mit tag, including previously published npm versions,
were released under MIT. Subsequent original work is licensed under Apache-2.0;
earlier MIT grants remain valid.
