agent-tenant-user-mcp

MCP server for the MSPbots Agent Platform tenant/user API (mb-platform-user service) — lets an Agent list all platform tenants.

Naming note: this is not a third-party vendor integration. It wraps an internal MSPbots App API (path prefix /apps/mb-platform-user/api/...) on the Agent Platform (agent.mspbots.ai). "MSP" in the header names below refers to the MSPbots Agent Platform itself, not an external MSP tool vendor. Auth convention follows the same pattern already established in ticketqa-mcp (another internal Agent Platform App API MCP), per explicit instruction to reuse that pattern.

Overview

• Stateless HTTP service. No credentials are ever persisted — each request supplies its own bearer token/tenant/host 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).

Related MCP server: cipp-mcp

Scope

1 tool, matching the single documented endpoint (tenants.md, attached to PRD-15236):

• mspbots_user_list_tenants — GET /apps/mb-platform-user/api/tenants (paginated + filterable, returns all platform tenants; requires superAdmin/admin role per the source doc).

No larger public API exists to reference for broader scope (this is a first-party internal service), so scope is exactly what the source doc documents.

Query parameters were corrected on 2026-07-30 — Leo Yang posted the actual current INT-branch implementation (service/tenant.ts:87), which documents 4 filter parameters (search, isActive, createdFrom, createdTo) beyond the page/pageSize in the original tenants.md attachment, and clarifies that page/pageSize are both optional (defaults 1 / 20), not required. This tool has been updated to match that corrected spec.

Authentication

Per the source doc, this endpoint requires:

• Authorization: Bearer <JWT> (EdDSA-signed) — tenant/user/role are decoded from the JWT itself.

• An X_Tenant_ID value for platform routing — the source doc describes this as a Cookie, but the established working convention on this platform (confirmed in ticketqa-mcp, where the equivalent header was empirically required because a bearer token alone gets 404 App not found) is to forward it as an HTTP header instead. This server follows that same convention rather than the doc's literal wording, for consistency with the platform's other MCP servers.

The Agent Platform host (agent.mspbots.ai or its per-environment equivalent) is also supplied per-request, since different environments (INT/STG/PROD) may use different hosts.

HEADER 授权参数说明

Missing any header returns 401:

{
  "error": "Missing credentials",
  "message": "This server requires the X-MSP-Token header (Agent Platform bearer access credential), the X-MSP-Tenant-Id header, and the X-MSP-Host header (Agent Platform host)",
  "required_headers": ["X-MSP-Token", "X-MSP-Tenant-Id", "X-MSP-Host"],
  "optional_headers": []
}

Environment Variables

MCP Endpoint

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

• GET /health — health check, returns {"status": "ok", "service": "agent-tenant-user-mcp", "transport": "http"}

Tool List

search/is_active/created_from/created_to combine as AND; results are always sorted by createdAt descending; an invalid date value in created_from/created_to is silently ignored (not an error) per the confirmed INT-branch implementation.

测试示例

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

# Call the 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-MSP-Token: <jwt>" \
  -H "X-MSP-Tenant-Id: <tenant-id>" \
  -H "X-MSP-Host: https://agent.mspbots.ai" \
  -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": "mspbots_user_list_tenants",
      "arguments": {"page": 1, "page_size": 50, "created_from": "2026-07-01"}
    }
  }'

API Reference

• Source doc: tenants.md, attached to PRD-15236 — superseded for the query-parameter list by Leo Yang's 2026-07-30 confirmation of the actual current INT-branch implementation (service/tenant.ts:87), posted in the MB_AgentPlatform Teams chat.

Known Gaps

• Live self-test still not passing — every attempt so far (a PROD web-panel token, then a real Agent Platform admin-role JWT) has returned 403 Permission denied, even with header/cookie transport variations for X_Tenant_ID ruled out as the cause (all three transports gave the identical result). Current working theory: the JWT's appRoles field was an empty object ({}) and this endpoint may check per-app appRoles rather than the top-level roles array — unconfirmed, needs backend-side clarification.

• The X_Tenant_ID-as-header-not-cookie assumption is carried over from ticketqa-mcp's empirical finding on the same platform, not independently re-verified for this specific mb-platform-user service.

• code/timezoneOffset/timestamp-format semantics beyond the corrected query-parameter table are still only inferred from the original source doc, not officially confirmed by the backend team.