@socialai/website-mcp

@socialai/website-mcp

Model Context Protocol server for the Social AI Website Builder.

Use Social AI from Claude, OpenAI Codex, Cursor, Windsurf, VS Code, or any MCP-compatible client to create websites, edit pages, manage shops, upload media, configure payments, inspect analytics, and publish live sites.

What Users Can Do

• Create a blank website or shop.
• Create a website from a Social AI template.
• Browse block types with reference links before adding headers, heroes, promo/ad sections, product rows, forms, and footers.
• Use setup presets for shop categories, variants, header menus, footer columns, contact pages, and product CSVs.
• Edit pages and blocks.
• Generate website copy, page sections, and themes with AI.
• Manage products, variants, categories, CSV import/export, discounts, and orders.
• Upload and host images.
• Configure country, currency, payment provider, and public site settings.
• Check preview, domain, analytics, leads, snapshots, and media limits.
• Publish a site when the account has an active package website slot.

Choose the Right Connection

For Claude.ai, Claude Desktop, Cowork, and other remote OAuth clients, add this custom connector URL:

https://socialai.one/api/mcp

Complete Social AI sign-in, approve access, enable Social AI in a new conversation, and ask the client to call get_started. No npm install, JSON edit, or API key is required for this path.

For local CLI and IDE clients, use the npm package below. This path requires Node.js 18 or newer and a Social AI API key from Settings -> API Keys. Put the live key directly in the local config or secret store; never paste it into chat.

Local Package Quick Start

Add this MCP server to a local AI client:

{
  "mcpServers": {
    "socialai-websites": {
      "command": "npx",
      "args": ["-y", "@socialai/website-mcp"],
      "env": {
        "SOCIALAI_API_KEY": "sai_user_xxxxx",
        "SOCIALAI_API_URL": "https://socialai.one"
      }
    }
  }
}

Then restart your AI client and try:

Help me create a Social AI website. Ask me one question at a time.

The MCP includes get_started, get_proactive_next_steps, get_store_setup_preset, get_intake_questions, quick_build, product_csv(action="template"), and a socialai_start_website prompt. Good AI clients can use those to guide the user through a friendly setup flow instead of dumping raw JSON.

For template browsing, ask for a small shortlist:

Show me 5 shop templates with preview links for a South African fashion store.

For block browsing, ask for focused options:

Show me 8 hero and header blocks with reference links.

Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "socialai-websites": {
      "command": "npx",
      "args": ["-y", "@socialai/website-mcp"],
      "env": {
        "SOCIALAI_API_KEY": "sai_user_xxxxx",
        "SOCIALAI_API_URL": "https://socialai.one"
      }
    }
  }
}

OpenAI Codex

Add to ~/.codex/config.toml:

[mcp_servers.socialai_websites]
command = "npx"
args = ["-y", "@socialai/website-mcp"]

[mcp_servers.socialai_websites.env]
SOCIALAI_API_KEY = "sai_user_xxxxx"
SOCIALAI_API_URL = "https://socialai.one"

Cursor or Windsurf

Add to .cursor/mcp.json or the Windsurf MCP settings:

{
  "mcpServers": {
    "socialai-websites": {
      "command": "npx",
      "args": ["-y", "@socialai/website-mcp"],
      "env": {
        "SOCIALAI_API_KEY": "sai_user_xxxxx",
        "SOCIALAI_API_URL": "https://socialai.one"
      }
    }
  }
}

VS Code

Add to .vscode/settings.json:

{
  "mcp": {
    "servers": {
      "socialai-websites": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@socialai/website-mcp"],
        "env": {
          "SOCIALAI_API_KEY": "sai_user_xxxxx",
          "SOCIALAI_API_URL": "https://socialai.one"
        }
      }
    }
  }
}

Tool Groups

Getting Started

• get_started
• get_proactive_next_steps
• get_intake_questions
• get_store_setup_preset
• quick_build
• product_csv with action: "template"
• list_blocks
• list_block_types
• Prompt: socialai_start_website
• Resources: socialai://mcp/getting-started, socialai://mcp/workflows/create-website

Websites

• list_templates
• create_website_from_template
• transfer_website_to_template
• manage_websites
• export_site
• apply_site
• publish_website
• get_preview_url
• manage_domain
• manage_snapshots

