Survey Solutions MCP Server

Codex-ready local MCP server for Survey Solutions Headquarters workflows.

This package runs as a local stdio MCP server. It lets Codex inspect Survey Solutions servers, manage local connection profiles, run safe read workflows, download and inspect exports, and perform guarded fieldwork/admin actions when the local profile permission level allows it.

Status

• Version: 0.2.7
• Runtime: Node.js 20+
• MCP transport: local stdio
• Default profile: mock Survey Solutions server for local testing
• Implemented tools: 123
• Prompts: 6
• Resources: 2
• Current target clients: Codex / OpenAI MCP clients and Claude Desktop local MCP
• Developed and tested against Survey Solutions Headquarters server version 26.07
• Current scope: curated public API surface for Headquarters discovery, fieldwork operations, exports/version workflows, setup helpers, administration, statistics, and modular QC planning.
• License: MIT

What It Can Do

• Manage local Survey Solutions connection profiles with suso-mcp.
• Warn about duplicate live profiles and provide cleanup commands.
• Explain permission modes and recommend the least-permissive mode for a task.
• List workspaces, questionnaires, assignments, interviews, users, and export jobs.
• Normalize MCP pagination metadata across Survey Solutions endpoints that mix zero-based and one-based offsets.
• Start, inspect, download, and summarize export files.
• Return race-aware export cancellation envelopes with refreshed job state.
• Activate/deactivate web interview mode and create web-link assignments.
• Read interview details/history/stats/PDFs.
• Add interview comments and perform approval/rejection actions with explicit confirmations.
• Run guarded workspace/user/settings admin actions.
• Use GraphQL read queries and raw REST escape hatches when explicitly enabled.
• Report runtime diagnostics including package version, build timestamp, config path, active profile, and commit SHA when available, with a non-null fallback for source archives.
• Guide Codex or Claude Desktop through a named web-test workflow after manual questionnaire import: check/create test users, activate web mode, create a web assignment, and return the link.

Scope Notes

get_api_capabilities may report many REST operations from the active Headquarters Swagger/OpenAPI document. This is the standard server REST API description, not an OpenAI-specific spec, and it is useful for both Codex/OpenAI MCP clients and Claude Desktop. Version 0.2.7 keeps curated tools tied to endpoints confirmed in the tested Survey Solutions 26.07 public OpenAPI document, with raw discovery tools available for future documented endpoints.

get_tool_catalog includes requiredEndpoint, availability, verifiedOnCurrentServer, and unavailableReason fields for curated tools backed by a REST endpoint. Use it to distinguish a tool that is unsupported by the connected Headquarters build from a real missing assignment, questionnaire, or user.

Use curated tools first. Raw REST/GraphQL is deliberately gated and should stay disabled for ordinary AI-agent use. Raw API access is useful for advanced endpoint testing, but it does not provide the same guardrails, confirmations, permission explanations, or workflow guidance as curated tools.

Map and calendar wrappers were removed from the curated surface in v0.2.6 because no matching public REST/GraphQL guide or tested 26.07 OpenAPI endpoints were found. If a future Headquarters build documents those operations, use get_api_capabilities, openapi_operation, or guarded raw API testing before adding curated wrappers back.

Install

From a release zip or GitHub checkout:

npm install
npm run build
npm run smoke
npm link

On Windows, the easiest path is:

install-and-setup.bat

That installer checks Node/npm, installs dependencies, builds, runs smoke tests, links the commands, and optionally walks through live Survey Solutions profile setup.

Windows Helper Launchers

After running the installer once, these helper files provide a neat click-through way to change local runtime settings:

• switch-profile.bat: lists profiles, sets the chosen profile as active/default, and tests it.
• change-permission.bat: lists profiles, changes a profile permission level, and disables raw API flags when resetting to read_only.
• uninstall-mcp.bat: unlinks the global commands, checks for currently running MCP node processes, and shows the Codex/Claude config cleanup steps. It preserves local profiles unless run with -RemoveProfiles.

Restart Codex after adding or changing the MCP config. Also restart Codex after changing the active profile or permission level if the MCP server was already loaded.

Codex MCP Setup

After installation, add this MCP server to Codex/OpenAI MCP configuration. In Codex (ChatGPT Desktop), go to Settings > Plugins > MCPs and enter:

