English Français العربية

io.github.handset-hq/handset

Official registry Media and design

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

Source code Website Documentation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

NPM package @handset/mcp
Claude Code 
claude mcp add handset -e 'HANDSET_API_KEY=<your handset_api_key>' -e 'HANDSET_ALLOW_LIVE=<HANDSET_ALLOW_LIVE>' -- npx -y @handset/mcp@0.1.1
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "handset": {
            "command": "npx",
            "args": [
                "-y",
                "@handset/mcp@0.1.1"
            ],
            "env": {
                "HANDSET_API_KEY": "<your handset_api_key>",
                "HANDSET_ALLOW_LIVE": "<HANDSET_ALLOW_LIVE>"
            }
        }
    }
}

Environment variables

  • HANDSET_API_KEY required secret Handset API key. Use a test-mode key (hs_test_…) — simulated carrier, free. Live keys are refused unless HANDSET_ALLOW_LIVE=1.
  • HANDSET_ALLOW_LIVE Set to 1 to permit a live-mode key (the agent can then text and call real people at real cost).

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. Handset UI
  2. What's in the registry
  3. Architecture
  4. Development
  5. Requirements
  6. Roadmap
  7. License

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.

# 1. Point the shadcn CLI at the Handset registry
npx shadcn@latest registry add @handset=https://ui.handset.dev/r/{name}.json

# 2. Install a complete texting surface + the server proxy route
npx 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:

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

pnpm install
pnpm --filter @handset/react build   # hooks package
pnpm dev                             # docs site + live demo at localhost:3000
pnpm 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.

Frequently asked questions

What is io.github.handset-hq/handset?

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

How do I install io.github.handset-hq/handset?

It runs on your machine. In Claude Code: claude mcp add handset -e 'HANDSET_API_KEY=<your handset_api_key>' -e 'HANDSET_ALLOW_LIVE=<HANDSET_ALLOW_LIVE>' -- npx -y @handset/mcp@0.1.1. For other clients, paste the JSON configuration from this page into their MCP settings.

Does io.github.handset-hq/handset need an API key?

Yes. It expects HANDSET_API_KEY, which you set in its configuration.

Is io.github.handset-hq/handset open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains io.github.handset-hq/handset?

It is published by handset-hq. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.