mspbots-forms-mcp

MCP server for the MSPbots Forms/Survey API — lets an Agent build surveys, publish them, manage share links, and read back/analyze responses.

Naming note: this is not a third-party vendor integration. It wraps an internal MSPbots App API (survey builder + response collection feature) described in the API contract attached to PRD-15818. "MSP" in the header names below refers to the MSPbots Agent Platform itself, not an external MSP tool vendor. This follows the same pattern as ticketqa-mcp (PRD-14991) — an internal-App wrapper, not a vendor-mcp-template SOP project.

✅ Build status: read tools verified against real PROD data (2026-08-07)

This server was built from the API contract Leo Yang pasted into the PRD-15818 comment — the actual backend repository was not read. It's since been tested end-to-end (real MCP handshake + tool call, not just curl) against the real production deployment:

• Real host found by trial: the contract didn't say where this API is deployed. A working browser request (captured from the actual app-forms UI) revealed it: https://agent.mspbots.ai/apps/app-forms/api/... — a /apps/<name>/api/... prefix the contract never mentioned. It is only deployed on PROD — the same path 404s ("App not found") on agentint.mspbots.ai (INT).

• Undocumented tenant requirement, confirmed by isolation test: the contract claims tenant is derived purely from the JWT ("tenantId 从 token 取，永不从请求参数取"). Live testing proved that's only true past the app-routing gateway — without an X_Tenant_ID cookie (not a header!), the same token/path 404s ("App not found"); adding just that cookie (nothing else changed) turns it into 200. Same class of gap ticketqa-mcp hit (there it was an undocumented header; here it's a cookie).

• Verified working with real data: survey_list, survey_get (with include=questions), response_summary, share_list — all returned real, correctly-shaped data for an actual PROD survey (Untitled survey, id 9030b62e-4000-4e61-ae98-2b7285c86ea6).

• Not yet tested: any write tool (survey_create/update/publish/delete/quick_publish, share_create/update/delete) — deliberately not exercised against PROD without explicit sign-off, since they'd create/mutate/delete real data. response_list also untested (the one test survey has 0 responses).

• The 3 referenced design docs (survey-share-design.md, route-a-design.md, mcp-design.md) and the real service/lib/question-kinds.ts source were still not read — the question-kind table below remains transcribed from the comment, not source-verified. The text/textarea kinds that were tested match, though.

Related MCP server: crewhu-mcp

Overview

Implements the Model Context Protocol (Streamable HTTP transport) and exposes the 14 tools specified in the API contract:

Per the contract, the public respondent-facing endpoints (/api/public/* — unlock, save draft, submit) are deliberately not exposed as tools: an agent shouldn't be able to submit a survey on an anonymous respondent's behalf.

Quick Start

Docker (recommended)

docker compose up --build

The server starts on http://localhost:8080.

Local (uv)

uv sync
python -m mspbots_forms_mcp

Health Check

curl http://localhost:8080/health
# {"status": "ok", "service": "mspbots-forms-mcp", "transport": "http"}

No credentials are required for the health endpoint.

授权参数说明 (Authentication)

Every request to /mcp must include the following HTTP headers:

Missing any of the three headers returns 401 Unauthorized.

Environment Variables

MCP Endpoint

POST http://localhost:8080/mcp

Connect your MCP client with:

• Transport: http (Streamable HTTP)

• Headers: X-MSP-Token, X-MSP-Host, X-MSP-Tenant-Id (all required)

Question DSL (for survey_create / survey_update)

Each question is a dict: kind (required), title (required), required (bool), plus kind-specific fields. Question names (q1, q2, ...) are auto-assigned by the server in definition order.

showIf: {"question": "<earlier question name>", "operator": "is"/"isNot"/"greaterThan"/"atLeast"/"lessThan"/"atMost"/"contains"/"answered"/"empty", "value": ...} — question can only reference an earlier question (server rejects forward/circular refs with 422).

Multi-page surveys use pages: [{title?, questions: [...]}] instead of a flat questions list.

Test Example

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "X-MSP-Token: <token>" \
  -H "X-MSP-Host: https://agent.mspbots.ai" \
  -H "X-MSP-Tenant-Id: <tenant-id>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "survey_create",
      "arguments": {
        "title": "Customer satisfaction",
        "questions": [
          {"kind": "rating", "title": "Overall satisfaction", "required": true, "steps": 5, "lowLabel": "Poor", "highLabel": "Great"},
          {"kind": "radio", "title": "How did you hear about us?", "choices": ["Website", "Friend", "Ad"]}
        ]
      }
    }
  }'

API Reference

• Source spec: API contract pasted into a comment on PRD-15818 by Leo Yang

• Parent program: PRD-14513 — MSPbots MCP gateway

Known Gaps / Implementation Notes

• Verified 2026-08-07 against real PROD data: survey_list, survey_get (incl. include=questions), response_summary, share_list all returned correctly-shaped real data for a live PROD survey. The real host (https://agent.mspbots.ai/apps/app-forms/api/...) and the undocumented X-MSP-Tenant-Id → X_Tenant_ID cookie requirement (see Auth table above) were both discovered this way, not from the contract doc.

• Write tools are still untested: survey_create/update/publish/delete/quick_publish and share_create/update/delete have not been called — deliberately avoided mutating real PROD data without explicit sign-off. response_list is also untested (the one available test survey has 0 responses to list). Test these against a disposable survey before trusting them.

• survey_quick_publish is a composite tool (3 chained API calls: create → publish → share-create) with no rollback — if the second or third call fails, the survey and/or its published version will already exist. This is a client-side convenience, not an atomic server-side operation.

• share_update's action="rotate" calls a genuinely different endpoint (POST /api/shares/:shareId/token) than the other three actions (PATCH /api/shares/:shareId with a status field) — this was inferred from the contract's description ("把四个生命周期动作收敛进一个 tool") rather than the contract giving an explicit combined-tool spec; the underlying two endpoints themselves are separately documented and that part is solid.

• The question-kinds mapping table above was transcribed from the ClickUp comment's rendered markdown table, not read from the actual service/lib/question-kinds.ts source file the comment says is authoritative. The text/textarea kinds were confirmed correct against a real survey; the other 6 kinds (radio/checkbox/dropdown/rating/boolean/date) are still unverified.

• survey_update's interaction between definition and questions/pages when both are given is unspecified in the contract — this implementation includes both in the request body if both are passed, which may or may not be what the real server expects. Avoid combining them until confirmed.

• INT (agentint.mspbots.ai) does not have this App deployed (confirmed via direct request — 404 "App not found"). This service can currently only be tested/used against PROD.