Spryng Analysis MCP

Connect your preferred assistant to the Spryng studies you can access. This package provides a local Model Context Protocol (MCP) relay that forwards read-only requests to your organization's hosted Spryng Analysis service.

You need Python 3.10 or later, a desktop MCP client that supports local stdio servers, and a Spryng organization with Analysis MCP enabled. Installing this package does not enable the service or change your study permissions.

1. Get your connection details

In Spryng, open your study's Analysis → Connect your assistant. You can also open Organization settings → Analysis MCP at /organization/<organization-slug>/settings/analysis-mcp-tokens on your Spryng app host.

Choose your assistant, create a personal token, and copy the Analysis MCP URL shown there. The token begins with smcpa_ and is shown once. Keep it private. If setup is unavailable, ask your organization administrator to check access and enablement.

2. Install the relay

Choose one installation method. These shell examples are for macOS and Linux.

pipx

pipx install 'spryng-analysis-mcp==0.2.0'
spryng-analysis-mcp --help
command -v spryng-analysis-mcp

uv

uv tool install 'spryng-analysis-mcp==0.2.0'
spryng-analysis-mcp --help
command -v spryng-analysis-mcp

If the installed command is not found, follow your installer's PATH instructions and reopen your terminal.

Python virtual environment

python3 -m venv "$HOME/.local/spryng-analysis-mcp"
"$HOME/.local/spryng-analysis-mcp/bin/python" -m pip install 'spryng-analysis-mcp==0.2.0'
"$HOME/.local/spryng-analysis-mcp/bin/spryng-analysis-mcp" --help
printf '%s\n' "$HOME/.local/spryng-analysis-mcp/bin/spryng-analysis-mcp"

Copy the full executable path printed by your chosen method for the next step. On Windows, use the installed executable's full Windows path in your client's configuration; the shell commands above use Unix paths.

3. Add Spryng to your assistant

Open your assistant's MCP settings and add a local stdio server. For clients that accept an mcpServers JSON configuration:

{
  "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 command with the full executable path from installation, the URL with the exact URL from Spryng, and the token placeholder with your personal token. Do not use ~ or shell variables in command: desktop clients may not expand them. In Windows JSON, escape each path backslash as \\.

Use your client's secret storage if available. Otherwise, protect the local configuration file containing your token and never share it. Restart or reload the MCP connection after saving. Configuration formats vary by client.

4. Try a question

Ask your assistant:

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

Then:

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

Successful tool discovery and an answer grounded in returned study data confirm the assistant connection. Spryng's Check Spryng readiness checks server readiness; it does not prove that an external assistant is connected.

For the virtual-environment installation above, you can also check server connectivity from a terminal:

export SPRYNG_ANALYSIS_MCP_URL='YOUR_ANALYSIS_MCP_URL'
export SPRYNG_ANALYSIS_MCP_TOKEN='YOUR_PERSONAL_ANALYSIS_TOKEN'
"$HOME/.local/spryng-analysis-mcp/bin/python" -m spryng_analysis_mcp.connection_check

Exit code 0 means MCP initialization and tool discovery succeeded. It does not test a model's reasoning. With pipx or uv, verify discovery in your assistant; the package is isolated from your system Python.

Where data goes

The relay does not choose a model or fall back to a cloud model. It sends the token only to the configured, validated Analysis URL, rejects HTTP redirects, ignores environment proxy settings, and does not persist the token itself. Your assistant's configuration, conversation history, and model runtime have their own storage and network behavior.

Available tools and statistics come from your Spryng server. Do not treat a missing answer as a refusal or average a three-part answer as if it were a slider. Review source evidence and the usage rules returned with statistics before relying on an assistant's interpretation.

Revoke access or troubleshoot

In Organization settings → Analysis MCP → Manage tokens, revoke a token to deny subsequent requests using it. Also remove it from your assistant's configuration.

Contact support@spryng.io with the package version, client name, and error message. Remove tokens and participant data before sharing diagnostics. Learn more at Spryng.

Offline read-only file mode (v0.2.0)

When Spryng is unreachable, you can analyze an authorized portable study export (--local-study-bundle study.spryng-study.json) or an Analysis workspace CSV export plus a versioned JSON sidecar you maintain (--local-file-csv with --local-file-schema). The three modes, including --url, are mutually exclusive. File mode is read-only, uses no token, environment credential or URL, and never falls back to the network.

File mode is a preview for macOS and Linux. It requires a POSIX safe file open (O_NOFOLLOW with non-blocking regular-file checks). Native Windows is not supported for file mode: it fails closed with a load error and has no fallback reader. Hosted --url mode on Windows is unchanged.

The privacy floor is a safeguard of this connector, not a claim that the file owner cannot edit the export. A bundle's snapshot_id is an integrity digest, not proof of origin.

See the guide file docs/local-file-mode.md in the package source and the synthetic example under docs/examples/.

License

This connector is licensed under the Apache License, Version 2.0. Copyright 2026 ScrumDo LLC. The full LICENSE and attribution NOTICE are included in the distribution.

The license does not grant trademark rights, except for the reasonable and customary use needed to describe the origin of the work and reproduce the NOTICE, as provided in Section 6. This license covers the connector; it does not grant access to hosted Spryng services.