Use Spryng Analysis MCP with a local model

Eyebrow: Analysis connection
Related: Ask your assistant about your Spryng study · How Spryng manages AI risk

What this setup does

Spryng Analysis MCP is a read-only connection. A small open-source package on your computer (spryng-analysis-mcp) gives your assistant the same analysis tools in two ways:

  • Live study (default): the package relays tool calls to your organization's hosted Spryng Analysis endpoint. Authorization, small-group privacy floors, and study permissions stay in Spryng.
  • Downloaded study file (version 0.2.0 and later): the package reads a study export you downloaded from Spryng and answers from that file on your computer, applying the same question-type rules, privacy floors, and redaction locally. Nothing is sent to Spryng. See Work from a downloaded study file.

A local model means the assistant that calls those tools runs a language model on your machine (or on an institution-approved server you control), instead of sending prompts to a cloud model provider. Installing the relay does not choose a model. Spryng's optional built-in language-model features (described in the AI policy) are a separate path and are not covered by this guide.

Eligibility: Included with annual Inquiry, Praxis, Spryng Field Study, and Research Organization plans, when Analysis MCP is enabled for your organization.

Before you start

  1. Confirm your plan and that Analysis MCP setup is available in Spryng (Analysis → Connect your assistant, or Organization settings → Analysis MCP).
  2. Create a personal token (smcpa_…) and copy the Analysis MCP URL ending in /mcp/analysis/rpc/. The token is shown once. Keep it private.
  3. Install Python 3.10 or later and the relay. Prefer pipx or uv, and pin the verified release unless you intentionally upgrade:
pipx install 'spryng-analysis-mcp==0.2.0'
# or: uv tool install 'spryng-analysis-mcp==0.2.0'
command -v spryng-analysis-mcp

Copy the absolute path to the executable. Desktop MCP hosts often do not expand ~ in the command field.

  1. Check PyPI for newer versions before pinning a different release.

Option A — LM Studio

LM Studio can act as an MCP host and run local models. Official documentation: Use MCP Servers. MCP Host support starts with LM Studio 0.3.17.

Install LM Studio and pick a tool-use model

  1. Download LM Studio from the official site and install 0.3.17 or newer.
  2. In the model catalog, filter by the Tool use capability (Model catalog). Choose a size that fits your machine's RAM and GPU memory. Smaller models run with less memory but are often weaker at multi-step tool calls.
  3. Download and load one tool-use model. Leave free memory for the model and for the MCP server process LM Studio will start.

As a starting point: machines with roughly 8–16 GB of system memory usually need a small quantized tool-use model; machines with more memory or a dedicated GPU can try mid-size or larger tool-use models from the catalog. Prefer the Tool use tag over popularity rankings, then try a simple Spryng question.

Add the Spryng Analysis MCP server

  1. In LM Studio, open the Program tab in the right-hand sidebar.
  2. Click Install → Edit mcp.json. Use the in-app editor rather than guessing a file path (docs).
  3. Add a local (stdio) server entry. LM Studio follows Cursor-style mcpServers JSON:
{
  "mcpServers": {
    "spryng-analysis": {
      "command": "/absolute/path/to/spryng-analysis-mcp",
      "args": [
        "--url",
        "https://app.spryng.io/api/organizations/YOUR_ORGANIZATION/mcp/analysis/rpc/"
      ],
      "env": {
        "SPRYNG_ANALYSIS_MCP_TOKEN": "YOUR_PERSONAL_ANALYSIS_TOKEN"
      }
    }
  }
}

Replace the command path, URL, and token with the values from Spryng. Never put a real token in shared documents or screenshots.

  1. Save the file. LM Studio loads the configured servers and starts a separate process for each one (0.3.17 notes).
  2. [VERIFY AFTER TEST] Confirm the Spryng tools appear for the loaded model and that a sample question returns study data from Spryng (third-party docs confirm MCP hosting; they do not prove this specific relay).

When a model calls a tool, LM Studio can show a confirmation dialog so you can review arguments before the call runs. You can manage always-allow choices later under App Settings → Tools & Integrations.

From LM Studio's docs: do not install MCP servers from untrusted sources; some servers designed for large cloud models use many tokens and can overflow a local model's context; when pasting JSON, keep the structure inside mcpServers intact.

Option B — Jan

Jan supports MCP with STDIO, HTTP, and SSE transports. Official documentation: MCP Servers.

Install Jan and pick a tool-capable local model

  1. Install Jan Desktop from the official site.
  2. Download a local model that supports tool or function calling. Jan documents Jan-v1 as supporting function calling (Jan-v1); that page lists about 8 GB RAM as a minimum for a Q4 build and about 16 GB RAM as recommended for a Q8 build. Larger tool-capable models need more memory.
  3. Select that model in a chat. Prefer models documented for tool calling over small base models that only chat.

Add the Spryng Analysis MCP server

  1. Go to Settings → MCP Servers.
  2. Click + Add MCP Server.
  3. Set:
Field Value
Transport STDIO
Command Absolute path to spryng-analysis-mcp
Args --url, then your Analysis MCP URL
Env SPRYNG_ANALYSIS_MCP_TOKEN = your personal token
  1. Toggle the server on. Jan shows a green indicator when the server is active.
  2. [VERIFY AFTER TEST] Confirm the Spryng tools list appears and that a sample question returns study data from Spryng.

Leave Allow All MCP Tool Permissions off unless your institution's policy requires automatic approval. Prefer reviewing each tool call while you learn the setup. Jan's default tool-call timeout is 30 seconds; raise it if responses from Spryng are slow on your network.

Work from a downloaded study file

