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