# Beaconstac — how to use (mcp.ai)

Connect your Beaconstac account and use 21 tools for marketing straight from your AI agent. Connect with your own API key. Beaconstac provides a platform for creating and managing QR codes and beacons, enabling businesses to engage customers through proximity marketing and track analytics.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_beaconstac?ms=1787295960000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `beaconstac_create_place`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/beaconstac`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/beaconstac/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/beaconstac/create/place` — Tool to create a new place for location-based assets. Use when you need to register a new physical place under an organization.
  - body: { name: string, address: string, latitude: string, longitude: string, organization: integer }
- `POST https://api.mcp.ai/api/beaconstac/create/qr/template` — Creates a new QR Code template with customizable design attributes. QR Code templates allow you to define reusable design presets for QR codes in your organization. You can customize colors, patterns,
  - body: { meta?: object, name: string, margin?: integer, default?: boolean, dotScale?: number, colorDark?: string, frameText?: string, logoImage?: string, logoScale?: number, colorLight?: string, frameColor?: string, frameStyle?: string, dataPattern?: string, eyeBallColor?: string, eyeBallShape?: string, gradientType?: string, organization: integer, eyeFrameColor?: string, eyeFrameShape?: string, frameTextColor?: string, backgroundColor?: string, backgroundImage?: string }
- `POST https://api.mcp.ai/api/beaconstac/create/tag` — Tool to create a new tag for organizing QR Codes and other objects. Use when you need to categorize QR Codes under a specific organization.
  - body: { name: string, organization: integer }
- `POST https://api.mcp.ai/api/beaconstac/create/user` — Tool to create a new User. Use when onboarding a new user under your organization (Reseller plan and above).
  - body: { email?: string, password?: string, username: string, last_name?: string, first_name?: string, organization: integer, billing_email?: string, customer_plan: string, profile_picture?: string }
- `POST https://api.mcp.ai/api/beaconstac/delete/qr/code` — Tool to delete a QR Code by its ID. Use when you need to remove an existing QR Code after validation.
  - body: { id: integer }
- `POST https://api.mcp.ai/api/beaconstac/delete/qr/template` — Tool to delete a QR Code template by its ID. Use when you need to permanently remove a QR Code template that is no longer needed.
  - body: { id: integer }
- `POST https://api.mcp.ai/api/beaconstac/delete/tag` — Tool to delete a tag by its ID. Use when you need to remove an existing Tag after validation.
  - body: { tag_id: integer }
- `POST https://api.mcp.ai/api/beaconstac/list/bulk/qr/codes` — Tool to list Bulk QR Code collections. Use when you need to filter, search, or order your bulk QR Code collections.
  - body: { page?: integer, search?: string, ordering?: string, page_size?: integer, qr_data_type?: integer, name__icontains?: string }
- `POST https://api.mcp.ai/api/beaconstac/list/organizations` — List all organizations accessible to the authenticated account. Use this tool when you need to: - Get a list of all organizations the user has access to - Retrieve organization details including IDs, 
  - body: { page?: integer, page_size?: integer }
- `POST https://api.mcp.ai/api/beaconstac/list/places` — Tool to list your Places. Use when you need to browse or search your account's Places with filtering and ordering.
  - body: { name?: string, page?: integer, search?: string, ordering?: string, page_size?: integer, name__icontains?: string }
- `POST https://api.mcp.ai/api/beaconstac/list/qr/templates` — Tool to list all QR code templates in your account. Use when you need to filter and paginate templates.
  - body: { page?: integer, page_size?: integer, organization: integer, name__icontains?: string }
- `POST https://api.mcp.ai/api/beaconstac/list/tags` — Tool to list all tags with optional filtering and pagination. Use when you need to browse or search tags in your account.
  - body: { page?: integer, ordering?: string, page_size?: integer, name__icontains?: string }
- `POST https://api.mcp.ai/api/beaconstac/list/users` — Tool to list all users with optional filtering, searching, ordering, and pagination. Use when you need to retrieve user records across your organization.
  - body: { page?: integer, search?: string, ordering?: string, page_size?: integer, email__exact?: string, organization?: integer, customer_plan?: string, date_joined__gt?: string, date_joined__lt?: string, username__exact?: string, date_joined__gte?: string, date_joined__lte?: string, email__icontains?: string, last_name__exact?: string, first_name__exact?: string, subscription_state?: string, username__icontains?: string, last_name__icontains?: string, first_name__icontains?: string }
- `POST https://api.mcp.ai/api/beaconstac/period/overview` — Tool to get period overview analytics for products including counts, impressions, and conversion percentage. Use after specifying the product_type and time interval.
  - body: { organization: integer, product_type: string, to_timestamp: integer, from_timestamp: integer }
- `POST https://api.mcp.ai/api/beaconstac/product/overview` — Tool to get analytics overview for a specified product type over a given time interval. Use after specifying the product type and time range to obtain summary metrics.
  - body: { organization: integer, product_type: string, to_timestamp: integer, from_timestamp: integer }
- `POST https://api.mcp.ai/api/beaconstac/retrieve/qr/code` — Retrieve detailed information about a specific QR Code by its ID. Returns QR code properties including name, type (static/dynamic), short URL, encoded data, design attributes, scan count, organization
  - body: { id: integer }
- `POST https://api.mcp.ai/api/beaconstac/retrieve/user` — Tool to retrieve the details of an existing User by ID. Use when you need to fetch a user's profile after confirming its existence.
  - body: { id: integer }
- `POST https://api.mcp.ai/api/beaconstac/update/place` — Tool to update the specified Place by ID. Use after retrieving the Place to modify its details, such as name, address, or coordinates.
  - body: { name: string, address?: string, latitude?: number, place_id: integer, longitude?: number, organization: integer, business_color?: string, business_icon_url?: string, business_cover_url?: string }
- `POST https://api.mcp.ai/api/beaconstac/update/qr/code` — Update an existing QR Code by its ID. Modify QR Code properties like name, design attributes, tags, and content. Returns the complete updated QR Code object. Important: When updating qr_type, you must
  - body: { meta?: object, name?: string, tags?: integer[], place?: integer, qr_type?: integer, campaign?: object, qrcode_id: integer, attributes?: object, fields_data?: object, organization?: integer }
- `POST https://api.mcp.ai/api/beaconstac/update/tag` — Tool to update an existing tag by its ID. Use when you need to modify a tag's name or color after confirming its ID via list_tags.
  - body: { name?: string, color?: string, tag_id: integer }
- `POST https://api.mcp.ai/api/beaconstac/update/user` — Tool to update an existing User. Use when you need to modify profile details or organization of a User by their ID.
  - body: { user_id: integer, last_name?: string, first_name?: string, organization?: integer, profile_picture?: string }

## Example prompts
- "What can I do in Beaconstac?"
- "Show me a summary of my Beaconstac account"

## More
- Page: https://mcp.ai/beaconstac
- Agent spec (llms.txt): https://mcp.ai/beaconstac/llms.txt
- Postman collection: https://mcp.ai/beaconstac/postman.json