> ## Documentation Index
> Fetch the complete documentation index at: https://docs.letshum.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Connect an MCP client and complete Hum's safe broadband availability and ordering workflow

# Quickstart

Connect an MCP client to Hum's stateless Streamable HTTP endpoint:

```text theme={null}
https://mcp.letshum.com/mcp
```

Hum does not require an account or API key. Your MCP client must support Streamable HTTP and the
server's negotiated MCP protocol version.

## Connect

Adapt this connection setting to your client's configuration format:

```json theme={null}
{
  "mcpServers": {
    "hum": {
      "url": "https://mcp.letshum.com/mcp"
    }
  }
}
```

Restart or reconnect the client, then confirm that `tools/list` returns all four tools:

* `check_availability`
* `validate_order`
* `create_order`
* `get_order`

You can also load the Hum manual from `skill://order-internet-service/SKILL.md`. Loading the skill
is optional; the tool descriptions and schemas contain the instructions needed to operate safely.

## Complete workflow

The examples below show tool arguments, not raw HTTP requests. IDs are inert placeholders. Always
use the exact opaque values returned to your client.

<Steps>
  <Step title="Start availability">
    Call `check_availability` with one complete U.S. service address:

    ```json theme={null}
    {
      "address": "100 Example Avenue, Unit 4B, Chicago, IL 60601"
    }
    ```

    Do not send continuation fields with the initial address.
  </Step>

  <Step title="Resolve clarification or questions">
    If Hum returns address candidates, ask the user to select one and continue with its exact ID:

    ```json theme={null}
    {
      "candidate_id": "candidate_example_01"
    }
    ```

    Add `unit` only when the result requests it:

    ```json theme={null}
    {
      "candidate_id": "candidate_example_01",
      "unit": "4B"
    }
    ```

    If Hum returns a current typed question set, collect the required answers without guessing and
    send the set together:

    ```json theme={null}
    {
      "lookup_id": "lookup_example_01",
      "question_set_id": "questions_example_01",
      "answers": {
        "residence_type": "apartment",
        "new_customer": true
      }
    }
    ```

    Use the answer keys and value types in the returned questions. Stale, missing, or extra answers can
    be rejected.
  </Step>

  <Step title="Preserve partial results and poll">
    Present FCC findings as area-level reported coverage even when the live check is still running. If
    the result says `checking`, wait at least `retry_after_seconds`, then call:

    ```json theme={null}
    {
      "lookup_id": "lookup_example_01"
    }
    ```

    Polling the same lookup reads its current snapshot. It does not start another qualification.
  </Step>

  <Step title="Choose an executable offer">
    Show the user the facts Hum returned, keeping unknown values unknown. A `catalog_plans` item is
    informational. Select only an item from `offers` that has `orderable_through_hum: true`, and keep its
    exact `offer_id`.
  </Step>

  <Step title="Start validation">
    Pass the selected executable offer and its lookup to `validate_order`:

    ```json theme={null}
    {
      "lookup_id": "lookup_example_01",
      "offer_id": "offer_example_01"
    }
    ```

    This creates or refreshes a draft. It does not create an order or contact fulfillment.
  </Step>

  <Step title="Provide only requested details">
    `required_fields` defines the checkout contract and may include fields already filled. Use
    `field_errors` to find the actual missing or invalid values, reuse facts the customer already gave,
    and ask only for what is still needed. Field-error paths are relative to `details`. Continue with
    the exact checkout and current revision, with `customer`, `installation`, `consents`, and
    `internet_addons` nested inside `details`:

    ```json theme={null}
    {
      "checkout_id": "checkout_example_01",
      "expected_revision": 2,
      "details": {
        "customer": {
          "first_name": "Sample",
          "last_name": "Customer",
          "email": "sample.customer@example.invalid",
          "phone_number": "+13125550100"
        },
        "installation": {
          "type": "self",
          "desired_service_start_date": "2026-10-15",
          "preferred_dates": {
            "first": {
              "date": "2026-10-15",
              "time_window": "8:00 AM - 12:00 PM (Local Time)"
            },
            "second": {
              "date": "2026-10-16",
              "time_window": "12:00 PM - 5:00 PM (Local Time)"
            }
          }
        },
        "internet_addons": [
          {
            "option_id": "equipment_example_01",
            "quantity": 1
          }
        ]
      }
    }
    ```

    Do not send card data, a Social Security number, existing-account credentials, or fields that Hum
    did not request. If validation is `checking`, wait at least `retry_after_seconds` and poll with only
    `checkout_id`:

    ```json theme={null}
    {
      "checkout_id": "checkout_example_01"
    }
    ```

    Do not resend `details` or `expected_revision` while polling: an edit increments the revision and
    restarts validation. If a revision is stale, retrieve the checkout with only `checkout_id`, wait
    while it is checking, then edit at the returned revision.

    If Hum returns `equipment_options`, show the name, price, included status, selection type, and
    quantity limit. Send the customer's complete selection in `details.internet_addons` using the
    exact returned option IDs. Omit `internet_addons` to retain the current selection or initial
    defaults; send `[]` to decline optional equipment. Select at most one `radio` option. If a
    dependent option appears after its parent is selected, keep the parent in the complete selection.
    Customer-owned equipment, included provider equipment, and optional paid equipment are distinct;
    a free provider gateway does not satisfy a request to use customer-owned equipment. Match the
    customer's preference using the returned option names and catalog facts, or ask the customer to
    choose when the requested option is unavailable.

    Use only `self` or `professional` for `installation.type`. When preferred dates are requested,
    collect both choices with one of the exact local-time windows shown above. Record explicit `true`
    or `false` choices for `customer.preferences.paperless_billing` and
    `customer.preferences.auto_pay`; do not turn either preference on silently.
  </Step>

  <Step title="Present the exact review">
    `ready` means the draft is technically valid; check it against the customer's budget, minimum
    speed, equipment, billing, and installation choices before asking for authorization. Present the
    returned review without filling in unknown facts. Include the selected plan, product quantities
    and line prices, monthly and one-time charges, total amount, bundle discount when returned,
    conditions, contract terms, installation preferences, billing preferences, and consents. The
    returned cart total is not necessarily the monthly bill or an amount due now. A requested
    installation date is not a confirmed appointment. Do not repeat a service PIN, full date of birth,
    or opaque checkout capability in customer-facing prose.

    If Hum reports changed or expired terms, follow the returned `next_action` and obtain a new review
    and authorization before submission. Do not repeatedly start the same failed draft; a fresh
    availability lookup is needed when the offer is unavailable or validation fails.
  </Step>

  <Step title="Obtain authorization and submit once">
    Use your host's approval mechanism to obtain authorization for the current review and
    `terms_hash`. Only then call `create_order`:

    ```json theme={null}
    {
      "checkout_id": "checkout_example_01",
      "validation_token": "validation_example_01",
      "idempotency_key": "order-attempt-example-01",
      "confirmation": {
        "terms_hash": "terms_example_01",
        "confirmed": true
      }
    }
    ```

    Keep the idempotency key stable for this exact intended order. Do not reuse it for different terms
    or a different checkout.
  </Step>

  <Step title="Retrieve the outcome">
    Use the checkout ID to read the latest persisted evidence:

    ```json theme={null}
    {
      "checkout_id": "checkout_example_01"
    }
    ```

    Call `get_order` after a normal submission and whenever the `create_order` response is lost,
    times out, disconnects, or is otherwise uncertain. Retrieve first; do not create a new checkout or
    blindly resubmit.
  </Step>
</Steps>

## Interpret the result

`queued` means Hum durably recorded the authorized order. Later states describe the fulfillment
submission evidence Hum has recorded. They do not confirm ISP acceptance, serviceability, an
installation appointment, or completed installation.

Read [Ordering and recovery](/mcp/ordering-and-recovery#fulfillment-states) before presenting a
fulfillment status. See the [tool reference](/mcp/tool-reference) for complete input variants,
fields, errors, and output schemas.

## Before using production

Follow the [testing instructions](/mcp/testing). Do not place a live order unless Hum has given you
an explicit test arrangement with approved address and customer data.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.