Handset

io.github.handset-hqPublished by GitHub account handset-hqv0.1.1Updated Nov 3, 2026

A business phone system for AI agents: send texts, place calls, read transcripts, buy numbers.

VerifiedSTDIODesktop onlyCommunication & CollaborationBusiness & Commerce

Overview

AI-generated overview

Handset is a business phone system for AI agents, letting an assistant send texts, place calls, read transcripts and buy numbers.

What you can do
  • Send text messages and place phone calls to real contacts
  • Read call transcripts and message history
  • Buy and manage phone numbers
  • Handle delivery, threading and STOP/HELP opt-out compliance through the Handset API
  • The manifest lists no individual tools, so exact operations are not documented here
When to use it
Useful when an assistant needs to reach people by SMS or voice as part of a business workflow, such as notifications, follow-ups or customer conversations, and you want to try it safely with a free simulated test-mode key first.
Requirements
Runs as a local stdio process from the npm package @handset/mcp, so Node.js is needed. Requires a Handset API key in HANDSET_API_KEY; a test-mode key (hs_test_…) is free and simulated. Live keys are refused unless HANDSET_ALLOW_LIVE=1. A Handset account is needed for real traffic.
Before you install
A live key lets the agent text and call real people at real cost, which is why HANDSET_ALLOW_LIVE must be set explicitly. Keep the API key server-side and out of browser code. Messages and calls go to third parties through the Handset API, and sending may incur charges and trigger compliance rules such as STOP/HELP handling.

Installation

In SourceWeft

  1. Open Handset in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

Handset UI

Texting inside your product, in an afternoon.

Open-source React components for embedded messaging, built on the Handset API. Distributed the shadcn way: the CLI copies the source into your repo, styled with your Tailwind tokens, yours to change.

bash
# 1. Point the shadcn CLI at the Handset registrynpx shadcn@latest registry add @handset=https://ui.handset.dev/r/{name}.json
# 2. Install a complete texting surface + the server proxy routenpx shadcn@latest add @handset/messaging @handset/next-routes

Set HANDSET_API_KEY in your env, wire resolveTenantId() in the generated route to your session, and render it:

tsx
import { HandsetProvider } from "@handset/react";import { Messaging } from "@/components/handset/messaging";
export default function MessagesPage() {  return (    <HandsetProvider>      <div className="h-[600px]">        <Messaging />      </div>    </HandsetProvider>  );}

What's in the registry

ItemWhat it is
@handset/messagingTwo-pane texting surface — inbox + thread, responsive to mobile
@handset/inboxConversation list: previews, relative times, STOP badges, infinite scroll
@handset/threadMessage history: delivery states, opt-out handling, wired composer
@handset/composerDraft box with live SMS segment counting and unicode detection
@handset/next-routesNext.js proxy route — your API key never reaches the browser

Architecture

Two layers, like shadcn-on-Radix:

  • @handset/react (npm, versioned) — headless hooks: useConversations, useThread, useComposer, plus segment math and a tiny client. Logic we maintain; bring your own UI if you prefer.
  • The registry (apps/www/registry) — the visual components, copied into your project as source.

Components never hold API keys. They call proxy routes in your backend (added by @handset/next-routes); your server holds the Handset key and your existing session auth decides which tenant each signed-in user sees. The Handset API handles the rest — numbers, delivery, threading, 10DLC compliance, STOP/HELP.

Development

bash
pnpm installpnpm --filter @handset/react build   # hooks packagepnpm dev                             # docs site + live demo at localhost:3000pnpm registry:build                  # compile registry.json → public/r/*.json

The docs site serves a mock Handset API (apps/www/app/api/handset) so the demo works with zero setup.

Requirements

  • React 18+ (components target React 19 / Tailwind v4 / shadcn CLI ≥ 3)
  • A Handset account for real traffic — the demo runs on mock data without one

Roadmap

See ROADMAP.md — shipped components, what's next (call summaries, MMS attachments, more framework proxies), and non-goals. Issues with real use cases move items up the list.

License

MIT © Handset HQ, Inc.

Source: README.md at commit 1cfd7b7

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.1LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts