Builder Guide

13 curated tools with a mandatory workflow for AI builders (Lovable, Replit, Bolt, v0, Bubble). Every generated page uses real Swoogo event data.

Endpoint: {{BASE_URL}}/mcp · Need all 31 tools? Assistant Guide

Connection Setup

Lovable

  1. Go to Settings → Connectors → Personal connectors.
  2. Click Add MCP server.
  3. Enter the URL: {{BASE_URL}}/mcp
  4. Approve the OAuth prompt when it appears.
  5. Recommended: upload the Lovable knowledge file in Settings → Knowledge for better results.
Lovable MCP support requires a paid plan and uses SSE transport only.

Replit

  1. Open your Repl and go to Agent configuration → MCP servers.
  2. Add a new MCP server with URL: {{BASE_URL}}/mcp
  3. Approve the OAuth prompt.
  4. Recommended: paste the Replit knowledge file content into the Agent instructions field for better results.

Generic MCP Client

For any MCP-compatible platform, configure:

{
  "url": "{{BASE_URL}}/mcp",
  "transport": "streamable-http",
  "auth": "oauth2"
}

The server supports OAuth 2.1 with PKCE. Your client will be redirected to the Swoogo authorization page on first connection.

Authentication

Automatic on first connection — your AI tool handles the OAuth flow. See API Reference for details.

Mandatory Workflow

Every page build MUST follow this 6-step workflow. Skipping any step produces incorrect pages.

1
swoogo-session-briefing()
Get the non-negotiable rules: field value types, submission format, and workflow requirements. Call with empty object {}.
2
swoogo-get-recipe(task_type)
Get the step-by-step recipe for your page type. Available types: registration_form, event_page, speaker_directory, session_schedule. Omit task_type to discover available recipes.
3
swoogo-event-bundle(event_id)
Retrieve ALL event data in one call: event details, sessions, speakers, sponsors, reg types, form questions, and packages. Includes computed event_features that tell you what this event has (paid/free, speakers, sessions, etc.).
4
Discovery Phase
Present event_features to the user and ask: What sections do they want? Embedded form or CTA link? Multi-page wizard or single page? Do NOT skip. Do NOT assume. Wait for answers.
5
swoogo-get-schema(page_type)
Get the page structure reference. Use FieldValueTypes for every form to know how to render inputs and format payload values. Available schemas: FieldValueTypes, RegistrationForm, EventPage, SpeakerDirectory, SessionSchedule.
6
swoogo-validate-page(event_id, sections, IDs)
Validate the generated page against real event data. Checks all referenced IDs exist, sections match event_features, and pricing is shown when required. MUST pass before delivering. If validation fails, fix errors and re-validate. After 3 failures: stop.

Available Recipes

Task Type Description
registration_form Multi-step registration form with dynamic fields, payments, session selection, file uploads
event_page Event landing page with hero, sessions, speakers, sponsors, pricing, venue sections
speaker_directory Speaker listing page with bios, photos, and linked sessions
session_schedule Session agenda/schedule page with timeline, track filtering, and speaker info

Knowledge File

Upload a knowledge file to your AI platform so it follows the workflow automatically. This is highly recommended for consistent results.

Download Knowledge File

Tool Reference

The Builder profile exposes 13 tools organized in three layers.

Orchestration (mandatory workflow)

Tool Description When to use
swoogo-session-briefing Returns the non-negotiable rules and mandatory workflow for building event pages. Contains field value rules, submission format, and the workflow steps. Step 1 Call at the start of every build session
swoogo-get-recipe Get the step-by-step recipe for a page type. Returns exact tools to call, order, conditional logic, and output format. Omit task_type to discover available recipes. Step 2 After session-briefing, before fetching data
swoogo-get-schema Get the structure schema for a page type or field value types. Use FieldValueTypes for every form to know how to render inputs and format payload values. Step 5 Before building the page structure
swoogo-validate-page Validates a generated page against real event data. Checks all referenced IDs exist, sections match event_features, and pricing is correct. Returns pass/fail with actionable errors. Step 6 Before delivering any generated page

Data (event information)

Tool Description When to use
swoogo-event-bundle Retrieve ALL data for an event in one call: event details, sessions (with locations, tracks, fees, speakers), speakers, sponsors, reg types (with fees), questions (with choices, pages, translations), and packages (with fees). Includes computed event_features. Step 3 Primary data source for every build
swoogo-events Smart event lookup: pass event_id for details, name for fuzzy search, or neither for a filtered list. Fuzzy mode handles typos, partial names, abbreviations. Read Find an event by name or ID before building
swoogo-sessions Smart session lookup with fuzzy search, track/date filters. Returns name, date, start/end time, location, track, capacity. Supports expand for speakers, fees, tracks. Read Drill-down on specific sessions (event-bundle includes all)
swoogo-speakers Smart speaker lookup with fuzzy name/email search. Returns first name, last name, email, company, job title. Supports expand for linked sessions. Read Drill-down on specific speakers (event-bundle includes all)
swoogo-event-questions Look up event structure: questions, websites, pages, or folders. Supports expand for choices, page metadata, and translations. Read Drill-down on questions, websites, or folders (event-bundle includes questions)
swoogo-reg-types Look up registration types with fees and early bird pricing. Returns name, description, capacity. Read Drill-down on reg types (event-bundle includes all with fees)
swoogo-packages Look up registration packages with fees and early bird pricing. Returns name, capacity, status, date range. Read Drill-down on packages (event-bundle includes all with fees)
swoogo-sponsors Look up sponsors for a Swoogo event. Returns name, website, sponsorship level. Supports filtering by level and status. Read Drill-down on sponsors (event-bundle includes all)

Operations

Tool Description When to use
swoogo-create-transaction Create a financial transaction record after external payment (e.g., Stripe, PayPal). High-risk (Tier 3) — always requires approval. Amount sign is auto-controlled by type. Transactions are immutable after creation. Tier 3 After external payment gateway confirms success

Critical Rules

Server-enforced. Violations produce 422 errors or incorrect pages.
  • NEVER invent data. All content must come from Swoogo tools only.
  • No CORS — the Swoogo API has no CORS headers. You MUST build a server-side backend.
  • No required markers in UI — the API validates server-side (422 errors).
  • 3-strike rule — if validation fails 3 times, stop and explain errors to the user.

For field formatting rules (choice IDs, address fields, session questions, .json suffix, flat body): see Common Pitfalls.

Troubleshooting

See API Reference → Troubleshooting.