Give your AI agent
a phone number.
Beacon is a self-hosted SMS API and MCP server. Connect your Twilio account so agents can send texts, receive replies, manage contacts, keep threads, and run OTP flows from your infrastructure.
Current release 0.3.5-beta changelog
The REST API and MCP server ship today. Beacon is beta software: the interface is still evolving, while analytics and additional channels remain planned. Your license never expires and includes releases published during the 12 months after purchase.
curl -X POST https://your-beacon.example/api/text \ -H "X-API-Key: beacon_YOUR_KEY_HERE_test" \ -H "Content-Type: application/json" \ -d '{ "phone_number": "+15555550123", "message": "Your order has shipped 🚀" }'
{
"success": true,
"textId": "9f1c2e4a-8b3d-4e5f-9c7a-1b2d3e4f5a6b",
"threadId": "7a2b1c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d"
}
Everything an agent needs to run an SMS conversation.
Beacon handles the full SMS lifecycle — sending, receiving, threading, contacts, and verification — so your agent can focus on the conversation, not the plumbing.
Context-Aware Threading
Every conversation is a first-class thread. Send outbound, receive inbound via webhooks, and poll for replies — all scoped to a thread your agent can track.
Autonomous Address Book
Full CRUD, upsert by phone or external ID, duplicate detection, merge, notes, tags, and multi-number support. Your agent's address book, built in.
OTP verification
Generate and verify one-time codes with configurable lifetime, placeholder support, and automatic invalidation. Failed-attempt tracking included.
Safety-First Outreach
Automatic keyword detection for STOP, CANCEL, UNSUBSCRIBE and more. Per-team suppression lists block sends and OTPs to opted-out recipients.
Team-scoped isolation
API keys, contacts, phone numbers, and opt-out lists are all scoped per team. Run multiple agents or clients from one Beacon install.
Reliability fundamentals
Idempotent writes with 24h replay cache, token-bucket rate limiting, delivery status sync from Twilio, and consistent JSON error responses.
OpenAPI-first
On your Beacon install, the OpenAPI 3.1 spec is at /openapi.yaml. Generate clients, import it into Postman, or point your agent at it — no copy-paste docs.
Business numbers
Run multiple sending numbers from one install. Set a primary, pause a number, attach per-number agent profiles and capabilities — all through the same API.
Connect one MCP server. Give your agent the whole conversation.
Beacon exposes high-level tools for sending messages, reading threads, resolving contacts, handling follow-ups, and verifying users. Your agent gets conversation context instead of raw SMS plumbing.
send_text
Send an SMS in the agent's team context
list_threads
Browse active conversation threads
check_replies
Poll a thread for new inbound messages
summarize_thread
Get an agent-ready conversation summary
get_contact_context
Pull contact details and recent activity
search_people_and_threads
Search contacts and conversations together
send_followup_to_contact
Close the loop on a pending conversation
send_otp
Generate and send a verification code
30 MCP tools, 17 resources, and 9 built-in prompts ship in the current beta.
See the complete MCP reference →From checkout to your first test message.
Your license portal provides the files and commands. Beacon's first-run setup creates the workspace, connects Twilio, selects a sending number, and generates your API key.
Get your license
Check out, and your license portal opens with a signed beacon.license file plus ready-to-paste install commands for Docker or Composer.
Install Beacon
Pull ghcr.io/apxcde/beacon with the creds from your portal, or composer create-project apxcde/beacon via our private registry. Drop beacon.license into storage/app/. Nginx, PHP-FPM, Redis, and Horizon boot together via Docker Compose on port 8000.
cp .env.example .env docker compose up -d # http://localhost:8000
Composer alternative and credentials in your license portal.
Read the docs →Connect Twilio
On your Beacon install, open /setup, paste your Twilio Account SID, Auth Token, and phone number. Beacon validates against Twilio's API and starts processing inbound messages automatically.
Connect your agent
Generate an API key from the setup dashboard, then wire your agent to the REST API or connect the MCP server to Claude Code in one command.
claude mcp add beacon https://your-beacon.com/api/mcp \ --transport http --scope user \ --header "X-API-Key: beacon_…"Read the docs →
Don't have Twilio yet?
Append _test to any API key and Beacon simulates Twilio, so you can verify the API before sending a live SMS.
Self-hosted Beacon is $99 during beta.
One payment includes both Docker and Composer installation, the complete REST and MCP surfaces, and releases published during the next 12 months.
Self-hosted Beacon
Deploy Beacon on your infrastructure and connect your own Twilio account. No recurring Beacon subscription.
One-time payment. Your license never expires, and the installed version keeps running even if you never renew updates.
- ✓ Full API + MCP server
- ✓ Docker and Composer installation
- ✓ Threads, contacts, OTP
- ✓ Team-scoped data and API keys
- ✓ OpenAPI 3.1 specification
- ✓ 12 months of updates from purchase
Want us to host it?
Beacon Hosted is not available yet. Join the waitlist if you want the product without managing a server or Twilio account.
Join the hosted waitlistNeed repository access?
Talk to us if your organization needs GitHub collaborator access, white-label rights, or a custom internal-use agreement.
Discuss repository accessPrefer not to run servers?
Beacon Hosted is coming — we run the infrastructure, provision your phone number, and meter usage. Join the waitlist and we'll email you when it opens.
Ready to run Beacon yourself?
Buy once, install with Docker or Composer, and send a simulated test message before connecting Twilio.