Pages and Navigation

• update_page_blocks
• manage_pages
• manage_navigation
• manage_posts

Block Catalog

• list_blocks
• list_block_types

Use this before adding sections when the user wants to choose a block visually or by name. Each result includes type, label, group, keywords, and referenceUrl.

AI and Theme

• generate_content
• manage_theme

Store, Products, Orders, and Discounts

• manage_products
• manage_variants
• manage_categories
• product_csv
• manage_orders
• manage_discounts

Media

• manage_media

Payments and Settings

• manage_store_settings

Analytics, Leads, Snapshots, and Support

• get_traffic_summary
• list_leads
• report_issue

Marketplace sellers

• manage_shop_seller — run a third-party seller account on the main Social AI Shop marketplace. This is a different shop from the website-builder store: manage_products and the other store tools are scoped to a website project, while most marketplace listings have none, so a marketplace seller cannot reach their own catalogue through them. Covers products (list/get/update/delete, plus set_offer for shared listings where the price lives on the offer rather than the product), image upload from the local machine or an https URL, CSV export/preview/import matched on SKU, dispatch and collection addresses with the courier prices the customer is charged, orders and shipment marking, returns decisions, balance and payout requests. A new product is submitted for Social AI approval rather than published; delete_product, delete_location, import_products and request_payout require confirm=true; payouts go only to the bank account saved in the seller portal and cannot be redirected from MCP; an order shows only the calling seller's own lines. Every write is recorded against the acting agent. Intentionally excluded from the OpenAI review profile.

Team & Partners

• manage_team — durable team inbox (my_inbox), assigned-task acknowledgement, submission with artifact URLs, owner approval/change requests, day/week/month work logs, and authorised team channels. Open Team pages receive live channel updates; assignments/submissions also send in-app notifications and email, while MCP clients retrieve state with my_inbox or my_tasks. Channel posts can optionally email recipients, and @sai answers with live team stats. Reports are filed to the owner and mirrored into #bugs.
• manage_business_teams — full-client multi-business administration: create/list businesses, select country/currency/accounting books, manage role-based members, choose Stripe/PayStack/PayFast and sandbox mode, narrow Team/MCP switches, and inspect accounting-linked customers/debtors. It never accepts or returns gateway secrets and is intentionally excluded from the OpenAI review profile.
• manage_team_invoices — full-client Team invoice CRUD, secure customer links, and confirmed email delivery. It can select Stripe, PayStack, or PayFast for the customer portal but cannot execute or mark a payment; signed provider webhooks do that. Delete and email actions require explicit confirmation. Administrators can disable Team invoicing, gateways, email, or the MCP invoice surface independently. This finance-adjacent tool is intentionally excluded from the OpenAI review profile.
• manage_feedback_surveys — full-client Team feedback survey CRUD, email preview, satisfaction/matrix/NPS/text questions, selected or all-Team delivery, invitation metrics, and response analysis. Delete and email actions require explicit confirmation. Team permissions and administrator switches are enforced, and the tool is intentionally excluded from the OpenAI review profile.
• manage_feedback_surveys — full-client Team feedback survey CRUD, email preview, satisfaction/matrix/NPS/text questions, selected or all-Team delivery, invitation metrics, and response analysis. Delete and email actions require explicit confirmation. Team permissions and administrator switches are enforced, and the tool is intentionally excluded from the OpenAI review profile.

Example Prompts

Help me create a Social AI website. Ask me one question at a time, then recommend templates.

Show me 5 premium shop templates with preview links for a South African fashion store.

Create a website from the best template for a premium dental clinic in Johannesburg.

List my websites, make the newest one the active package-slot website, and show me the preview URL.

Import this product CSV, upload the image URLs, create categories, and configure South African payments.

Export only the demo products with source columns, then replace the demo products with my real CSV.

Check my store orders, list open leads, and summarize the last 30 days of traffic.

Duplicate the About page, rename it Our Story, update the navigation, and publish when I confirm.

Show me promo/ad style blocks with reference links, then add the one I choose to the homepage.

Template Browsing Without Huge Output

list_templates supports filters so AI clients do not need to load every template:

• limit and offset for pagination.
• q for natural search text such as fashion, coffee, law, or skincare.
• projectType as website or shop.
• category for category/tag filtering.
• premium for premium/free filtering.
• includePages=false and summaryOnly=true for short chat output.

