Handset
A business phone system for AI agents: send texts, place calls, read transcripts, buy numbers.
Runs on your machine from its package; the steps are below.
What it does
- Reads
- Writes
- High impact
At most: moves money, runs code or commands, deletes data, or sends messages for you.
What it costs
FreeOdel charges nothing per call. The publisher may charge for its own service.
Runs locally over stdio
This server isn't hosted — your MCP client launches it from a package registry. Use one of the commands below, or drop the config into your client (e.g. Claude Desktop).
Run
npx -y @handset/mcp
MCP client config
{
"mcpServers": {
"handset": {
"command": "npx",
"args": [
"-y",
"@handset/mcp"
]
}
}
}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
| Item | What it is |
|---|---|
@handset/messaging | Two-pane texting surface — inbox + thread, responsive to mobile |
@handset/inbox | Conversation list: previews, relative times, STOP badges, infinite scroll |
@handset/thread | Message history: delivery states, opt-out handling, wired composer |
@handset/composer | Draft box with live SMS segment counting and unicode detection |
@handset/next-routes | Next.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.
