# HXP Operator MCP > Source: /hxp/operator-mcp > Conditional OAuth onboarding and the implemented assistant tool contract Implemented, but not activated on the production origin when checked September 19, 2026: discovery and MCP POST returned HTTP `503`. The examples below apply only after Journey configures and qualifies the integration. They do not demonstrate a live third-party connection. ## Onboarding [#onboarding] 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](/hxp/authentication#delegated-operator-mcp), 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. ## Transport [#transport] 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): ```bash 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 tools [#implemented-tools] | Tool | Arguments in addition to `organizationId`, `scopeId` | Behavior | | --- | --- | --- | | `capabilities` | None | Shared collaboration capability/readiness description; does not add callable tools | | `read_thread` | `guestId` | Authorized non-sensitive comments, legacy evidence, and eligible Actions for the guest | | `task_status` | `id` | Current operator's saved task, subject to current access and source freshness | | `start_task` | `idempotencyKey`, `command` | Accept a bounded `task_start` command; return a receipt | | `cancel_task` | `idempotencyKey`, `id` | Revoke the operator's task and child grants; previously submitted external effects still require reconciliation | 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 context [#read-thread-context] ```json { "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 work [#start-bounded-work] ```json { "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 failures [#limits-and-failures] - 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](/hxp/actions). Those commands are documented for clarity, not exposed by this MCP tool set.