From version 0.2.0 the same package can analyse a study without contacting Spryng. This is the option for researchers who want everything, data and model, to stay on one machine, or who work where Spryng is not reachable. It needs no token and no URL.

What you download

  1. In Spryng, open the study in Analysis and choose Work locally. If you currently have a search, a flow or panel view, a selection, or a frozen pack open, Spryng refuses the download and shows how to return to a supported view; the file always describes the whole permitted study, never a partial selection.
  2. Spryng checks your current study, questionnaire, and customer permissions, redacts protected content, and downloads a typed file named like study.spryng-study.json. It keeps each question's type (triad, dyad, monad, choice, free text), its poles or options, and a minimum group size that the file mode will enforce. Story text that consent or access rules do not allow to leave Spryng is marked withheld, not included.
  3. The same screen shows the installation steps and a ready-to-paste MCP server entry for the file. Downloads use your signed-in session; the file carries no token.

The file is yours to keep and to delete. Its checksum only detects accidental edits; it is not a signature, so do not treat a file someone sends you as proof of what Spryng holds.

Point the package at the file

Use the file instead of a URL and token:

{
  "mcpServers": {
    "spryng-local": {
      "command": "/absolute/path/to/spryng-analysis-mcp",
      "args": [
        "--local-study-bundle",
        "/absolute/path/to/study.spryng-study.json"
      ]
    }
  }
}

Spryng's Work locally screen shows this entry filled in for your download; paste it into LM Studio or Jan exactly as in Options A and B, with the absolute path to the executable and no SPRYNG_ANALYSIS_MCP_TOKEN. The --url and --local-study-bundle options are mutually exclusive: one server entry per mode. Stories are returned as short redacted excerpts; add --allow-full-story-text only when you need the full (still redacted) text.

What stays the same, and what changes

  • Same safeguards. Small groups are withheld below the file's minimum group size, including every histogram bin and option count. Statistics follow each question type: triads give composition points, never averages; dyads and monads give points and histograms on their 0 to 100 scale; choices give option counts; free text is searchable only. Titles, poles, option labels, and stories are redacted. Story text is treated as data; instructions hidden inside a story do not change what the tools do.
  • Nothing leaves the machine. File mode never reads other paths, never uses credentials or environment tokens, and never falls back to the network. With a local model in your host, the data and the model processing both stay on your computer.
  • A cloud assistant is still a cloud assistant. If your host sends prompts to a cloud model, that model receives the tool responses. Choose a local model in LM Studio or Jan for on-device processing.
  • Story Packs stay in Spryng. File mode is read-only. Creating, editing, and publishing Story Packs, and anything collaborative, happen in the Spryng app.
  • A snapshot, not a live view. The file is the study as permitted at download time. Download again for newer responses. The file is subject to your institution's data handling rules; it is study data on your disk.
  • Platforms. File mode is a preview for macOS and Linux. On native Windows it refuses to start (symlink-safe file reading is unavailable there); the live-study mode on Windows is unchanged.

Advanced: a CSV export with a schema you maintain

An Analysis workspace CSV export can also be read, but a CSV cannot safely carry question types. Generate a sidecar template from the CSV headers, bind each analysed column to a question key, type, poles or options, and missing-answer tokens, then start with both files:

spryng-analysis-local-schema-template --csv export.csv --out export.schema.json
spryng-analysis-mcp --local-file-csv export.csv --local-file-schema export.schema.json

The template refuses to load until every analysed column is bound, so a mistyped column cannot be averaged by accident. Prefer the downloaded study file; it already carries the types.

Try a question

With the local model selected and Spryng Analysis MCP connected, ask:

List the Spryng studies I can access. For one study, describe its questions and the statistics available.

Then:

Show a supported statistic for one question, explain any missing-answer or privacy limits, and identify the study and question behind it.

Success means the tools are discovered and the answer is grounded in returned study data. Spryng's in-app readiness check does not prove that an external assistant is connected.

Limits to expect

  • Local models are usually slower, and less reliable at multi-step tool use, than large cloud models. Wrong or skipped tool calls are common on small models.
  • The assistant only sees what Spryng allows: read-only tools, studies you can already analyse, and aggregates with small groups under the privacy floor suppressed.
  • In live mode, study requests still go to Spryng. A local model changes where the assistant's inference runs; it does not replace Spryng hosting or expand your permissions. In file mode the package answers from the downloaded file and makes no requests at all.
  • The desktop app may store conversation history on disk. Follow your institution's device and retention rules.
  • Spryng's optional built-in language-model features, when they are turned on for an organization on request, use commercial AI services under the AI policy. That path is separate from this local-assistant setup.
  • Revoke the personal token in Organization settings → Analysis MCP → Manage tokens when you are finished, and remove it from the MCP host configuration.

Troubleshooting

Symptom What to check
Executable not found Use the full absolute path in command.
Missing token Put SPRYNG_ANALYSIS_MCP_TOKEN in the MCP server environment or secrets UI, not only in a terminal session.
401 or 403 Revoked token, wrong organization URL, or plan / enablement.
Tools missing Model lacks tool use; MCP server off; host older than the documented MCP support; wrong transport (this relay needs STDIO).
Tools present, answers empty or invented Ask the model to show the tool result; compare with Spryng in the browser; try a larger tool-use model.
File mode exits with local_file_load:… The path must be a regular file, not a symlink; the file must be an unmodified spryng-study download or a CSV with a complete schema sidecar; native Windows is not supported for file mode.
File mode withholds a result A group, bin, or option is below the file's minimum group size. Broaden the question or filter; the floor cannot be lowered.