Each result includes a previewUrl so the user can click and inspect the template before choosing it.

Product CSV and Demo Products

Template shops can include demo products so the store looks complete before the seller adds their own catalog. Those demo rows are tagged separately from seller-imported rows.

• Use product_csv with action: "template" to create a fillable product CSV for the chosen store type.
• Use product_csv with action: "export" and scope: "demo" to download only template demo products.
• Use product_csv with action: "export" and scope: "user" to download only seller/imported products.
• Use includeSource: true when the AI or admin needs to see whether a row is demo or user-owned.
• Use product_csv with action: "import" and replaceDemoProducts: true when the seller confirms they want to delete the demo catalog and replace it with their real products.
• For a storefront URL migration, use Import Studio for the design direction and import_products_from_url for Shopify or WooCommerce/WordPress product feeds. Public WooCommerce works through the Store API; pass wooConsumerKey and wooConsumerSecret for private Woo catalogs and richer variation imports. The seller admin Products -> Import products from a store URL flow uses the same importer. URL imports create draft products first so the seller can review, edit, bulk-activate, mirror product images into Social AI storage, and publish intentionally.

The import endpoint imports core product fields plus supported variant/detail/spec columns. Follow-up MCP actions such as manage_variants, manage_categories, and manage_products(action: "mirror_images") can refine anything that needs custom handling after import.

Safeguards and Entitlements

The MCP respects Social AI plan rules:

• API keys must have the right scopes.
• Paid package slots control publishing, commerce, payments, and custom-domain power.
• Draft sites can exist without being assigned to a paid package slot.
• Media uploads are checked against storage, monthly upload count, file size, dimensions, and image type limits.
• AI generation checks plan access, rate limits, and credit billing.
• Expired/free accounts can read where allowed, but write, publish, commerce, AI, and custom-domain tools can be blocked by plan state.
• Project-scoped keys can only access their pinned project.

When a tool is blocked, the server returns an error code such as:

• mcp_access_denied
• website_edit_mode_denied
• inactive_package_slot
• active_package_slot_limit
• published_site_limit
• media_storage_limit
• monthly_media_upload_limit
• ai_provider_failed

Country-Aware Payments

Use manage_store_settings with action: "set_payments" and a country code:

Configure this shop for South Africa.

The tool can set country=ZA, currency=ZAR, and recommend providers such as Paystack, PayFast, and Ozow. Payment provider secret keys are not accepted through MCP; they must be entered in the Social AI dashboard.

Local Testing

PowerShell:

cd C:\sai\SaiApp\mcp
$env:SOCIALAI_API_URL = "http://localhost:3000"
$env:SOCIALAI_API_KEY = "sai_user_xxxxx"
node test-local.mjs

Do not paste the PS C:\...> prompt itself. Only paste the commands.

Publishing a New npm Version

The repository release contract is mcp/compatibility.json. The full OAuth endpoint is https://socialai.one/api/mcp; the OpenAI submission endpoint is the review-stable https://socialai.one/api/mcp/openai. Existing SocialAI entitlements apply on both endpoints, but the OpenAI profile does not expose checkout, subscription purchase, credit purchase, money transfer, or payment execution. lib/mcpOpenAiPolicy.json is the canonical OpenAI hint/payment policy; run npm run generate:chatgpt-submission and npm run check:chatgpt-submission whenever tools or hints change. Update the contract together with mcp/package.json, mcp/package-lock.json, the runtime version in mcp/src/server.ts, the public /mcp page, public/llms.txt, mcp/SETUP.md, and the admin MCP manual.

cd C:\sai\SaiApp\mcp
npm login
npm version patch --no-git-tag-version
npm run build
npm pack --dry-run
npm publish --access public
cd ..
npm run check:mcp-registry

The npm package only updates the local stdio server. Deploy the Social AI web app so the matching /api/mcp-api/* routes, https://socialai.one/api/mcp, and /mcp instructions are current. Then complete a clean hosted OAuth test with any local stdio Social AI server disabled.

Environment Variables

Variable	Required	Description
SOCIALAI_API_KEY	Yes	User or project API key from Social AI.
SOCIALAI_API_URL	No	Social AI API base URL. Defaults to https://socialai.one.

License

MIT