Vanity Phone Number Studio
Agent API
Turn a brief into ranked vanity phone numbers, decode numbers into words, and verify availability. Open source under MIT. Open the studio →
Authentication
The /api/agent/* routes require a bearer key: send Authorization: Bearer $VANITY_AGENT_API_KEY or x-api-key. Generate one with openssl rand -hex 32. If the server has no key configured, these routes return 503. See auth.md.
Find vanity numbers
POST /api/agent/find resolves a natural-language brief (city → area code, keywords → word pack), generates candidates, and — when the prompt asks for an available number, or onlyAvailable is set — verifies the top candidates against Twilio's inventory.
curl -s -X POST http://localhost:3000/api/agent/find \
-H "Authorization: Bearer $VANITY_AGENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "cool vanity number in Las Vegas for a tech business that is available",
"onlyAvailable": true,
"limit": 5
}'Decode a number
curl -s -X POST http://localhost:3000/api/agent/decode \
-H "Authorization: Bearer $VANITY_AGENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"number": "702-776-4726"}'Check availability
POST /api/availability accepts { "number": "702-776-4726" }. It is rate-limited and makes zero network calls when Twilio isn't configured.
POST /api/agent/verify batch-verifies words with Twilio's Contains pattern — one call per word confirms every number that spells it.
curl -s -X POST http://localhost:3000/api/agent/verify \
-H "Authorization: Bearer $VANITY_AGENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"areaCode": "702", "words": ["BIGCODE", "PROGRAM"]}'MCP
Two ways to connect, both exposing find_vanity_numbers, find_available_numbers, decode_number, and check_availability.
Remote (no install):
{
"mcpServers": {
"vanity": {
"type": "http",
"url": "https://vanity-phone-number.vercel.app/api/mcp",
"headers": { "Authorization": "Bearer YOUR_AGENT_KEY" }
}
}
}Local (stdio, self-hosted):
{
"mcpServers": {
"vanity": {
"command": "node",
"args": ["scripts/mcp-server.mjs"],
"env": { "VANITY_AGENT_API_KEY": "…" }
}
}
}Machine-readable
- /openapi.json — OpenAPI 3.1
- /.well-known/api-catalog — RFC 9727
- /.well-known/mcp/server-card — MCP server card
- /.well-known/agent.json — A2A agent card
- /llms.txt