subq-snap-mcp
Summary: This MCP server exposes SubQ's Snap decision model as typed tools that return structured, probabilistic answers (never prose) about a state you describe.
Ask multiple typed questions in one call (
snap_decide): up to 128 questions of typechoice,score, and/ornoul, all evaluated against the same state and images.Pick one of 2–255 labelled options (
snap_choice): returns the chosen option, a confidence value, and a probability for every option.Rate a state on an ordered 2–10 level scale (
snap_score): returns a probability-weighted score (can fall between levels), the level legend, per-level probabilities, and confidence.Get a calibrated yes/no probability (
snap_noul): returns a 0..1 probability that a proposition is true, with optional true/false criteria.Describe the state as text or structured JSON (object or array), and pass structured JSON for instructions and criteria too.
Attach up to 4 images (PNG/JPEG/WebP, base64, ≤4 MiB each / 8 MiB total) that every question sees alongside the state.
List available models (
snap_list_models) for your API key, and override the model per call (defaultsubq-snap-1.2).Use it for decide-don't-chat steps like routing, triage, moderation, risk scoring, and prioritisation inside agent workflows.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@subq-snap-mcp Choose the best category for this ticket: billing, technical, or account."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
subq-snap-mcp
A standard Model Context Protocol (MCP)
server that exposes SubQ's Snap decision model as typed tools —
publishable to npm and runnable anywhere with npx or bunx.
npx -y @devbux/subq-snap-mcpWhat is Snap?
Snap is SubQ's decision model (currently subq-snap-1.2). It never
generates prose. Instead, you give it:
a
state— a situation described as text or structured JSON,up to 4 images to evaluate alongside the state, and
a set of typed questions about that state,
and Snap returns typed answers with probabilities:
Question type | You define | Snap returns |
| 2–255 labelled options (each with an optional description) | the chosen option, a confidence value, and a probability for every option |
| an ordered scale of 2–10 level descriptions | a probability-weighted score (it can fall between levels), the level legend, confidence, and per-level probabilities |
| a proposition (optionally with true/false descriptions) | a probability (0..1) that the proposition is true |
Because the output is structured and probabilistic rather than free text, Snap is well suited to routing, triage, moderation, risk scoring, prioritisation, and any other "decide, don't chat" step inside an agent workflow. One call can ask up to 128 questions, and every question sees the same state and every image.
Scope: this server wraps SubQ's Decisions API and Models API. The
separate subq-preview chat model (Chat Completions / Responses APIs,
structured outputs, function calling) is not a decision model and is out
of scope here.
Related MCP server: Jev MCP Server
Requirements
Node.js >= 18 (or Bun) to run the server.
A SubQ API key (see Getting an API key).
Install & run
The server speaks MCP over stdio, so you normally don't run it by hand — your MCP client launches it. The commands below are how clients (or you, for a quick smoke test) start it.
npx (Node)
SUBQ_API_KEY=your-key npx -y @devbux/subq-snap-mcpbunx (Bun)
SUBQ_API_KEY=your-key bunx @devbux/subq-snap-mcpGlobal install (npm)
npm install -g @devbux/subq-snap-mcp
SUBQ_API_KEY=your-key subq-snap-mcpGlobal install (Bun)
bun add -g @devbux/subq-snap-mcp
SUBQ_API_KEY=your-key subq-snap-mcpThe server starts even when
SUBQ_API_KEYis not set, so clients can still list its tools; each tool call then returns a clear error naming the missing variable instead of crashing.
Getting an API key
Create an API key in your SubQ account (see docs.subq.ai),
then expose it to the server as the SUBQ_API_KEY environment variable.
Never commit your key to source control.
MCP client configuration
Generic (mcpServers JSON)
Most MCP clients (Claude Desktop, and many others) accept a configuration
like this — see also examples/mcp-config.json:
{
"mcpServers": {
"subq": {
"command": "npx",
"args": ["-y", "@devbux/subq-snap-mcp"],
"env": {
"SUBQ_API_KEY": "YOUR_SUBQ_API_KEY"
}
}
}
}Using Bun instead:
{
"mcpServers": {
"subq": {
"command": "bunx",
"args": ["@devbux/subq-snap-mcp"],
"env": {
"SUBQ_API_KEY": "YOUR_SUBQ_API_KEY"
}
}
}
}Claude Code
claude mcp add subq \
-e SUBQ_API_KEY=YOUR_SUBQ_API_KEY \
-- npx -y @devbux/subq-snap-mcpCursor / VS Code
Cursor and VS Code use the same mcpServers JSON shape above (Cursor:
.cursor/mcp.json or Settings → MCP; VS Code: .vscode/mcp.json uses a
top-level "servers" key with the same per-server fields). Paste the generic
config and replace the placeholder key.
Configuration
Environment variable | Default | Description |
| (unset) | Bearer API key for the SubQ API. Required for tool calls; the server still starts without it. |
|
| Base URL of the SubQ API. |
|
| Snap model id to request. Can be overridden per call with the tools' optional |
Tools
All tools return the SubQ API response as JSON text content. Errors (missing
API key, HTTP 400/401/402/403/422/429/5xx, network failures, timeouts) are
returned as MCP tool errors (isError) with a clear message that includes
the HTTP status and the API's own error detail — never your API key.
Tool | Inputs | Output |
|
| All answers in one call: |
|
| One Choice answer under the name |
|
| One Score answer under the name |
|
| One Noul answer (probability 0..1) under the name |
| (none) |
|
Question shapes for snap_decide
{
"type": "choice",
"instructions": "Which team should own this chat?",
"criteria": { "nurse_line": "Needs a nurse today", "front_desk": null }
}{
"type": "score",
"instructions": "How soon should someone respond?",
"criteria": ["Within a week", "Within a day", "Within an hour"]
}{
"type": "noul",
"instructions": "Should a nurse see this chat first?"
// "criteria" is optional for noul and omitted when not provided
}instructions and criteria accept structured JSON (objects/arrays) as
well as strings, so a criterion can carry the data it is judged against.
Images
Any decision tool accepts an optional images array. Each image is an
object with a mediaType (image/png, image/jpeg, or image/webp) and
the file bytes as one line of base64 (no data: prefix — URLs and
data: URLs are rejected by the API). Every question in the request sees
every image, alongside the state.
{
"state": "The number row stopped working.",
"images": [{ "mediaType": "image/jpeg", "base64": "<base64 of the photo>" }],
"questions": {
"shows_keyboard": {
"type": "noul",
"instructions": "Does the photo show a keyboard?"
}
}
}Limits from the SubQ docs:
At most 4 images per request; each at most 4 MiB decoded, and 8 MiB decoded in total. The request body can be up to 13 MiB.
The image bytes must match the declared
mediaType, or the API fails the request with422. This server checks the count, the base64 shape, and the decoded sizes before sending, so those mistakes come back as clear local errors.Each image uses 66 to about 1,600 input tokens (not the base64 text), set by resolution rather than file size. Downscale anything above about 1.6 megapixels to cut the cost. Image tokens are counted toward the model's 384K-token context window together with the request text.
Video is not supported; sample up to 4 frames and send them as images.
Note: SubQ stores decisions together with their images, under SubQ's data-retention policy.
Worked example
An employee reports a broken keyboard and attaches a photo. In one
snap_decide call you can check the photo, classify the device, and grade
its wear:
Request (tool snap_decide):
{
"state": "The number row stopped working.",
"images": [{ "mediaType": "image/jpeg", "base64": "<base64 of the photo>" }],
"questions": {
"shows_keyboard": {
"type": "noul",
"instructions": "Does the photo show a keyboard?",
"criteria": {
"true": "A keyboard is the main object",
"false": "No keyboard is visible"
}
},
"layout": {
"type": "choice",
"instructions": "Which keyboard layout is in the photo?",
"criteria": {
"full_size": "Desktop keyboard with a numeric keypad",
"tenkeyless": "Desktop keyboard with no numeric keypad",
"laptop": "Built into a laptop",
"not_a_keyboard": null
}
},
"wear": {
"type": "score",
"instructions": "How worn does the keyboard look?",
"criteria": ["Looks new", "Everyday wear", "Replace it"]
}
}
}Response (shape; exact values come from the live model):
{
"model": "subq-snap-1.2",
"answers": {
"shows_keyboard": { "type": "noul", "noul": 0.98 },
"layout": {
"type": "choice",
"choice": "tenkeyless",
"probabilities": { "full_size": 0.04, "tenkeyless": 0.9, "laptop": 0.05, "not_a_keyboard": 0.01 },
"confidence": 0.9
},
"wear": {
"type": "score",
"score": 1.35,
"legend": { "0": "Looks new", "1": "Everyday wear", "2": "Replace it" },
"probabilities": { "0": 0.15, "1": 0.55, "2": 0.3 },
"confidence": 0.72
}
},
"usage": { "input_tokens": 210, "output_tokens": 0 }
}Pricing note: you pay only for input tokens (output_tokens is always 0);
Snap is $0.04 per million input tokens at the time of writing.
Development
git clone https://github.com/devbux/subq-snap-mcp.git
cd subq-snap-mcp
npm install
npm run dev # run the server from source with tsx (stdio)
npm run typecheck # tsc --noEmit
npm test # vitest (fake fetch — no live network calls)
npm run build # bundle to dist/index.js with tsup
npm start # run the built serverProject layout:
src/
index.ts stdio bootstrap
server.ts MCP server + the five snap_* tools (zod-validated)
config.ts environment parsing (SUBQ_*)
snap/
client.ts typed SnapClient for POST /v1/systemone and GET /v1/models
types.ts request/response types for the SubQ API
test/
client.test.ts SnapClient + config unit testsPublishing
Releases are published to npm by the Publish to npm GitHub Action
(.github/workflows/publish.yml):
Bump the version in
package.json, updateCHANGELOG.md, and push.Create a GitHub Release for the new version tag (or run the workflow manually with
workflow_dispatch).The workflow runs typecheck, tests, and build, then publishes with
npm publish --provenance --access public.
Notes:
The workflow expects an
NPM_TOKENrepository secret (an npm automation token for an account/organisation that owns the@devbuxscope) in this repository's settings.Provenance is enabled (
id-token: writepermission +--provenance), so each published version is linked to its GitHub Actions build.This is a scoped package (
@devbux/subq-snap-mcp);publishConfig.accessis set topublicinpackage.jsonso releases are publicly installable.prepublishOnlyalso runs typecheck, tests, and build for manual publishes.
License
MIT © 2026 devbux
Available Tools
5 toolssnap_choiceSnap: choice questionA
Ask SubQ's Snap decision model a single Choice question: pick one of 2-255 labelled options for a state. Returns the chosen option, a confidence value, and a probability for every option, under the question name "answer".
Inputs: state (required), options (required), instructions (required), model, +1 more.
snap_decideSnap: decide (typed questions over a state)A
Ask SubQ's Snap decision model one or more typed questions (choice, score and/or noul) about a state in a single call. Returns typed answers with probabilities. The state may be text or structured JSON, and up to 4 images may accompany it; every question sees the state and every image.
Inputs: state (required), questions (required), model, images.
snap_list_modelsSnap: list available modelsA
List the model IDs available to the configured SubQ API key (GET /v1/models, OpenAI-compatible shape). Use a returned id with the endpoint that supports that model; the Decisions tools in this server need a decision model such as subq-snap-1.2.
Inputs: no named parameters.
snap_noulSnap: noul question (yes/no probability)A
Ask SubQ's Snap decision model a single Noul question: is a proposition about a state true? Returns a calibrated probability (0..1) under the question name "answer".
Inputs: state (required), instructions (required), model, images, +1 more.
snap_scoreSnap: score questionA
Ask SubQ's Snap decision model a single Score question: rate a state on an ordered scale of 2-10 levels you define. Returns a probability-weighted score (it can fall between levels), the level legend, per-level probabilities, and a confidence value, under the question name "answer".
Inputs: state (required), levels (required), instructions (required), model, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
snap_decide is a batch superset of snap_choice, snap_score, and snap_noul, so for any single-question request two tools are valid selections. The descriptions do clarify the split (batch vs. single typed question) and the three single-question tools are distinct from each other, but the redundancy creates a real selection decision the agent must reason through each call.
All tools share a clean 'snap_' prefix and snake_case, so the set reads as one family. The only wrinkle is that snap_decide/snap_list_models use verbs while snap_choice/snap_score/snap_noul are named after question types rather than actions, a minor convention mix.
Five tools is well-matched to a focused decision-inference API: one per question type, one batch entry point, and one discovery tool. Nothing feels padded and nothing essential is obviously absent.
The surface covers all three question types, a combined multi-question call, and model discovery, which is solid lifecycle coverage for a stateless inference API. Minor gaps: no model-detail/usage or credential-validation tool, and it is unclear how a caller passes a listed model ID into the decision tools, which may be a dead end after snap_list_models.
Maintenance
Related MCP Connectors
Typed AI decisions for agents: classify, route, screen evidence, score and batch-label text.
Calibrated judgments for text: yes/no probabilities, picks from your options, or scores.
Deterministic contextual decision arbitration and action routing for autonomous software. Takes current state, context, or intent plus caller-supplied candidate actions, state transitions, routes, refusals, escalations, tools, or models and returns a deterministic ordered candidate field. Also provides persistent machine representations for memory, retrieval, indexing, and downstream coherence measurement.
Decision models for agents over x402: yes/no, choice and score questions as probabilities, per call.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables agents to evaluate single records or batches with dynamically authored typed questions, returning structured decisions and probabilities.22 PyPIMIT
- AlicenseAqualityBmaintenanceEnables MCP clients to classify, score, and evaluate content with structured typed decisions via a single generic tool.117 npm2MIT
- AlicenseNot gradedqualityAmaintenanceEnables agents and services to ask small decision models typed questions about text, JSON, images, or video, returning labels, scores, or yes/no answers over MCP tools or a Jev-compatible HTTP API.Apache 2.0
- AlicenseAqualityBmaintenanceLets MCP clients ask typed questions — yes/no, choice, or score — about structured state, including images, and receive calibrated probabilities from System One decision models such as TypeSafe Jev and Cloudflare Clef. Supports TypeSafe, OpenRouter, and local providers selectable per request, with input validation and cost reporting.6219 npmMIT