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. 使用 HTTP Basic Auth（username:password）调用 GET https://login.thrio.com/provider/token-with-authorities → 返回 {"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"}（纯本地探测，不调用 Nextiva/Thrio API）

工具列表

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

每个参数的文档位于各工具的参数模式中（可通过 tools/list 查看），不在此表中 — 此表仅为快速参考，此处参数名称与代码保持同步。

成功响应为供应商的 JSON，紧凑序列化（无美化打印，ensure_ascii=False），并限制在约 20,000 个字符以内 — 过大的列表响应会以 truncated/original_count 标记截断，而不是完整返回。这些端点没有供应商文档化的 limit/页大小参数（分页仅使用 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 生成的文档，涵盖认证、对象/数据 API、分析等）

已知差距

• 范围恰好是 MSPbots 配置的 5 个端点，而非供应商的完整 API 表面 — Thrio 的 API 还涵盖 Workitem 操作、列表管理、仪表板、录音、联系人同意、State DID、聊天、CRM、客户端、号码验证、WFM、TEAMS、回呼等（根据公开文档自身的导航）；这些不在本范围内。

• 分页是 start 偏移，经实证确认（传递 start=1 会将结果窗口移动一位，并相应更新响应的 previous 字段）— 供应商的公开文档对此的描述不如请求/响应形状实际展示的那么明确，因此这是针对实时 API 验证的，而非仅凭文档假设。

• 供应商文档中描述的 session/login 步骤（POST {location}/users/api/login）未被此服务器使用 — 它似乎仅用于创建完整的交互式代理会话（例如用于电话/ACD 状态），而非 MSPbots 使用的只读数据/分析端点，这些端点仅凭认证令牌即可正常工作。已通过成功调用所有 5 个端点而无需该步骤得到确认。