contactscience-mcp

MCP server for Contact Science — an appointment-setting / sales engagement CRM platform. Exposes its appointment and call-block reporting endpoints as MCP tools.

Naming note: MSPbots' own integration is registered as "Contact Science" (subjectCode=SCIENCE); the underlying API host is Contact Science's own backend, www.klpzmedia.com. This MCP covers exactly the 2 GET endpoints MSPbots itself has configured — see Known Gaps below for why the scope stops there.

Overview

• Stateless HTTP service. No credentials are ever persisted — each request supplies its own token via a header, 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).

Authentication

Contact Science authenticates with a single static API token, generated in the Contact Science admin portal. MSPbots' own integration convention sends this token as the raw value of the authorization header — no Bearer prefix — and this server forwards it exactly that way.

HEADER 授权参数说明

Missing the header returns 401:

{
  "error": "Missing credentials",
  "message": "This server requires the X-ContactScience-Authorization header",
  "required_headers": ["X-ContactScience-Authorization"],
  "optional_headers": []
}

Important quirk: unlike most REST APIs, Contact Science's own endpoints return HTTP 200 even when the token is invalid — the error is embedded in the JSON body instead ({"error": "Unauthorized", "message": "Invalid API Key"}). This server's client (api_client.py) detects that body shape and raises a tool-level error regardless of the HTTP status code, so callers still see a structured error envelope (see Error Handling below) rather than silently getting an error payload back as if it were real data.

Error Handling

Tool errors are returned as a structured JSON envelope (never raised as protocol-level exceptions), so a calling agent can branch on code and retryable programmatically:

{"error": {"code": "unauthorized", "message": "Invalid API Key", "retryable": false}}

code is one of a fixed vocabulary: not_configured, unauthorized, not_found, invalid_argument, rate_limited, upstream_error.

Environment Variables

MCP Endpoint

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

• GET /health — health check, returns {"status": "ok"} (local probe only, does not depend on the upstream Contact Science API)

Tool List

Both tools are plain GET calls against the same 2 endpoints MSPbots itself calls. start_date is required — confirmed by live testing, this is not documented anywhere and contradicts MSPbots' own stored integration config (which shows empty params); calling either endpoint without it returns {"error": "Invalid parameters", "message": "startDate parameter is missing"}. end_date is an accepted optional filter. Each tool also accepts an optional extra_params pass-through dict for any further query-string filters, since Contact Science does not publish a public API reference (see Known Gaps).

测试示例

# 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-ContactScience-Authorization: <your-contact-science-token>" \
  -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": "contactscience_get_appointments",
      "arguments": {"start_date": "2026-01-01"}
    }
  }'

Expected: 200 with the appointments list on a valid token; 200 with {"error": "Unauthorized", "message": "Invalid API Key"} in the body on an invalid token — surfaced by this server as a tool-level structured error envelope (see Error Handling above), not treated as real data.

Live-verified (2026-07-29) against a real Tech Guardian tenant token: both contactscience_get_appointments and contactscience_get_call_block returned real data end-to-end through this running server.

API Reference

• No public API documentation exists for Contact Science's reporting API. The vendor's marketing site (contactscience.com) and backend (klpzmedia.com) do not publish a developer reference, and no Swagger/OpenAPI spec or third-party reference was found. The two endpoints implemented here were confirmed directly from MSPbots' own stored integration configuration and by probing the live API.

Known Gaps

• Scope is exactly MSPbots' 2 configured endpoints, not a larger vendor API surface — Contact Science does not publish any public API reference, so (like bvoip-mcp earlier in this program) there was no broader public spec to weigh a wider scope against.

• Response field shapes are not independently documented — whatever the live API returns is passed through as-is; no schema/field reference exists to validate against.

• Beyond start_date/end_date, further filter parameters are undocumented; extra_params is provided so a caller who discovers additional supported filters can still pass them through.

• start_date being required could not be discovered from any documentation or from MSPbots' own stored config (which shows it calling both endpoints with zero params) — it was only found by calling the live API and reading the resulting error message. MSPbots' own sync may be relying on a default/fallback behavior not visible from the stored config, or may be passing it through a mechanism this investigation didn't surface.