Survey MCP

Survey MCP gives an AI assistant local language checks and guidance for Qube Script and ODIN. The assistant writes or changes your source; MCP returns checks and reference material. You review the changes and test the questionnaire. It is one server with tool namespaces for different work, not separate research, survey and assessment object models.

Use the assistant and account you already configure in Codex, Claude Code or Copilot. The verified VS Code Workbench integration is described below. Clean installation and authorization journeys for each other client remain separate qualification work. There is no deployed hosted OAuth MCP connector or authenticated deployment-mutation tool in this setup.

Use the supplied Workbench

The MCP-enabled beta VSIX includes the server. In a trusted workspace, run QUBE: Show AI Setup, then MCP: List Servers and start QUBE Survey. Choose its tools in your assistant’s chat. See Workbench for installation. This uses VS Code’s Node runtime and needs no QubeSurvey sign-in for local language tools.

The public ODIN extension 0.7.12 does not include this integration. The locally qualified Workbench 0.8.5 / Survey MCP 0.1.5 artifacts remain unpublished; use the complete beta package supplied to you.

Configure a portable local server

If supplied a portable Survey MCP archive, extract the entire package into a permanent directory. Install Node.js 22 or later. No npm dependency installation, Rust toolchain or QUBE source checkout is needed at runtime.

Check the package before starting it:

node /absolute/path/to/survey-mcp/survey-mcp.mjs --verify

Keep the launcher, manifest, parsers and assets together. Missing or changed packaged files prevent startup. Configure your client’s stdio MCP server with a command and arguments like these; the outer configuration structure belongs to your client:

{
  "command": "/absolute/path/to/node",
  "args": ["/absolute/path/to/survey-mcp/survey-mcp.mjs"]
}

The default speaks MCP 2026-07-28 and refuses the legacy initialization handshake. If the client requires MCP 2025-11-25, append "--legacy" to args. The Workbench provider selects that compatibility mode explicitly. Neither mode keeps an interview or conversation in the MCP server.

This is a local process connection. A reusable stateless HTTP adapter exists in the implementation, but is unmounted and does not provide hosted OAuth. Protocol compatibility, transport statelessness and authorization are separate.

Discover the available tools

Start with qube.workflow.get({"audience":"survey"}). Choose research for professional market research or assessment for quizzes and assessments. The guide reports which optional capabilities are actually configured.

QSS tools require the QSS-enabled package. A pattern definition’s review is not approval of an implementation. Exact example source, collection mode and limitations remain separate. Pending human-review candidates are excluded from packaged recommendations. Parser checks are not native interview replay or proof of scientific validity.

A research-to-Run workflow

1. Describe the decision to inform, audience, recruitment, intended measures and analysis. Ask the assistant to identify missing decisions before authoring.
2. Retrieve the audience workflow. If private methodology is configured, retrieve relevant notes and preserve their provenance. Use qss.guide.get for syntax.
3. Agree a short specification with expected branches, required answers, repeat identity and completion conditions. Ask for the complete .qube file.
4. Run qss.check on the complete source, review the diff, then run QUBE: Run Interview. Check the expected paths and Back corrections with invented data.
5. Upload the reviewed immutable version and prepare the Run in the human Fieldwork UI. Review access, outcomes, services and export.
6. If Fieldwork reads are authorized and configured, ask for aggregate counts for the explicit Account and Run. In the quota candidate, inspect current targets/counts and original setup separately. Use the UI for operational changes.

For a small survey, shorten the design step. For a quiz, specify the answer key, scoring and feedback before writing; see the practice quiz. The workflow guide does not grant new permissions or confidential marking.

Optional private methodology

Append --mr-root /absolute/path/to/KB to enable mr.search and mr.fetch. Use an existing compatible synthesis KB directory, not a raw document vault. The reader accepts its supported metadata and note layout; an arbitrary folder of Markdown is not a compatible KB. It refuses unsafe paths and files changed since startup; restart after legitimate KB edits.

Methodology is design guidance with provenance, not QSS syntax authority, implementation approval or permission to publish the notes. No private KB prose is included in the portable package. Retrieved text can still reach the AI assistant’s configured model; use material you are authorized to share.

Optional authenticated fieldwork reads

Candidate Workbench: explicit per-window consent

