Skip to main content
Glama

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-mcp

What 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

choice

2–255 labelled options (each with an optional description)

the chosen option, a confidence value, and a probability for every option

score

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

noul

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

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-mcp

bunx (Bun)

SUBQ_API_KEY=your-key bunx @devbux/subq-snap-mcp

Global install (npm)

npm install -g @devbux/subq-snap-mcp
SUBQ_API_KEY=your-key subq-snap-mcp

Global install (Bun)

bun add -g @devbux/subq-snap-mcp
SUBQ_API_KEY=your-key subq-snap-mcp

The server starts even when SUBQ_API_KEY is 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-mcp

Cursor / 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

SUBQ_API_KEY

(unset)

Bearer API key for the SubQ API. Required for tool calls; the server still starts without it.

SUBQ_BASE_URL

https://api.subq.ai

Base URL of the SubQ API.

SUBQ_SNAP_MODEL

subq-snap-1.2

Snap model id to request. Can be overridden per call with the tools' optional model argument. Use snap_list_models to see what your key can access.

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

snap_decide

state (string | JSON object | JSON array), questions (map of name → typed question, 1–128), optional images, model

All answers in one call: { model, answers, usage }

snap_choice

state, instructions, options (object: label → description or null, 2–255), optional images, model

One Choice answer under the name answer

snap_score

state, instructions, levels (array of level descriptions, 2–10, ordered low → high), optional images, model

One Score answer under the name answer

snap_noul

state, instructions, optional criteria ({ "true": ..., "false": ... } descriptions), optional images, model

One Noul answer (probability 0..1) under the name answer

snap_list_models

(none)

{ object: "list", data: [{ id, name, object, created, owned_by }] }

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 with 422. 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 server

Project 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 tests

Publishing

Releases are published to npm by the Publish to npm GitHub Action (.github/workflows/publish.yml):

  1. Bump the version in package.json, update CHANGELOG.md, and push.

  2. Create a GitHub Release for the new version tag (or run the workflow manually with workflow_dispatch).

  3. The workflow runs typecheck, tests, and build, then publishes with npm publish --provenance --access public.

Notes:

  • The workflow expects an NPM_TOKEN repository secret (an npm automation token for an account/organisation that owns the @devbux scope) in this repository's settings.

  • Provenance is enabled (id-token: write permission + --provenance), so each published version is linked to its GitHub Actions build.

  • This is a scoped package (@devbux/subq-snap-mcp); publishConfig.access is set to public in package.json so releases are publicly installable.

  • prepublishOnly also runs typecheck, tests, and build for manual publishes.

License

MIT © 2026 devbux

Available Tools

5 tools
snap_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

    A3.8/5.0

    Scored across 5 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables agents to evaluate single records or batches with dynamically authored typed questions, returning structured decisions and probabilities.
      22 PyPI
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables 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
    • A
      license
      A
      quality
      B
      maintenance
      Lets 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.
      6
      219 npm
      MIT