{
  "mcpServers": {
    "survey-solutions": {
      "type": "stdio",
      "command": "survey-solutions-mcp",
      "args": []
    }
  }
}

If your client requires a direct Node path instead of the linked command:

{
  "mcpServers": {
    "survey-solutions": {
      "type": "stdio",
      "command": "node",
      "args": [
        "C:/path/to/survey-solutions-mcp/dist/index.js"
      ]
    }
  }
}

Do not put Survey Solutions URLs, usernames, passwords, or tokens in the MCP launch config. Store those through the local profile CLI.

Restart Codex after saving or changing the MCP config so it reloads the local server definition.

Claude Desktop MCP Setup

In Claude Desktop, go to Settings > Developer > Edit Config. This opens claude_desktop_config.json.

Add the Survey Solutions server under mcpServers using the direct Node path:

{
  "mcpServers": {
    "survey-solutions": {
      "command": "node",
      "args": [
        "C:\\path\\to\\survey-solutions-mcp\\dist\\index.js"
      ]
    }
  }
}

Replace the path with the folder where this package was extracted. If your config already has other keys such as preferences, keep them and only add the survey-solutions block inside the existing mcpServers object. Claude Desktop does not need the Codex/OpenAI "type": "stdio" field.

Restart Claude Desktop after saving or changing the config so it reloads the local server definition.

Cleanup / Uninstall

Old extracted copies are mostly harmless if Codex and Claude Desktop no longer reference them. They can become confusing if multiple MCP client config entries point at old package folders, because the client may launch stale server versions.

To clean up the global command link and get guided client-config cleanup steps, double-click:

uninstall-mcp.bat

The cleanup helper does not delete C:\Users\<you>\.suso-mcp\config.json by default, because that file may contain profiles you want to reuse with the next version. To remove local profile config as well, run:

powershell -ExecutionPolicy Bypass -File .\uninstall-mcp.ps1 -RemoveProfiles

Profile CLI

List profiles:

suso-mcp profile list

Test the built-in mock profile:

suso-mcp profile test mock

Add a live profile with basic auth:

suso-mcp profile add test-server `
  --server-url "https://YOUR-SERVER.mysurvey.solutions" `
  --workspace "primary" `
  --auth basic `
  --username "api_user" `
  --password "api_password" `
  --permission read_only

Add a live profile with bearer/token auth:

suso-mcp profile add test-server `
  --server-url "https://YOUR-SERVER.mysurvey.solutions" `
  --workspace "primary" `
  --auth token `
  --token "YOUR_TOKEN" `
  --permission read_only

Set the active/default profile:

suso-mcp profile set-default test-server
suso-mcp profile test test-server

Remove a duplicate local profile after choosing the canonical one:

suso-mcp profile delete old-profile-name --yes

First Codex Prompt

Use the Survey Solutions MCP. Call survey_solutions_orientation, get_tool_catalog, list_profiles, get_mcp_diagnostics, check_connection, and list_questionnaires.

The mock profile should work immediately. Switch to a live profile only after suso-mcp profile test <name> succeeds.

Permissions

Profiles start as read_only. Raise permissions only for the exact action you intend to run:

suso-mcp profile permission test-server fieldwork_write
suso-mcp profile permission test-server admin_write
suso-mcp profile permission test-server read_only

Raw API access is separately controlled:

suso-mcp profile raw-api test-server enable-get
suso-mcp profile raw-api test-server enable-writes
suso-mcp profile raw-api test-server enable-delete
suso-mcp profile raw-api test-server enable-graphql-mutations
suso-mcp profile raw-api test-server disable

Development

npm install
npm run check
npm run build
npm run audit:openapi
npm run smoke

Release packaging is a plain source package with dist, docs, installer scripts, and user-pack included. The generated zip should exclude node_modules, local .suso-* folders, temporary files, and user config/secrets.

License

MIT. See LICENSE.

Documentation

• user-pack/README.md: end-user Codex setup and tool list.
• user-pack/LOCAL_COMPUTER_SETUP.md: step-by-step Windows setup.
• user-pack/TEST_CHECKLIST.md: mock/live/write testing checklist.
• docs/WRITE_TOOL_GUARDRAILS.md: permission and write-action safety notes.
• docs/MVP_BACKLOG.md: remaining product backlog.
• docs/GITHUB_UPLOAD_CHECKLIST.md: first public GitHub upload checklist.
• SECURITY.md: credential and raw-API safety notes.