Use a supplied candidate Workbench with the new read bridge. The public ODIN extension 0.7.12 does not include it, and Workbench 0.8.5 remains unpublished. An existing download does not gain this feature from a source change.

1. Open a trusted workspace with qube.qubeSurvey.baseUrl set to exactly https://test.qubesurvey.com. Other destinations/base paths do not support this bridge.
2. Run QUBE: Allow MCP Fieldwork Reads. Review what can reach your assistant: aggregate Run progress, quota conditions/current counts and original setup history within your current permissions. Choose Allow reads.
3. The command enables the application setting qube.ai.mcp.fieldwork.enabled and uses existing browser device authorization if sign-in is needed. Cancellation or failure grants no consent. Refresh QUBE Survey tools in your assistant after access is allowed.
4. Supply the Account UUID you intend to inspect. Use fieldwork.runs.list to select a Run UUID, then ask for that Run’s progress or either quota read below. Obtain the intended Account UUID from your authorized beta setup; a display name is not a substitute.

The setting defaults to false and is only a ceiling. Setting it to true alone grants no access. Consent belongs to this editor window/current connection; another window needs its own confirmation. Discovery and server resolution never prompt or silently sign in.

The editor keeps the ordinary session bearer in SecretStorage/host memory. The bundled child receives only a revocable loopback capability. Run QUBE: Disable MCP Fieldwork Reads to revoke it while retaining local script tools. Disconnect, a changed destination or credential, and window reload invalidate access; use Allow again for the intended connection. Previously returned data cannot be recalled. Disable is not server-wide session revocation.

This is a local candidate, not a hosted OAuth connector or a new standalone login flow. The bridge permits four fixed reads; it does not make the saved ordinary session a read-only server credential. API availability and clean assistant/platform onboarding remain separate qualification work.

Standalone MCP: existing bearer configuration

Append --fieldwork-origin https://test.qubesurvey.com and securely supply an existing authorized user bearer through QUBE_MCP_ACCESS_TOKEN. Use the Test console origin for the current progress API. This is an explicitly configured local user’s connection, separate from the candidate Workbench bridge. This standalone adapter does not extract Workbench credentials or offer a new login flow. Leave it unconfigured if you have no authorized bearer; never put a token in a prompt or tool argument.

This connection currently requires assisted beta setup; there is no self-service standalone MCP sign-in or token-provisioning screen. Ask your inviter to help configure an authorized connection for your own user. If you do not already have a supported user bearer, leave this adapter disabled and use the Fieldwork UI.

Bridge and standalone bearer modes are mutually exclusive and neither enables itself from ambient credentials. A bridge failure never falls back to a bearer.

Choose the scope and interpret the results

An authorized account owner/admin can use Permissions in the Test console: select the Account, create a role with View Run progress, then assign that role to the member for All Runs in this account or one named Run. A scoped progress role does not grant participant or Script access. Ask the inviter for the exact Account and Run UUIDs for the intended scope; do not guess another account from a display name. Revoking the assignment removes that role’s grant.

The progress tools require an explicit Account UUID. fieldwork.runs.get also requires the Run UUID. Results contain only Run ID, name, status, total attempts and allocated/started/completed/finished/expired counts. Current account membership, scoped roles and revocation are checked by the product API on every request. Counts include retained historical attempts; they are not unique-person counts.

The source candidate adds two quota reads to this same connection. They require current paid owner/editor access; View Run progress alone does not grant access to quota conditions, targets or setup history. Both take only accountId and runId, using the explicit UUIDs for the intended scope.

Initial setup targets are historical configuration. Use the current quota read for operational targets and counts, including counts above target. Selected but unconfirmed setup still needs explicit recovery in Run Settings. An unavailable response does not mean zero interviews or an empty quota table. Reads neither configure quotas nor recover setup or activate a Run.

Quota reads and the Workbench bridge are local source/package candidates. The public download and deployed quota endpoints have separate release identities; an existing download does not gain tools from a repository change. Ask qube.workflow.get which tools the running server actually has. Hosted OAuth and standalone self-service MCP sign-in remain separate qualification work.

The tools cannot read participants, answers, individual attempts, invitation tokens or exports. They cannot create, activate, pause or close Runs, send messages, spend service credit or deploy source.

Model use belongs to your assistant’s provider and billing. Local language MCP does not call a model or charge QubeSurvey Agent credit. Hosted QUBE Agent and online Services have separate access and cost boundaries.