Quickstart

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

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:

{
  "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.

Start availability

Call check_availability with one complete U.S. service address:

{
  "address": "100 Example Avenue, Unit 4B, Chicago, IL 60601"
}

Do not send continuation fields with the initial address.

Resolve clarification or questions

If Hum returns address candidates, ask the user to select one and continue with its exact ID:

{
  "candidate_id": "candidate_example_01"
}

Add unit only when the result requests it:

{
  "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:

{
  "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.

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:

{
  "lookup_id": "lookup_example_01"
}

Polling the same lookup reads its current snapshot. It does not start another qualification.

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.

Start validation

Pass the selected executable offer and its lookup to validate_order:

{
  "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.

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:

{
  "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:

{
  "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.

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.

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:

{
  "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.

Retrieve the outcome

Use the checkout ID to read the latest persisted evidence:

{
  "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.

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 before presenting a fulfillment status. See the tool reference for complete input variants, fields, errors, and output schemas.

Before using production

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

​Quickstart

​Connect

​Complete workflow

​Interpret the result

​Before using production

Quickstart

Connect

Complete workflow

Interpret the result

Before using production