nextiva-mcp

Nextiva（联络中心平台，基于收购的 Thrio 产品构建——API 主机为 login.thrio.com / *.thrio.io）的 MCP 服务器。将 Thrio 数据和分析 API 的用户、活动、联系人、队列以及工作项历史记录作为 MCP 工具暴露。

命名说明：MSPbots 自身的集成注册名为 "Nextiva" （subjectCode=NEXTIVA）；底层 API 及所有文档 均引用 "Thrio"，即 Nextiva 收购的联络中心产品。本 MCP 仅覆盖 MSPbots 自身配置的 5 个方法。

概述

• 无状态 HTTP 服务。凭据不会被持久化——每个请求 通过请求头提供自己的用户名/密码，仅用于该 单个请求的生命周期。

• 支持并发请求；通过 Python contextvars 实现 每个请求的凭据隔离，而非使用全局/共享客户端实例。

• 入口点：POST /mcp（MCP 协议）和 GET /health（健康检查）。

• 默认端口：8080（可通过 MCP_HTTP_PORT 配置）。

Related MCP server: five9-mcp

认证

Thrio 的认证调用会返回同时包含令牌和实际租户级 API 主机——Thrio 部署在多个区域集群中，因此 不存在单一固定的数据平面主机名：

1. GET https://login.thrio.com/provider/token-with-authorities，使用 HTTP 基本认证（username:password）→ {"location": "https://<tenant-cluster>.thrio.io", "token": "..."}。

2. 所有实际的数据/分析调用随后发送到 {location}（而非 login.thrio.com），令牌按原样放入 Authorization 请求头——不带 Bearer 前缀。

由于无需保留会话，本服务器在每次工具调用时都会重新进行认证 ——MCP 请求之间不会缓存或持久化任何内容。

HEADER 参数说明

缺少任一请求头则返回 401：

{
  "error": "Missing credentials",
  "message": "This server requires the X-Nextiva-Username and X-Nextiva-Password headers",
  "required_headers": ["X-Nextiva-Username", "X-Nextiva-Password"],
  "optional_headers": []
}

用户名/密码无效会在工具调用层面报错，而非 HTTP 层面的错误。

环境变量

MCP 端点

• POST /mcp — MCP 协议（基于流式 HTTP 传输）

• GET /health — 健康检查，返回 {"status": "ok"}（纯本地探测，不调用 Thrio/Nextiva API）

工具列表

全部 5 个工具均为只读（readOnlyHint=True，idempotentHint=True）；没有写入/删除类工具。

每个参数的详细说明见各工具的参数 schema（可通过 tools/list 查看），本表仅为快速参考——参数名与代码保持同步。

成功响应直接返回厂商的 JSON，采用紧凑序列化（无 美化输出，ensure_ascii=False），并限制在约 ~20,000 字符以内—— 超长列表响应会被截断，并附带 truncated/original_count 标记，而非完整返回。这些端点没有厂商文档化的 limit/page-size 参数（分页仅通过 start 偏移量实现，参见下方已知限制），因此除上述 自动截断外，没有其他可限制的参数。

错误以 JSON 错误信封返回（而非异常/HTTP 错误），例如：

{"error": {"code": "upstream_error", "message": "...", "retryable": true}}

code 取值为 not_configured / unauthorized / not_found / invalid_argument / rate_limited / upstream_error，由 Thrio API 的 HTTP 状态码映射而来（参见 api_client.py 中的 error_envelope/NextivaError.to_envelope）。对外调用使用 5 秒连接 / 30 秒读取 超时，并在 429/5xx 响应时最多重试 3 次，采用带上限的指数退避 （并遵循 Retry-After）。

测试示例

# 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-Nextiva-Username: admin@example.com" \
  -H "X-Nextiva-Password: <your-password>" \
  -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": "nextiva_get_users",
      "arguments": {}
    }
  }'

已实测验证（2026-07-30）针对真实的 Nextiva/Thrio 租户，全部 5 个 工具均通过本运行中的服务器端到端调用：nextiva_get_users 返回了 101 个真实用户；nextiva_get_campaigns 返回了 9 个真实活动 （例如 "Nextiva - Transfers"）；nextiva_get_contacts 返回了 99 个真实 联系人；nextiva_get_queues 返回了 18 个真实队列；并且 nextiva_get_workitems_history 返回了真实的汇总统计（例如 最近 7 天内有 297 个呼入、195 个呼出、500 个联系人）——所有调用均 通过登录步骤动态解析租户的真实集群主机 （https://mancity.thrio.io）。

API 参考

• 公开文档，无需登录：https://api.thrio.com/（Postman 生成的 文档，涵盖 Authentication、Objects/Data API、Analytics 以及 更多内容）

已知限制

• 范围严格限定为 MSPbots 配置的 5 个端点，而非厂商的 完整 API 面——Thrio 的 API 还涵盖 Workitem 操作、List Management、Dashboards、Recordings、Contact Consent、State DID、Chat、 CRM、Client、Number Verification、WFM、TEAMS、Callbacks 等（参见 公开文档自身的导航）；这些均不在本服务器范围内。

• 分页仅通过 start 偏移量实现，已通过实测确认（传入 start=1 会使结果窗口偏移一条，并相应更新响应中的 previous 字段）——厂商公开文档对此的描述 不如请求/响应实际形态那么明确， 因此这是基于真实 API 验证得出的结论，而非仅凭 文档假设。

• 厂商文档中描述的 session/login 步骤（POST {location}/users/api/login）本服务器未使用——该步骤看起来 仅用于创建完整的交互式坐席会话（例如用于 电话/ACD 状态），而非 MSPbots 使用的只读数据/分析端点， 后者仅凭 Authentication 令牌即可正常工作。已通过在不使用该步骤的情况下成功调用全部 5 个端点得到确认。