HXP Operator MCP

OnboardingCopy Anchor Link

1. Agree with Journey on the assistant host, requested organization/workspace, and read-only or bounded-write use case.
2. Journey registers the OAuth client with the configured authorization server and allowlists its client ID and collaboration scopes for the HXP resource.
3. The operator authorizes the host using the provisioned flow. The host obtains a resource-specific token; do not reuse a Core token or Journey API key.
4. Verify protected-resource discovery and claim requirements, current WorkOS membership, HXP permissions, and scope grants.
5. Initialize, list tools, and test an authorized read plus an out-of-scope denial. Qualify idempotent task acceptance, cancellation, and reauthentication before enabling writes.

Token issuance, refresh, consent, and supported client registration must be verified with the configured authorization server. HXP's implementation alone does not establish that onboarding has been completed.

TransportCopy Anchor Link

Use JSON-RPC 2.0 over POST /api/operator-mcp?organizationId={orgId}&scopeId={scopeId} with Authorization: Bearer ... and JSON content. The implemented initialization response advertises protocol version 2025-11-25 and server journey-hxp-operator version 1.0.0.

Supported methods are initialize, notifications/initialized, ping, tools/list, and tools/call. GET returns 405. There is no server push or event stream; retrieve saved task status. An initialization notification returns 202 with no body.

Example after provisioning (placeholder organization and scope):

curl --request POST \
  'https://v3.hxp.journey.com/api/operator-mcp?organizationId=hotel-example&scopeId=venue-example' \
  --header "Authorization: Bearer $HXP_MCP_ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"qualified-hotel-assistant","version":"1.0.0"}}}'

Keep tokens server-side. The query uses HXP organization/scope IDs; the token's org_id instead identifies the mapped WorkOS organization. Every tool's arguments must repeat the exact HXP context in the URL.

Implemented toolsCopy Anchor Link

All requests need hxp:collaboration:read; start/cancel additionally need hxp:collaboration:write. Domain permissions and execution grants still constrain work. Use tools/list for the exact current JSON schemas. The broader capability catalog may mention action.complete or guest.send; neither is an exposed MCP tool in this version.

Read thread contextCopy Anchor Link

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "read_thread",
    "arguments": {
      "organizationId": "hotel-example",
      "scopeId": "venue-example",
      "guestId": "guest-example"
    }
  }
}

The tool returns a JSON-RPC result.content array whose text entry is itself serialized JSON. For read_thread, that object contains guestId, comments, legacy, actions, excludedCount, and policy. Sensitive/deleted comments, private AI history, and Actions whose source comments are excluded are not returned. This is a bounded evidence view, not a paginated transcript export or listener.

Start bounded workCopy Anchor Link

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "start_task",
    "arguments": {
      "organizationId": "hotel-example",
      "scopeId": "venue-example",
      "idempotencyKey": "consult-example-001",
      "command": {
        "type": "task_start",
        "guestId": "guest-example",
        "audience": { "type": "staff" },
        "purpose": "Summarize the preparation needed for this guest's arrival.",
        "mode": "consult",
        "agentVersionId": null,
        "parentId": null,
        "deadline": "2026-09-20T18:00:00.000Z",
        "maxUnits": 1
      }
    }
  }
}

Replace the example deadline with a future ISO timestamp within the next 30 days. The command schema requires a purpose of 1–2,000 characters, a mode of consult, delegate, or human, nullable agent/parent IDs, and a budget of 1–50 units; runtime policy may further restrict them. A human task also requires HXP write permission. Agent-backed work requires an accessible, valid agent version.

Parse the receipt's id from the serialized tool result and use it as task_status.arguments.id, along with the same organization and scope. Acceptance is not completion. Keep the same idempotency key and input after an ambiguous response; the key belongs in the tool arguments, not only an HTTP header.

To cancel, call cancel_task with that task ID and a new stable idempotencyKey. Canceling a task is not a generic way to cancel any Action.

Limits and failuresCopy Anchor Link

• There is no MCP write_message, listen, claim_action, finish_action, handoff_action, or approval-execution tool in this release.
• Guest-facing approval remains in authenticated HXP. Starting a task does not grant permission to bypass it.
• Tool arguments are strict; unknown fields are rejected. Requests are capped at 32,000 characters, with an additional content-length check.
• Handle HTTP status and JSON-RPC error, not just HTTP success. Unknown methods return JSON-RPC -32601; authorization failures may use -32001; other request/application failures use -32602 in this adapter.
• An activated endpoint's 401 includes a WWW-Authenticate protected-resource metadata link. An unconfigured deployment returns 503. Reconnect through the authorization server when required; do not repeatedly retry invalid credentials.

For full operator-side Action transitions, see Actions and status changes. Those commands are documented for clarity, not exposed by this MCP tool set.