customerthermometer-mcp

MCP server for Customer Thermometer — an email-based CSAT/NPS survey platform. Exposes its full public REST API (survey reporting + sending) as MCP tools.

Overview

• Stateless HTTP service. No credentials are ever persisted — each request supplies its own credentials via headers, used only for the lifetime of that single request.

• Supports concurrent requests; per-request credential isolation is done via Python contextvars, not a global/shared client instance.

• Entry points: POST /mcp (MCP protocol) and GET /health (health check).

• Default port: 8080 (configurable via MCP_HTTP_PORT).

Scope

15 tools — the vendor's entire public API (single api.php endpoint, dispatched via a getMethod query parameter): 10 read methods (get_thermometers, get_recipient_lists, get_send_quota, get_happiness_value, get_nps_value, get_temp_rating_value, get_response_rate_value, get_num_responses_value, get_blast_results, get_comments) and 5 write methods (send_email, log_response, add_recipient_to_list, delete_response, unsubscribe_recipient). MSPbots itself only calls 5 of the 10 read methods (BlastResults, Comments, ResponseRateValue, NumResponsesValue, NPSValue) — this MCP covers the full API since the vendor's entire public surface is small enough to implement completely.

Authentication

Customer Thermometer authenticates with a static API key, sent as the apiKey query-string parameter on every call (the vendor's "super API key" style — no Authorization: Bearer header, which the vendor docs reserve for scoped "sub-API keys"). MSPbots' own integration also stores the API host (api_url) as a per-tenant field, so this server treats it as per-request too rather than a fixed default.

HEADER 授权参数说明

Missing either header returns 401:

{
  "error": "Missing credentials",
  "message": "This server requires the X-CustomerThermometer-Api-Key and X-CustomerThermometer-Api-Url headers",
  "required_headers": ["X-CustomerThermometer-Api-Key", "X-CustomerThermometer-Api-Url"],
  "optional_headers": []
}

Environment Variables

(No *_BASE_URL env var — the API host is per-tenant and always supplied via the X-CustomerThermometer-Api-Url header, never a fixed default.)

MCP Endpoint

• POST /mcp — MCP protocol (streamable HTTP transport)

• GET /health — health check, returns exactly {"status": "ok"} (a pure local liveness probe — it never calls out to the Customer Thermometer API, so it cannot reflect upstream availability; run a real tools/call to verify the MCP path itself)

Tool List

15 tools (10 read-only, 5 write). Every tool result is a JSON-serialized string per the SOP: the vendor's own payload — an XML document, or a plain integer/string — is JSON-encoded as-is (so, for example, an XML report comes back as a quoted JSON string containing that XML) rather than re-parsed into a different shape. Errors use the SOP's fixed envelope {"error": {"code", "message", "retryable"}} instead of ad-hoc strings.

All 7 tools that accept limit (get_happiness_value, get_nps_value, get_temp_rating_value, get_response_rate_value, get_num_responses_value, get_blast_results, get_comments) clamp it to 200 server-side. The vendor does not document a hard maximum of its own — a vendor support-doc example shows &limit=100000 being accepted — so this 200 cap is this server's own SOP-mandated ceiling (protecting the agent's context budget), not a vendor-imposed limit.

测试示例

# Health check
curl -s http://localhost:8080/health

# Call a tool via the MCP protocol (streamable HTTP) — requires an
# initialize handshake first per the MCP spec; abbreviated example below
# shows the tool-call request body only:
curl -s -X POST http://localhost:8080/mcp \
  -H "X-CustomerThermometer-Api-Key: <your-api-key>" \
  -H "X-CustomerThermometer-Api-Url: app.customerthermometer.com/api.php" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <session-id-from-initialize>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "customerthermometer_get_send_quota",
      "arguments": {}
    }
  }'

Live-verified (2026-07-29): customerthermometer_get_send_quota and customerthermometer_get_nps_value were both called end-to-end through this running server with a real API key and returned real account data (a credit count and an NPS score respectively).

API Reference

• Full public documentation: https://www.customerthermometer.com/integration/api-documentation/

Known Gaps

• getResponseRateValue/getNumResponsesValue method-name ambiguity in the vendor's own docs: each method's parameter table names the getMethod value without the Value suffix (getResponseRate, getNumResponses), but every worked example on the same page uses the ...Value suffixed name — and MSPbots' own configured endpoint names ("ResponseRateValue", "NumResponsesValue") match the suffixed form. This server uses the suffixed names (getResponseRateValue, getNumResponsesValue), consistent with the examples and MSPbots' usage.

• POST body encoding is not specified in the vendor docs for logResponse, addRecipientToList, and unsubscribeRecipient — they only list field names/types, not a content-type. This server sends them as application/x-www-form-urlencoded (the traditional convention for a PHP-based endpoint like this); if the vendor actually expects JSON, these three tools would need client.post to switch from data= to json=.

• Only the 5 tools matching MSPbots' own usage plus get_send_quota were live-verified with real data; the remaining tools are structurally correct (schema validated, MCP-protocol tools/list confirmed) but not individually smoke-tested — several (send_email, log_response, etc.) are write operations that would create/modify real survey data, so they weren't exercised against the live test account.

• No vendor-documented hard cap exists for limit (see the Tool List section above) — the 200-record ceiling enforced by this server is our own SOP-driven safeguard, not something the vendor requires.