# Social Neuron -- Complete Product Documentation

> AI-powered content creation platform with closed-loop learning. Create videos, images, and social posts with 35+ AI models, distribute to 3 live platforms (YouTube, TikTok, Instagram) with 4 more coming, and let performance data make your next batch smarter.

## Table of Contents

1. Product Overview
2. Getting Started
3. Ideation Station
4. Content Creation Suite
5. Content Library
6. Distribution Hub
7. Analytics & Learning Loop
8. Automations & Workflows
9. Credits & Plans
10. What's New
11. Frequently Asked Questions
12. Comparisons
13. Use Cases
14. Technical Information
15. Links
16. Agent & Developer API

---

## 1. Product Overview

Social Neuron is an end-to-end AI content creation platform that handles the entire content lifecycle -- from ideation and creation to distribution and analytics. Rather than cobbling together separate tools for brainstorming, design, video editing, scheduling, and reporting, Social Neuron provides a single platform where all these stages are connected.

The key differentiator is the closed-loop learning system. When you publish content through Social Neuron, the platform tracks how it performs -- views, engagement, watch time, and growth. The research agent analyzes these patterns and feeds insights back into the ideation engine. Over time, your content suggestions become more aligned with what actually works for your audience. The more you publish, the smarter the system gets.

Social Neuron integrates 20+ premium AI models for video, image, and text generation. Every creation tool offers two modes: Easy Mode lets you describe what you want in plain language and the AI handles model selection and settings; Pro Mode gives you full control over model choice, parameters, and advanced options. Nothing is published without your explicit approval -- AI generates drafts, you review and decide.

---

## 2. Getting Started

Social Neuron helps you create engaging content faster with AI. Whether you are a creator, marketer, or business owner, you can generate professional videos, images, and social posts in minutes.

### Quick Setup (About 5 Minutes)

**Step 1: Create Your Brand Profile**
Go to Settings -> Brand Profile and tell us about your brand. This helps Brand Brain understand your voice, audience, and goals. The more detail you add, the better the AI matches your style.

**Step 2: Connect Your Social Accounts**
Link your YouTube, TikTok, Instagram, or LinkedIn accounts in Settings -> Connected Accounts. We use secure OAuth authentication and never store your passwords.

**Step 3: Start Creating**
Head to the Dashboard and choose where to begin: get AI ideas in Ideation Station, or jump straight to creating videos and images in the Creation Hub.

### Easy Mode vs Pro Mode

Every creation tool offers two modes. Easy Mode lets you describe what you want in plain language -- the AI handles model selection and settings. Pro Mode gives you full control over model choice, parameters, and advanced options. You can switch between them anytime.

### Browser Support

Social Neuron works in Chrome, Firefox, Safari, and Edge. We recommend using the latest version of your preferred browser. The platform is optimized for desktop use -- the dashboard and content library are responsive for mobile review.

**Tip**: The more detail you add to your Brand Profile, the better the AI will understand your style and create content that sounds like you. Include your website URL, brand guidelines, and examples of content you like.

---

## 3. Ideation Station

Stop staring at a blank page. The Ideation engine analyzes what is working in your niche and generates content concepts tailored to your brand -- complete with hooks, angles, and predicted engagement potential.

### Four Ideation Modes

**Research Mode**
Enter a topic and get data-backed content ideas based on what is performing well. Great for discovering new angles on trending subjects. Uses competitor analysis and trend data.

**Brainstorm Mode**
Need quick inspiration? Get rapid-fire ideas that match your brand voice and audience preferences. Perfect for filling your content calendar fast.

**Campaign Mode**
Planning a launch or series? Generate cohesive content batches around a central theme or product. Get a complete campaign with varied angles that tell a connected story.

**Trends Mode**
See what is trending now and get ideas for how your brand can authentically join the conversation. Real-time trend analysis across platforms.

### How to Use Ideation

**Step 1: Choose Your Mode**
Select the ideation style that fits your current need -- research for deep dives, brainstorm for quick ideas.

**Step 2: Enter Your Topic**
Describe what you want to create content about. Be specific for better results -- "sustainable fashion for Gen Z" works better than just "fashion."

**Step 3: Review & Select**
The AI generates multiple concepts. Each shows the hook, angle, format suggestion, and why it could perform well.

**Step 4: Send to Creation**
Click on any idea to automatically start creating content based on that concept. The idea context carries over to the creation tools.

**Tip**: Ideas cost just 1 credit each. Generate lots of options and pick the best ones -- it is far more cost-effective than trying to create the perfect piece on the first try.

---

## 4. Content Creation Suite

The Creation Hub is where ideas become reality. Generate professional videos, eye-catching images, and platform-optimized content using AI -- no design skills required.

### Generative Studio

Create videos and images from text descriptions using 35+ AI models.

- Easy Mode: Describe what you want, AI handles the rest
- Pro Mode: Choose models, aspect ratios, and fine-tune parameters
- Multiple styles: realistic, animated, cinematic, and more
- Batch generation for testing multiple variations

### Avatar Lab

Create UGC-style talking head videos with AI presenters.

- Choose from diverse AI presenters
- Script assistance with hook generation
- Natural voice synthesis in multiple languages
- Perfect for product reviews and explainer content

### Repurpose Studio

Transform existing content into new formats.

- Turn long videos into short clips
- Convert articles and blog posts into video scripts
- Extract highlights automatically
- Maintain brand voice across formats

### Quick Wizards

One-click content from URLs or product pages.

- URL to Video: Any webpage becomes a video
- Product Showcase: Create demos from product pages
- Auto-generated hooks and scripts
- Blog to YouTube pipeline

### Storyboard Studio

Build complete video storyboards with AI.

- Four phases: Script -> Scenes -> Visuals -> Assembly
- AI-generated visuals for each scene
- Transitions, music, and voiceover
- Export as finished video

### Video Editor

The built-in Video Editor lets you fine-tune any generated video before publishing. Trim clips, add captions, adjust timing, overlay music, and export in multiple aspect ratios (16:9, 9:16, 1:1). No external editing tools needed.

**Best Practice**: Start with Easy Mode to get familiar with what is possible, then graduate to Pro Mode when you want more control over the output. Generate multiple variations and pick the best one.

---

## 5. Content Library

Content Library is your central hub for all generated content. Every video, image, and text piece you create is automatically saved here, organized by project.

### Features

- **Filter & Search** -- Filter by content type (video, image, text), status (draft, published, scheduled), or date range
- **Preview** -- View any piece of content with full playback controls before deciding what to do with it
- **Download** -- Export content in standard formats (MP4 for video, PNG/JPG for images) for use outside Social Neuron
- **Send to Distribution** -- Publish any piece of content directly to your connected social accounts
- **Edit** -- Open any video in the Video Editor or regenerate images with different prompts

**Tip**: Content is organized by project. Use projects to separate different brands, campaigns, or content types for easier management.

---

## 6. Distribution Hub

Once your content is ready, publish directly to your connected social accounts. Schedule posts for optimal times and let the platform handle formatting automatically.

### Supported Platforms

- YouTube (Live)
- TikTok (Live)
- Instagram (Pending platform approval)
- LinkedIn (Pending platform approval)
- X / Twitter (Pending platform approval)
- Facebook (Pending platform approval)
- Threads (Coming soon)

### How to Publish

**Step 1: Select Your Content**
From the Content Library, choose the video or image you want to post.

**Step 2: Choose Platforms**
Select which connected accounts should receive this content. You can post to multiple platforms at once.

**Step 3: Customize Per Platform**
Edit captions, hashtags, and descriptions for each platform. The preview shows exactly how it will appear.

**Step 4: Schedule or Post Now**
Set a specific date/time or publish immediately. The system suggests optimal posting times based on your audience.

### Connecting Accounts

Go to Settings -> Connected Accounts and click the platform you want to add. You will be redirected to authorize access through the platform's official OAuth flow. We never store your passwords -- all tokens are encrypted at rest.

**Note**: Each platform has different content requirements (aspect ratios, length limits, etc.). Social Neuron automatically adjusts your content to meet each platform's specifications -- no manual reformatting needed.

---

## 7. Analytics & Learning Loop

This is what makes Social Neuron different. We do not just show you numbers -- we analyze your performance and use those insights to make your next content even better.

### Performance Dashboard

**Performance Tracking**
- Views, likes, shares, and comments
- Watch time and retention curves
- Engagement rates by platform
- Growth trends over time
- Content performance comparisons

### AI Learning Loop

The system analyzes what is working and automatically applies those insights to future content suggestions. Your ideation results improve as you publish and track more content.

Example: "Videos with questions in the first 3 seconds get 40% more watch time -- future hooks will include questions."

### How the Learning Loop Works

1. **Publish**: Your content goes live on connected platforms.
2. **Track**: The system monitors performance metrics across all platforms.
3. **Analyze**: The research agent identifies patterns in top-performing content -- hooks, formats, topics, timing.
4. **Improve**: Insights are injected into the ideation engine, so future suggestions are informed by what actually works for your audience.

---

## 8. Automations & Workflows

Build custom workflows that run automatically. Perfect for consistent posting schedules, content series, or complex multi-step processes. This is the most powerful feature for teams producing content at scale.

### Three Ways to Automate

**Flow Builder**
Visual drag-and-drop workflow designer. Chain together ideation, creation, review, and publishing steps into custom flows. Connect nodes with conditions and branching logic.

**Autopilot**
Set a schedule and let the system generate and publish content automatically. Choose your topic, frequency, and platforms -- Autopilot handles the rest with your Brand Brain context.

**Recipes**
Pre-built workflow templates for common tasks. One-click setup for things like "weekly trend roundup" or "daily social post." Customize any recipe to match your needs.

### What You Can Automate

- **Scheduled Content Series**: Set up recurring content that posts on a consistent schedule across platforms
- **Multi-Platform Publishing**: Post the same content to multiple platforms with platform-specific adjustments
- **Content Pipelines**: Chain ideation -> creation -> review -> publishing into one automated flow
- **Trend Monitoring**: Automatically research trends and generate content ideas based on what is performing
- **Approval Workflows**: Route content through team review before publishing -- perfect for brand compliance

### Building Your First Automation

**Step 1: Choose a Starting Point**
Start from a blank flow, use a recipe template, or set up Autopilot for the simplest option.

**Step 2: Configure Your Trigger**
Choose when the automation runs: on a schedule (daily, weekly), manually, or when triggered by an event (new trend detected).

**Step 3: Add Action Steps**
Drag and connect nodes: Ideate -> Generate Image -> Write Caption -> Publish. Each node has its own settings.

**Step 4: Test and Activate**
Run a test execution to verify the output. Review the results, then activate the automation to run on its schedule.

### Execution & Monitoring

All automation runs are logged with detailed execution history. See which steps completed, what content was generated, and whether publishing succeeded. Failed steps are retried automatically, and you will get notifications for anything that needs attention.

**Tip**: Start with simple automations (e.g., "generate and publish one post daily") and expand complexity as you get comfortable. Use the approval queue to review automated content before it goes live.

---

## 9. Credits & Plans

Social Neuron uses a credit system to keep pricing simple and transparent. 1 credit = $0.01 USD. Different actions cost different amounts based on the computational resources required.

### Credit Costs (Starting From)

| Category | Starting From | USD Equivalent |
|---|---|---|
| Text & Ideation | 1 credit | $0.01 |
| AI Images | 15 credits | $0.15 |
| AI Videos | 200 credits | $2.00 |
| Analysis & Research | 2 credits | $0.02 |

Costs vary by AI model. Premium models (Midjourney, Sora 2, Flux Max) cost more but produce higher quality. Easy Mode automatically picks the most cost-effective model; Pro Mode lets you choose.

### Detailed Model Pricing

#### Video Generation (per video)
| Model | Credits | USD |
|---|---|---|
| Veo 3 Fast | 120 | $1.20 |
| Luma | 100 | $1.00 |
| Midjourney Video | 150 | $1.50 |
| Runway Aleph | 200 | $2.00 |
| Sora 2 | 300 | $3.00 |
| Veo 3 Quality | 600 | $6.00 |
| Sora 2 Pro | 900 | $9.00 |
| Kling | 17 credits/second | $0.17/sec |

#### Image Generation (per image)
| Model | Credits | USD |
|---|---|---|
| Imagen 3 | 15 | $0.15 |
| Midjourney | 20 | $0.20 |
| Ideogram | 20 | $0.20 |
| Seedream | 20 | $0.20 |
| Imagen 4 Fast | 25 | $0.25 |
| Imagen 3 Pro | 25 | $0.25 |
| Flux Pro | 30 | $0.30 |
| Imagen 4 | 35 | $0.35 |
| GPT-4o Image | 40 | $0.40 |
| Flux Max | 50 | $0.50 |

#### Text & Ideation (per call)
| Task | Credits | USD |
|---|---|---|
| Content idea | 1 | $0.01 |
| Caption | 1 | $0.01 |
| Script | 2 | $0.02 |
| Advanced reasoning | 3 | $0.03 |

#### Analysis (per use)
| Feature | Credits | USD |
|---|---|---|
| Trend research | 2 | $0.02 |
| Viral coach analysis | 3 | $0.03 |
| Brand Brain analysis | 5 | $0.05 |
| Brand extraction | 5 | $0.05 |

#### Additional Costs
| Feature | Credits | USD |
|---|---|---|
| Hook generation | 1 | $0.01 |
| Caption generation | 1 | $0.01 |
| Idea brainstorm | 1 | $0.01 |
| Script generation | 2 | $0.02 |
| Campaign builder | 3 | $0.03 |
| Repurpose analysis | 5 | $0.05 |
| Thumbnail generation | 8 | $0.08 |

### Subscription Plans

#### Free -- $0/forever
- 100 credits per month
- 1 brand
- 2 projects
- Basic AI models
- Content library
- No credit card required

#### Starter -- $29/month
- 800 credits per month
- 1 brand
- 3 projects
- 3 platforms
- 1 team member
- Annual: $23/month billed yearly (save 20%)

#### Pro -- $79/month
- 2,000 credits per month
- 3 brands
- 10 projects
- All platforms
- 1 team member
- Priority support
- Annual: $63/month billed yearly (save 20%)

#### Team -- $199/month
- 6,500 credits per month
- 10 brands
- 50 projects
- All platforms
- 10 team members
- Priority support
- API access
- Annual: $159/month billed yearly (save 20%)

#### Business / Enterprise
- Custom pricing for agencies and large teams
- Unlimited brands and projects
- Custom team size
- All platforms + API access
- White-label option
- SSO and dedicated support
- Contact us: https://socialneuron.com/contact?plan=enterprise

### What Can Your Credits Buy?

**800 credits (Starter)**
- Approximately 53 AI images (at lowest cost model)
- Approximately 6-8 short AI videos
- Approximately 800 content ideas

**2,000 credits (Pro)**
- Approximately 133 AI images
- Approximately 16-20 short AI videos
- Approximately 2,000 content ideas

**6,500 credits (Team)**
- Approximately 433 AI images
- Approximately 54 short AI videos
- Approximately 6,500 content ideas

### Credit Add-Ons

Purchase additional credits anytime from Settings -> Billing.

| Add-On | Credits | Bonus | Total | Price | Per Credit |
|---|---|---|---|---|---|
| Credit Boost | 200 | +50 | 250 | $9.99 | $0.04 |
| Credit Pack | 500 | +50 | 550 | $9.99 | $0.018 |
| Credit Bundle | 1,500 | +200 | 1,700 | $24.99 | $0.015 |
| Credit Mega | 5,000 | +1,000 | 6,000 | $69.99 | $0.012 |

### Managing Your Credits

- View your remaining credits in the top navigation bar
- Check detailed usage history in Settings -> Billing
- Unused credits roll over for active subscriptions
- Purchase add-on credit packs anytime starting from $9.99
- Annual billing saves 20% compared to monthly

---

## 10. What's New

Recent updates and improvements to Social Neuron.

**March 2026 -- MCP Server v1.3.2 + HTTP Transport + OAuth 2.0 (60 Tools)** (Updated)
AI agents and developers can now control Social Neuron from Claude Code, Claude Desktop, or any MCP client. 60 tools across 23 modules covering ideation, content creation, distribution, analytics, brand management, comments, planning, autopilot, quality checks, pipeline management, and tool discovery. OAuth 2.0 + PKCE authentication. HTTP endpoint: https://mcp.socialneuron.com/mcp. Local install: npx -y @socialneuron/mcp-server. Requires paid plan (Starter $29/mo or higher).

**February 2026 -- TikTok Distribution (Live)** (New)
Publish videos directly to TikTok from Social Neuron. Full support for captions, privacy settings, and content disclosure. Content Posting API audit passed.

**February 2026 -- Real Analytics Data** (Improved)
Analytics dashboard now shows real performance data from connected platforms. Instagram and TikTok metrics (views, likes, shares) pulled from live APIs. Backfilled historical posts with fresh analytics.

**February 2026 -- Engagement Hub** (New)
Unified social inbox for managing comments across all connected platforms. View, reply, moderate, and track engagement from one place. Supports Instagram and YouTube with more platforms rolling out.

**January 2026 -- Automations & Autopilot** (New)
Visual flow builder for custom content workflows. Chain ideation, creation, and publishing steps together. Autopilot mode handles recurring content series on a schedule.

**January 2026 -- Storyboard Studio** (New)
End-to-end storyboard creation with four phases: script writing, scene planning, AI visual generation, and final video assembly with transitions and audio.

**January 2026 -- Avatar Lab v2** (Improved)
Redesigned avatar creation flow with more diverse AI presenters, improved voice synthesis, and better lip-sync accuracy for UGC-style videos.

**January 2026 -- Video Editor** (New)
Built-in video editor with trimming, captions, music, and multi-format export. Edit any generated video before publishing -- no external tools needed.

**December 2025 -- YouTube Distribution (Live)** (New)
Publish videos directly to YouTube from Social Neuron. Full support for titles, descriptions, tags, thumbnails, and scheduling.

**December 2025 -- AI Learning Loop** (Improved)
Performance data now feeds directly back into the ideation engine. Content suggestions improve based on what actually works for your audience.

**December 2025 -- Multi-Platform Distribution** (New)
Distribution hub supporting 7 platforms: YouTube (live), TikTok, Instagram, LinkedIn, X/Twitter, Facebook, and Threads. Additional platforms rolling out.

**November 2025 -- Generative Studio Upgrade** (Improved)
Added support for 35+ AI models including Midjourney, Flux Pro/Max, Sora 2, Runway, Veo 3, and more. Easy Mode and Pro Mode for all skill levels.

**November 2025 -- Repurpose Studio** (New)
Transform existing content into new formats. Turn long videos into short clips, convert blogs into video scripts, and extract highlights for social posts.

**October 2025 -- Credit System Accuracy** (Fixed)
Corrected credit pricing across all generation types to accurately reflect model costs. Added real-time cost previews before generation.

---

## 11. Frequently Asked Questions

### Getting Started

**What is Social Neuron?**
Social Neuron is an end-to-end AI content creation platform that handles the entire content lifecycle -- from ideation and creation to distribution and analytics. Performance data feeds back into the ideation engine so your content gets smarter over time.

**How does the platform work?**
Social Neuron uses a closed-loop workflow: Ideate -> Create -> Distribute -> Analyze -> Optimize. You start with AI-powered content ideas, create videos, images, or carousels, publish to your connected platforms, then the system analyzes performance and feeds insights back to improve future ideas.

**Do I need technical skills or design experience?**
Not at all. Social Neuron is built for non-technical users. Easy Mode lets you describe what you want in plain language and AI handles the rest. Pro Mode is there when you want more control, but it is completely optional.

**How long does setup take?**
About 5 minutes. Create your account, fill in your brand profile so the AI understands your voice, and connect your social accounts. You can start creating content immediately after.

**Is there a free plan?**
Yes! Social Neuron offers a free plan with 100 credits per month, forever. Create AI content, brainstorm ideas, and experience our learning loop -- no credit card required. When you need more credits or advanced features, upgrade anytime.

**What browsers are supported?**
Social Neuron works best in Chrome, Firefox, Safari, and Edge. We recommend using the latest version of your preferred browser for the best experience.

**Can I use Social Neuron on mobile?**
The platform is optimized for desktop use where you get the full creation suite. The dashboard and content library are responsive and work on mobile for reviewing content and checking analytics on the go.

**How do I invite team members?**
Go to Settings -> Organization and invite team members by email. Team member access is available on Pro and Team plans. Each member gets their own login with role-based permissions.

### AI & Content Quality

**Will the content look like generic AI slop?**
Social Neuron fights generic AI content three ways: (1) Brand Brain learns your unique voice from your website, past content, and brand guidelines. (2) You review and refine everything before publishing -- AI drafts, you decide. (3) Access to 20+ premium AI models means you are not locked to one style. The more you use it, the better it gets.

**How does Brand Brain match my voice?**
Brand Brain analyzes your brand profile, website, and past content to understand your tone, vocabulary, audience, and visual style. It then injects this context into every AI generation so the output sounds like you, not a robot.

**How is this different from ChatGPT or other AI tools?**
ChatGPT is a chat tool -- you get text responses. Social Neuron is an end-to-end platform that generates videos, images, and complete social posts, then publishes them to your accounts, tracks performance, and uses that data to improve future content. It is the difference between a calculator and an accounting system.

**What AI models power Social Neuron?**
We integrate 20+ premium AI models including Google Gemini, Midjourney, Flux, Sora, Runway, Veo, Ideogram, and more. Different models are best at different things -- our system automatically selects the right model for each task, or you can choose manually in Pro Mode.

**Can I edit the AI output before publishing?**
Yes, at every step. AI generates drafts -- you review, edit, regenerate, or approve before anything is published. The Video Editor lets you fine-tune cuts, captions, and timing. Nothing goes live without your explicit approval.

**How does the AI learning loop work?**
When you publish content through Social Neuron, the platform tracks how it performs (views, engagement, watch time). The research agent analyzes these patterns and feeds insights back to the ideation engine. Over time, your content suggestions become more aligned with what actually works for your audience.

**Can I choose which AI model to use?**
In Pro Mode, you can select from any available model for image or video generation. Each model has different strengths -- Midjourney for artistic images, Flux for photorealism, Veo for video, and so on. Easy Mode automatically picks the best model for your task.

**Does the content quality improve over time?**
Yes. The closed-loop system means the AI learns from your content's real-world performance. Ideas that lead to high engagement get reinforced, while underperforming patterns are deprioritized. Your Brand Brain profile also improves as you provide more feedback.

**Will AI replace my creative team?**
Social Neuron is designed to augment your team, not replace it. It handles the heavy lifting -- research, first drafts, image generation, formatting -- so your team can focus on strategy, creative direction, and the human touch that makes content resonate.

### Features & Capabilities

**What content types can I create?**
Videos (short-form and long-form), AI-generated images, photo carousels, talking-head avatar videos, storyboard animations, and text posts with captions and hashtags. You can also repurpose existing content into new formats.

**What is Ideation Station?**
Ideation Station is the AI-powered brainstorming engine with four modes: Research Mode for data-backed ideas, Brainstorm Mode for quick inspiration, Campaign Mode for cohesive content series, and Trends Mode for riding what is trending now.

**What are Automations?**
Automations let you build custom content workflows using a visual flow builder. Chain together ideation, creation, and publishing steps that run on a schedule or trigger. Autopilot mode handles recurring content series automatically.

**How does Storyboard Studio work?**
Storyboard Studio walks you through four phases: script writing, scene planning, visual generation, and final assembly. You get a complete video storyboard with AI-generated visuals, transitions, and audio -- then export as a finished video.

**Can I create avatar or UGC-style videos?**
Yes. Avatar Lab lets you create talking-head videos with AI presenters. Choose from diverse avatars, write or generate a script, and produce UGC-style videos complete with natural voice synthesis -- no camera required.

**What is Easy Mode vs Pro Mode?**
Easy Mode lets you describe what you want in plain language and the AI handles model selection, settings, and optimization. Pro Mode gives you full control over model choice, parameters, aspect ratios, and advanced settings. You can switch between them anytime.

**How does the Repurpose tool work?**
Repurpose takes existing content -- a long video, blog post, or article -- and transforms it into new formats. Turn a 10-minute video into short clips, convert a blog post into a video script, or extract highlights for social posts.

**What are Quick Wizards?**
Quick Wizards are one-click content generators. Paste a URL and get a video from any webpage, or paste a product page to auto-generate a product showcase. The AI extracts key information and builds a complete piece of content.

**Does Social Neuron have a video editor?**
Yes. The built-in Video Editor lets you trim, cut, add captions, adjust timing, add music, and export in multiple formats and aspect ratios. You can edit any generated video before publishing.

**How does Content Library work?**
Content Library is where all your generated content lives. Filter by type, status, or date. Preview, download, edit, or send content directly to distribution. Everything is organized by project and automatically saved.

### Pricing & Credits

**How does the credit system work?**
Social Neuron uses a simple credit system where 1 credit = $0.01. Different actions cost different amounts based on computational resources -- generating a text idea costs less than rendering a video. Your subscription includes a monthly credit allowance.

**What do credits buy?**
Content ideas and scripts start from 1 credit ($0.01). AI images start from 15 credits ($0.15). AI videos start from 80 credits ($0.80). Analysis and research start from 2 credits ($0.02). Costs vary by model -- premium models cost more but produce higher quality.

**What plans are available?**
Free forever with 100 credits/month. Starter at $29/month includes 800 credits. Pro at $79/month includes 2,000 credits with priority support. Team at $199/month includes 6,500 credits with multi-user access. Annual billing saves 20%. Enterprise plans are available for agencies.

**What if I run out of credits?**
You can purchase credit add-ons instantly from Settings -> Billing. Your work in progress is always saved automatically, so you will not lose anything. Add-on packs start from $9.99 for 250 credits.

**Can I cancel my subscription anytime?**
Yes, you can cancel your subscription at any time from your account settings. There are no cancellation fees or long-term commitments. If you cancel, you will retain access until the end of your current billing period.

**Do unused credits roll over?**
Yes, unused credits roll over month-to-month for active subscriptions. If you cancel, remaining credits are available until the end of your billing period.

**Is there an annual discount?**
Yes, annual billing saves 20% compared to monthly. Starter is $23/month billed annually, Pro is $63/month, and Team is $159/month.

**How can I estimate my monthly credit usage?**
Check Settings -> Billing for detailed usage history. As a reference: 800 credits (Starter) covers roughly 53 AI images or 8 short videos or 800 content ideas. 2,000 credits (Pro) covers roughly 133 AI images or 20 short videos.

**What happens if I go over my credit allowance?**
You can purchase add-on credit packs anytime starting from $9.99 for 250 credits. Spending caps prevent runaway costs: Starter cap is 2,000 credits/month, Pro cap is 5,000, and Team cap is 16,250.

### Platforms & Distribution

**What platforms are supported?**
YouTube and TikTok publishing are fully live. Instagram is pending Meta App Review approval. X/Twitter, LinkedIn, Threads, Facebook, and Bluesky are coming soon -- connect your accounts in Settings to get early access as each platform goes live.

**Can I post to multiple platforms at once?**
Yes. Select multiple connected accounts when publishing and Social Neuron will distribute your content to all of them. Each post is automatically formatted for that platform's requirements.

**Does it handle different format requirements?**
Yes. Each platform has different aspect ratios, length limits, and caption rules. Social Neuron automatically adjusts your content to meet each platform's specifications -- no manual reformatting needed.

**Can I schedule posts for later?**
Yes. Set a specific date and time for each post, or use Autopilot to maintain a consistent posting schedule. The system suggests optimal posting times based on your audience's activity patterns.

**How do I connect my social accounts?**
Go to Settings -> Connected Accounts and click the platform you want to add. You will be redirected to authorize access through the platform's official OAuth flow. We never store your passwords.

**What happens if a scheduled post fails?**
Failed posts are moved to a retry queue with a clear error message. You will get a notification and can retry, edit, or reschedule. The system automatically retries temporary failures.

**Can I preview posts before publishing?**
Yes. The distribution preview shows exactly how your content will appear on each platform -- including captions, thumbnails, and formatting. Review and adjust before anything goes live.

### Security, Privacy & Legal

**Who owns the content I create?**
You retain full ownership of all content you create with Social Neuron. Your content is yours to use commercially, publish, or modify however you choose.

**Is my data secure?**
Yes. We use industry-standard encryption for all stored data, Row Level Security on all database tables, OAuth for social account connections (we never store your passwords), and encrypted token storage for connected accounts.

**Is Social Neuron GDPR compliant?**
Yes. We follow GDPR requirements for data handling, provide data export and deletion capabilities, and process data in accordance with privacy regulations.

**Does AI-generated content comply with platform terms of service?**
Social Neuron is designed with platform compliance in mind. We recommend following each platform's disclosure guidelines for AI-generated content. The platform includes tips for proper AI content disclosure.

**What about copyright and intellectual property?**
AI-generated content copyright is an evolving legal landscape. Content you create with Social Neuron is yours to use, but we recommend consulting legal counsel for specific commercial use cases. We do not claim any rights to your generated content.

**How are my social account tokens protected?**
OAuth tokens are encrypted at rest using AES-256 encryption before storage. Tokens are only decrypted server-side when needed for publishing. We follow the principle of least privilege for all API access.

**Can I export or delete my data?**
Yes. You can download all your content from the Content Library at any time. For full account data export or deletion, contact support at socialneuronteam@gmail.com and we will process your request within 30 days.

### Social Media Growth

**How often should I post?**
We recommend 1-3 posts daily for maximum growth. Consistency matters more than volume -- it is better to post once every day than seven times on Monday and nothing the rest of the week. Automations can help you maintain a steady schedule.

**What content formats work best right now?**
Short-form video (under 60 seconds) consistently outperforms other formats across platforms. Photo carousels and educational content also drive strong engagement. Social Neuron's Trends Mode shows you what is working in your specific niche.

**Can I use AI-generated content for paid ads?**
Yes. AI-generated videos and images work well as ad creative for paid campaigns. Many brands use Social Neuron to produce high volumes of ad variations for testing -- the credit system makes it cost-effective to iterate.

**How do I warm up a new social media account?**
Spend 48-72 hours engaging organically before posting content -- scroll, like, comment, and follow accounts in your niche. This signals to the algorithm that you are a real user. Social Neuron's scheduling tools let you plan your first posts while you warm up.

**How do I track which content performs best?**
The Analytics dashboard shows performance metrics for all published content -- views, engagement, watch time, and growth trends. The AI learning loop automatically identifies patterns in your top-performing content and applies those insights to future suggestions.

---

## 12. Comparisons

- Social Neuron vs Jasper AI: https://socialneuron.com/compare/jasper
- Social Neuron vs HeyGen: https://socialneuron.com/compare/heygen
- Social Neuron vs Opus Clip: https://socialneuron.com/compare/opus-clip
- Social Neuron vs Sprout Social: https://socialneuron.com/compare/sprout-social
- Social Neuron vs Creatify: https://socialneuron.com/compare/creatify
- Social Neuron vs Descript: https://socialneuron.com/compare/descript
- Social Neuron vs Buffer: https://socialneuron.com/compare/buffer
- Compare all tools: https://socialneuron.com/compare/all

---

## 13. Use Cases

- **Content Creators**: Solo creators and influencers use Social Neuron to maintain a consistent posting schedule across multiple platforms without burning out. The AI handles research, first drafts, and formatting so creators can focus on their unique perspective and audience connection. Automations keep the content pipeline running even during busy weeks.

- **Marketing Teams**: Marketing departments use Social Neuron to scale content production without scaling headcount. Brand Brain ensures every piece of content matches brand guidelines regardless of who initiates it. The analytics learning loop helps teams double down on what is working and stop wasting budget on underperforming formats.

- **Agencies**: Agencies managing multiple client accounts use Social Neuron to separate brands into distinct projects with their own Brand Brain profiles. The Team plan supports multi-user collaboration with approval workflows, so junior staff can create content that gets reviewed before publishing. White-label options are available on Enterprise plans.

- **Small Businesses**: Small business owners who cannot afford a dedicated marketing team use Social Neuron as their content department. Easy Mode requires zero design experience -- describe your product or promotion in plain language and get professional videos and posts ready to publish. The credit system means you only pay for what you use.

---

## 14. Technical Information

- **Browser support**: Chrome, Firefox, Safari, Edge (latest versions)
- **Mobile**: Dashboard and content library are responsive; creation suite is optimized for desktop
- **Data security**: Encryption at rest, Row Level Security, OAuth for social connections, encrypted token storage (AES-256)
- **Compliance**: GDPR compliant, ICO registered (United Kingdom)
- **Content ownership**: Users retain full ownership of all generated content
- **Uptime**: Production infrastructure with automatic failover
- **Company**: Cosmocodex Ltd, United Kingdom

---

## 15. Links

- [Home](https://socialneuron.com/)
- [Pricing](https://socialneuron.com/pricing)
- [Demo](https://socialneuron.com/demo)
- [Help Center](https://socialneuron.com/help)
- [About](https://socialneuron.com/about)
- [Contact](https://socialneuron.com/contact)
- [Compare vs Jasper](https://socialneuron.com/compare/jasper)
- [Compare vs HeyGen](https://socialneuron.com/compare/heygen)
- [Compare vs Opus Clip](https://socialneuron.com/compare/opus-clip)
- [Compare vs Sprout Social](https://socialneuron.com/compare/sprout-social)
- [Compare vs Creatify](https://socialneuron.com/compare/creatify)
- [Compare vs Descript](https://socialneuron.com/compare/descript)
- [Compare vs Buffer](https://socialneuron.com/compare/buffer)
- [Compare All](https://socialneuron.com/compare/all)
- [Privacy Policy](https://socialneuron.com/privacy)
- [Terms of Service](https://socialneuron.com/terms)
- [Security](https://socialneuron.com/security)
- [Cookie Policy](https://socialneuron.com/cookies)
- [Data Deletion](https://socialneuron.com/data-deletion)
- [For Developers](https://socialneuron.com/for-developers)
- [Documentation](https://socialneuron.com/docs)
- [npm Package](https://www.npmjs.com/package/@socialneuron/mcp-server)

---

## 16. Agent & Developer API

### System Prompt

Copy the contents of https://socialneuron.com/system-prompt.txt into your agent's system prompt for optimal MCP integration. It includes the recommended protocol, CORRECT/WRONG patterns, and common workflows.

### Tool Reference (63 tools across 24 modules)

#### Analytics (2 tools)

##### fetch_analytics
Get post performance metrics — views, likes, comments, shares, and engagement rate. Filter by platform, time range (default 30 days), or specific content_id. Call refresh_platform_analytics first if data seems stale. Results sorted by most recent capture.
- Scope: mcp:analytics | Credits: ~0

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| platform | enum: youtube, tiktok, instagram, twitter, linkedin, facebook, threads, bluesky,  | No | Filter analytics to a specific platform. |
| days | number (1-365) | No | Lookback window in days (1-365). Default 30. Use 7 for weekly review, 30 for monthly summary, 90 for quarterly trends. |
| content_id | string (UUID) | No | Filter to a specific content_history ID to see performance of one piece of content. |
| limit | number (1-100) | No | Maximum number of posts to return. Defaults to 20. |
| response_format | enum: text, json | No | Optional response format. Defaults to text. |

##### refresh_platform_analytics
Queue analytics refresh jobs for all posts from the last 7 days across connected platforms. Call this before fetch_analytics if you need fresh data. Returns immediately — data updates asynchronously over the next 1-5 minutes.
- Scope: mcp:analytics | Credits: ~0

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| response_format | enum: text, json | No | Optional response format. Defaults to text. |

#### Autopilot (4 tools)

##### list_autopilot_configs
List autopilot configurations showing schedules, credit budgets, last run times, and active/inactive status. Use to check what is automated before creating new configs, or to find config_id for update_autopilot_config.
- Scope: mcp:autopilot | Credits: ~0

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| active_only | boolean | No | If true, only return active configs. Defaults to false (show all). |
| response_format | enum: text, json | No | Optional response format. Defaults to text. |

##### update_autopilot_config
Update an existing autopilot configuration. Can enable/disable, change schedule, or modify credit budgets.
- Scope: mcp:autopilot | Credits: ~0

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| config_id | string (UUID) | Yes | The autopilot config ID to update. |
| is_active | boolean | No | Enable or disable this autopilot config. |
| schedule_days | enum: mon, tue, wed, thu, fri, sat, sun | No | Days of the week to run (e.g., ["mon", "wed", "fri"]). |
| schedule_time | string | No | Time to run in HH:MM format (24h, user timezone). E.g., "09:00". |
| max_credits_per_run | number | No | Maximum credits per execution. |
| max_credits_per_week | number | No | Maximum credits per week. |

##### get_autopilot_status
Get autopilot system overview: active config count, recent execution results, credits consumed, and next scheduled run time. Use as a dashboard check before modifying autopilot settings.
- Scope: mcp:autopilot | Credits: ~0

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| response_format | enum: text, json | No | Optional response format. Defaults to text. |

##### create_autopilot_config
Create a new autopilot configuration for automated content pipeline execution. Defines schedule, credit budgets, and approval mode.
- Scope: mcp:autopilot | Credits: ~0

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| name | string (1-100 chars) | Yes | Name for this autopilot config |
| project_id | string (UUID) | Yes | Project to run autopilot for |
| mode | enum: recipe, pipeline | Yes | Mode: recipe (legacy) or pipeline (new orchestration) |
| schedule_days | enum: mon, tue, wed, thu, fri, sat, sun | Yes | Days of the week to run |
| schedule_time | string | Yes | Time to run in HH:MM format (24h). E.g., "09:00" |
| timezone | string | No | Timezone (e.g., "America/New_York"). Defaults to UTC. |
| max_credits_per_run | number (min 0) | No | Maximum credits per execution |
| max_credits_per_week | number (min 0) | No | Maximum credits per week |
| approval_mode | enum: auto, review_all, review_low_confidence | Yes | How to handle post approvals |
| is_active | boolean | Yes | Whether to activate immediately |
| response_format | enum: text, json | No | Response format. Defaults to text. |

#### Brand (4 tools)

##### extract_brand
Analyze a website URL and extract brand identity data including brand name, colors, voice/tone, target audience, and logo. Uses AI-powered analysis of the page HTML. Useful for understanding a brand before generating content for it.
- Scope: mcp:read/write | Credits: ~0-3

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| url | string (URL) | Yes | The website URL to analyze for brand identity ' + '(e.g. "https://example.com"). |
| response_format | enum: text, json | No | Optional response format. Defaults to text. |

##### get_brand_profile
Load the active persisted brand profile for a project from brand_profiles.
- Scope: mcp:read/write | Credits: ~0-3

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| project_id | string (UUID) | No | Project ID. Defaults to active project context. |
| response_format | enum: text, json | No | Optional response format. Defaults to text. |

##### save_brand_profile
Persist a brand profile as the active profile for a project.
- Scope: mcp:read/write | Credits: ~0-3

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| project_id | string (UUID) | No | Project ID. Defaults to active project context. |
| brand_context | string | Yes | Brand context payload to save to brand_profiles.brand_context. |
| change_summary | string (max 500) | No | Optional summary of changes. |
| changed_paths | string | No | Optional changed path list. |
| source_url | string (URL) | No | Optional source URL for provenance. |
| extraction_method | enum: manual, url_extract, business_profiler, product_showcase | No | Extraction method metadata. |
| overall_confidence | number (0-1) | No | Optional overall confidence score in range 0..1. |
| extraction_metadata | string | No |  |
| response_format | enum: text, json | No |  |

##### update_platform_voice
Update platform-specific voice overrides (samples, tone/style, CTA/hashtag strategy).
- Scope: mcp:read/write | Credits: ~0-3

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| platform | enum: youtube, tiktok, instagram, twitter, linkedin, facebook, threads, bluesky,  | Yes |  |
| project_id | string (UUID) | No | Project ID. Defaults to active project context. |
| samples | string (max 3000) | No | 3-5 real platform post examples for style anchoring. |
| tone | string | No |  |
| style | string | No |  |
| avoid_patterns | string | No |  |
| hashtag_strategy | string (max 300) | No |  |
| cta_style | string (max 300) | No |  |
| response_format | enum: text, json | No |  |

#### brandRuntime (3 tools)

##### get_brand_runtime
Get the full brand runtime for a project. Returns the 4-layer brand system: messaging (value props, pillars, proof points), voice (tone, vocabulary, avoid patterns), visual (palette, typography, composition), and operating constraints (audience, archetype). Also returns extraction confidence metadata.
- Scope: mcp:read | Credits: ~0

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| project_id | string | No | Project ID. Defaults to current project. |

##### explain_brand_system
Explains what brand data is available vs missing for a project. Returns a human-readable summary of completeness, confidence levels, and recommendations for improving the brand profile.
- Scope: mcp:read | Credits: ~0

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| project_id | string | No | Project ID. Defaults to current project. |

##### check_brand_consistency
Check if content text is consistent with the brand voice, vocabulary, messaging, and factual claims. Returns per-dimension scores (0-100) and specific issues found. Use this to validate scripts, captions, or post copy before publishing.
- Scope: mcp:read | Credits: ~0

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| content | string | Yes | The content text to check for brand consistency. |
| project_id | string | No | Project ID. Defaults to current project. |

#### Comments (5 tools)

##### list_comments
List YouTube comments — pass video_id (11-char string, e.g. dQw4w9WgXcQ) for a specific video, or omit for recent comments across all channel videos. Returns comment text, author, like count, and reply count. Use page_token from previous response for pagination.
- Scope: mcp:comments | Credits: ~0-1

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| video_id | string | No | YouTube video ID — the 11-character string from the URL (e.g. "dQw4w9WgXcQ" from youtube.com/watch?v=dQw4w9WgXcQ). Omit to get recent comments across all channel videos. |
| max_results | number (1-100) | No | Maximum number of comments to return. Defaults to 50. |
| page_token | string | No | Pagination cursor from previous list_comments response nextPageToken field. Omit for first page of results. |
| response_format | enum: text, json | No | Optional response format. Defaults to text. |

##### reply_to_comment
Reply to a YouTube comment. Get the parent_id from list_comments results. Reply appears as the authenticated channel. Use for community engagement after checking list_comments for questions or feedback.
- Scope: mcp:comments | Credits: ~0-1

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| parent_id | string | Yes | The ID of the parent comment to reply to (from list_comments). |
| text | string (min 1) | Yes | The reply text. |
| response_format | enum: text, json | No | Optional response format. Defaults to text. |

##### post_comment
Post a new top-level comment on a YouTube video.
- Scope: mcp:comments | Credits: ~0-1

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| video_id | string | Yes | The YouTube video ID to comment on. |
| text | string (min 1) | Yes | The comment text. |
| response_format | enum: text, json | No | Optional response format. Defaults to text. |

##### moderate_comment
Moderate a YouTube comment by setting its status to published or rejected.
- Scope: mcp:comments | Credits: ~0-1

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| comment_id | string | Yes | The comment ID to moderate. |
| moderation_status | enum: published, rejected | Yes | "published" to approve, "rejected" to hide. |
| response_format | enum: text, json | No | Optional response format. Defaults to text. |

##### delete_comment
Delete a YouTube comment. Only works for comments owned by the authenticated channel.
- Scope: mcp:comments | Credits: ~0-1

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| comment_id | string | Yes | The comment ID to delete. |
| response_format | enum: text, json | No | Optional response format. Defaults to text. |

#### Content (6 tools)

##### generate_video
Start an async AI video generation job — returns a job_id immediately. Poll with check_status every 10-30s until complete. Cost varies by model: veo3-fast (~15 credits/5s), kling-3 (~30 credits/5s), sora2-pro (~60 credits/10s). Check get_credit_balance first for expensive generations.
- Scope: mcp:write | Credits: ~5-50

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| prompt | string (max 2500) | Yes | Video prompt — be specific about visual style, camera movement, lighting, and mood. Example: "Aerial drone shot of coastal cliffs at golden hour, slow dolly forward, cinematic 24fps, warm color grading." Vague prompts produce generic results. |
| model | enum: veo3-fast, veo3-quality, runway-aleph, sora2, sora2-pro, kling, kling-3, kling-3-pro,  | Yes | Video model. veo3-fast: fastest (~15 credits/5s, ~60s render). veo3-quality: highest quality (~20 credits/5s, ~120s). sora2-pro: OpenAI premium (~60 credits/10s). kling-3: 4K with audio (~30 credits/5s). kling-3-pro: best Kling quality (~40 credits/5s). |
| duration | number (3-30) | No | Video duration in seconds. kling: 5-30s, kling-3/kling-3-pro: 3-15s, ' + 'sora2: 10-15s. Defaults to 5 seconds. |
| aspect_ratio | enum: 16:9, 9:16, 1:1 | No | Video aspect ratio. 16:9 for YouTube/landscape, 9:16 for TikTok/Reels/Shorts, 1:1 for Instagram feed/square. Defaults to 16:9. |
| enable_audio | boolean | No | Enable native audio generation. Kling 2.6: doubles cost. ' + 'Kling 3.0: 50% more (std 30/sec, pro 40/sec). 5+ languages. |
| image_url | string | No | Start frame image URL for image-to-video (Kling 3.0 frame control). |
| end_frame_url | string | No | End frame image URL (Kling 3.0 only). Enables seamless loop transitions. |
| response_format | enum: text, json | No | Optional response format. Defaults to text. |

##### generate_image
Start an async AI image generation job — returns a job_id immediately. Poll with check_status every 5-15s until complete. Costs 2-10 credits depending on model. Use for social media posts, carousel slides, or as input to generate_video (image-to-video).
- Scope: mcp:write | Credits: ~5-50

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| prompt | string (max 2000) | Yes | Text prompt describing the image to generate. Be specific about style, ' + 'composition, colors, lighting, and subject matter. |
| model | enum: midjourney, nano-banana, nano-banana-pro, flux-pro, flux-max, gpt4o-image, imagen4, imagen4-fast, seedream,  | Yes | Image generation model. midjourney for artistic style, imagen4 for ' + 'photorealistic quality, flux-pro for general purpose, gpt4o-image ' + 'for creative/illustrated styles. |
| aspect_ratio | enum: 16:9, 9:16, 1:1, 4:3, 3:4 | No | Aspect ratio. Defaults to 1:1 (square). |
| image_url | string | No | Reference image URL for image-to-image generation. Required for ' + 'ideogram model. Optional for others. |
| response_format | enum: text, json | No | Optional response format. Defaults to text. |

##### check_status
Poll an async job started by generate_video or generate_image. Returns status (queued/processing/completed/failed), progress %, and result URL on completion. Poll every 10-30s for video, 5-15s for images. On failed status, the error field explains why — check credits or try a different model.
- Scope: mcp:write | Credits: ~5-50

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| job_id | string | Yes | The job ID returned by generate_video or generate_image. ' + 'This is the asyncJobId or taskId value. |
| response_format | enum: text, json | No | Optional response format. Defaults to text. |

##### create_storyboard
Plan a multi-scene video storyboard with AI-generated prompts, durations, captions, and voiceover text per frame. Use before generate_video or generate_image to create cohesive multi-shot content. Include brand_context from get_brand_profile for consistent visual branding across frames.
- Scope: mcp:write | Credits: ~5-50

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| concept | string (max 2000) | Yes | The video concept/idea. Include: hook, key messages, target audience, ' + 'and desired outcome (e.g., "TikTok ad for VPN app targeting ' + 'privacy-conscious millennials, hook with shocking stat about data leaks"). |
| brand_context | string (max 3000) | No | Brand context JSON from extract_brand. Include colors, voice tone, ' + 'visual style keywords for consistent branding across frames. |
| platform | enum: tiktok, instagram-reels, youtube-shorts, youtube, general | Yes | Target platform. Determines aspect ratio, duration, and pacing. |
| target_duration | number (5-120) | No | Target total duration in seconds. Defaults to 30s for short-form, 60s for YouTube. |
| num_scenes | number (3-15) | No | Number of scenes. Defaults to 6-8 for short-form. |
| style | string | No | Visual style direction (e.g., "cinematic", "anime", "documentary", "motion graphics"). |
| response_format | enum: text, json | No | Response format. Defaults to json for structured storyboard data. |

##### generate_voiceover
Generate a voiceover audio file for video narration. Returns an R2-hosted audio URL. Use after create_storyboard to add narration to each scene, or standalone for podcast intros and ad reads. Costs ~2 credits per generation.
- Scope: mcp:write | Credits: ~5-50

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| text | string (max 5000) | Yes | The script/text to convert to speech. |
| voice | enum: rachel, drew, clyde, paul, domi, dave, fin, sarah, antoni, thomas, charlie,  | No | Voice selection. rachel=warm female, drew=confident male, ' + 'paul=authoritative male, sarah=friendly female. Defaults to rachel. |
| speed | number | No | Speech speed multiplier. 1.0 is normal. Defaults to 1.0. |
| response_format | enum: text, json | No | Response format. Defaults to text. |

##### generate_carousel
Generate carousel slide content (headlines, body text, emphasis words per slide). Supports Hormozi-style authority format and educational templates. Returns structured slide data — render visually then publish via schedule_post with media_type=CAROUSEL_ALBUM and 2-10 media_urls on Instagram.
- Scope: mcp:write | Credits: ~5-50

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| topic | string (max 200) | Yes | Carousel hook/angle — specific beats general. Example: "5 pricing mistakes that kill SaaS startups" beats "SaaS tips". Include a curiosity gap or strong opinion for better Hook Strength scores. |
| template_id | enum: educational-series, product-showcase, story-arc, before-after, step-by-step, quote-collection, data-stats, myth-vs-reality, hormozi-authority,  | No | Carousel template. hormozi-authority: bold typography, one idea per slide, ' + 'dark backgrounds. educational-series: numbered tips. Default: hormozi-authority. |
| slide_count | number (3-10) | No | Number of slides (3-10). Default: 7. |
| aspect_ratio | enum: 1:1, 4:5, 9:16 | No | Aspect ratio. 1:1 square (default), 4:5 portrait, 9:16 story. |
| style | enum: minimal, bold, professional, playful, hormozi | No | Visual style. hormozi: black bg, bold white text, gold accents. ' + 'Default: hormozi (when using hormozi-authority template). |
| project_id | string | No | Project ID to associate the carousel with. |
| response_format | enum: text, json | No | Response format. Defaults to json. |

#### Credits (2 tools)

##### get_credit_balance
Check remaining credits, monthly limit, spending cap, and plan tier. Call this before expensive operations — generate_video costs 15-80 credits, generate_image costs 2-10. Returns current balance, monthly allocation, and spending cap (2.5x allocation).
- Scope: mcp:read | Credits: ~0

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| response_format | enum: text, json | No | Optional response format. Defaults to text. |

##### get_budget_status
Check how much of the per-session budget has been consumed. Tracks credits spent and assets created in this MCP session against configured limits. Use to avoid hitting budget caps mid-workflow.
- Scope: mcp:read | Credits: ~0

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| response_format | enum: text, json | No | Optional response format. Defaults to text. |

#### digest (2 tools)

##### generate_performance_digest
Generate a performance summary for a time period. Includes metrics, trends vs previous period, top/bottom performers, platform breakdown, and actionable recommendations. No AI call, no credit cost.
- Scope: mcp:read | Credits: ~0

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| project_id | string (UUID) | No | Project ID (auto-detected if omitted) |
| period | enum: 7d, 14d, 30d | Yes | Time period to analyze |
| include_recommendations | boolean | Yes |  |
| response_format | enum: text, json | No |  |

##### detect_anomalies
Detect significant performance changes: spikes, drops, viral content, trend shifts. Compares current period against previous equal-length period. No AI call, no credit cost.
- Scope: mcp:read | Credits: ~0

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| project_id | string (UUID) | No | Project ID (auto-detected if omitted) |
| days | number (7-90) | Yes | Days to analyze |
| sensitivity | enum: low, medium, high | Yes | Detection sensitivity: low=50%+, medium=30%+, high=15%+ changes |
| platforms | array | No | Filter to specific platforms |
| response_format | enum: text, json | No |  |

#### discovery (1 tool)

##### search_tools
Search available tools by name, description, module, or scope. Use name detail (~50 tokens) for quick lookup, summary (~500 tokens) for descriptions, full for complete input schemas. Start here if unsure which tool to call — filter by module (e.g. planning, content, analytics) to narrow results.
- Scope: mcp:read | Credits: ~0

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| query | string | No | Search query to filter tools by name or description |
| module | string | No | Filter by module name (e.g. "planning", "content", "analytics") |
| scope | string | No | Filter by required scope (e.g. "mcp:read", "mcp:write") |
| detail | enum: name, summary, full | Yes | Detail level: "name" for just tool names, "summary" for names + descriptions, "full" for complete info including scope and module |

#### Distribution (5 tools)

##### schedule_post
Publish or schedule a post to connected social platforms. Check list_connected_accounts first to verify active OAuth for each target platform. For Instagram carousels: use media_type=CAROUSEL_ALBUM with 2-10 media_urls. For YouTube: title is required. schedule_at uses ISO 8601 (e.g. 2026-03-20T14:00:00Z) — omit to post immediately.
- Scope: mcp:distribute | Credits: ~1-3

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| media_url | string | No | Optional URL of the media file (video or image) to post. This should be a ' + 'publicly accessible URL or a Cloudflare R2 signed URL from a previous generation. ' + 'Required for platforms that enforce media uploads. Not needed if media_urls is provided. |
| media_urls | string | No | Array of 2-10 image URLs for Instagram carousel posts. Each URL must be publicly accessible or a Cloudflare R2 signed URL. Use with media_type=CAROUSEL_ALBUM. |
| media_type | enum: IMAGE, VIDEO, CAROUSEL_ALBUM | No | Media type. Set to CAROUSEL_ALBUM with media_urls for Instagram carousels. ' + 'Default: auto-detected from media_url. |
| caption | string | No | Post caption/description text. |
| platforms | enum: youtube, tiktok, instagram, twitter, linkedin, facebook, threads, bluesky,  | Yes | Target platforms (array). Each must have active OAuth — check list_connected_accounts first. Values: youtube, tiktok, instagram, twitter, linkedin, facebook, threads, bluesky. |
| title | string | No | Post title (used by YouTube and some other platforms). |
| hashtags | string | No | Hashtags to append to caption. Include or omit the "#" prefix — both work. Example: ["ai", "contentcreator"] or ["#ai", "#contentcreator"]. |
| schedule_at | string | No | ISO 8601 UTC datetime for scheduled posting (e.g. "2026-03-20T14:00:00Z"). Omit to post immediately. Must be in the future. |
| project_id | string | No | Social Neuron project ID to associate this post with. |
| response_format | enum: text, json | No | Optional response format. Defaults to text. |
| attribution | boolean | No | If true, appends "Created with Social Neuron" to the caption. Default: false. |

##### list_connected_accounts
Check which social platforms have active OAuth connections for posting. Call this before schedule_post to verify credentials. If a platform is missing or expired, the user needs to reconnect at socialneuron.com/settings/connections.
- Scope: mcp:distribute | Credits: ~1-3

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| response_format | enum: text, json | No | Optional response format. Defaults to text. |

##### list_recent_posts
List recent published and scheduled posts with status, platform, title, and timestamps. Use to check what has been posted before planning new content, or to find post IDs for fetch_analytics. Filter by platform or status to narrow results.
- Scope: mcp:distribute | Credits: ~1-3

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| platform | enum: youtube, tiktok, instagram, twitter, linkedin, facebook, threads, bluesky,  | No | Filter to a specific platform. |
| status | enum: draft, scheduled, published, failed | No | Filter by post status. |
| days | number (1-90) | No | Number of days to look back. Defaults to 7. Max 90. |
| limit | number (1-50) | No | Maximum number of posts to return. Defaults to 20. |
| response_format | enum: text, json | No | Optional response format. Defaults to text. |

##### find_next_slots
Find optimal posting time slots based on best posting times and existing schedule. Returns non-conflicting slots sorted by engagement score.
- Scope: mcp:distribute | Credits: ~1-3

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| platforms | enum: youtube, tiktok, instagram, twitter, linkedin, facebook, threads, bluesky,  | Yes |  |
| count | number (1-20) | Yes | Number of slots to find |
| start_after | string | No | ISO datetime, defaults to now |
| min_gap_hours | number (1-24) | Yes | Minimum gap between posts on same platform |
| response_format | enum: text, json | Yes |  |

##### schedule_content_plan
Schedule all posts in a content plan. Optionally auto-assigns time slots and runs quality checks before scheduling. Supports dry-run mode.
- Scope: mcp:distribute | Credits: ~1-3

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| plan | string | No |  |
| plan_id | string (UUID) | No | Persisted content plan ID from content_plans table |
| auto_slot | boolean | Yes | Auto-assign time slots for posts without schedule_at |
| dry_run | boolean | Yes | Preview without actually scheduling |
| response_format | enum: text, json | Yes |  |
| enforce_quality | boolean | Yes | When true, block scheduling for posts that fail quality checks. |
| quality_threshold | number (0-35) | No | Optional quality threshold override. Defaults to project setting or 26. |
| batch_size | number (1-10) | Yes | Concurrent schedule calls per platform batch. |
| idempotency_seed | string (max 128) | No | Optional stable seed used when building idempotency keys. |

#### Extraction (1 tool)

##### extract_url_content
Extract text content from any URL — YouTube video transcripts, article text, or product page features/benefits/USP. YouTube URLs auto-route to transcript extraction with optional comments. Use before generate_content to repurpose existing content, or before plan_content_week to base a content plan on a source URL.
- Scope: mcp:read | Credits: ~0-1

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| url | string (URL) | Yes | URL to extract content from |
| extract_type | enum: auto, transcript, article, product | Yes | Type of extraction |
| include_comments | boolean | Yes | Include top comments (YouTube only) |
| max_results | number (1-100) | Yes | Max comments to include |
| response_format | enum: text, json | Yes |  |

#### Ideation Context (1 tool)

##### get_ideation_context
Get synthesized ideation context from performance insights. Returns the same prompt-injection context used by ideation generation.
- Scope: mcp:read | Credits: ~0

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| project_id | string (UUID) | No | Project ID to scope insights. |
| days | number (1-90) | No | Lookback window for insights. Defaults to 30 days. |
| response_format | enum: text, json | No | Optional output format. Defaults to text. |

#### Ideation (3 tools)

##### generate_content
Create a script, caption, hook, or blog post tailored to a specific platform. Pass project_id to auto-load brand profile and performance context, or call get_ideation_context first for full context. Output is draft text ready for quality_check then schedule_post.
- Scope: mcp:write | Credits: ~1-5

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| prompt | string (max 10000) | Yes | Detailed content prompt. Include topic, angle, audience, and requirements. Example: "LinkedIn post about AI productivity for CTOs, 300 words, include 3 actionable tips, conversational tone." Richer prompts produce better results. |
| content_type | enum: script, caption, blog, hook | Yes | Type of content to generate. "script" for video scripts, "caption" for ' + 'social media captions, "blog" for blog posts, "hook" for attention-grabbing hooks. |
| platform | enum: youtube, tiktok, instagram, twitter, linkedin, facebook, threads, bluesky,  | No | Target social media platform. Helps tailor tone, length, and format. |
| brand_voice | string (max 500) | No | Tone directive (e.g. "direct, no jargon, second person" or "witty Gen-Z energy with emoji"). Leave blank to auto-load from project brand profile if project_id is set. |
| model | enum: gemini-2.0-flash, gemini-2.5-flash, gemini-2.5-pro | No | AI model to use. Defaults to gemini-2.5-flash. Use gemini-2.5-pro for highest quality. |
| project_id | string (UUID) | No | Project ID to auto-load brand profile and performance context for prompt enrichment. |

##### fetch_trends
Get current trending topics for content inspiration. Source youtube returns trending videos with view counts, google_trends returns rising search terms, rss/url extracts topics from any feed or page. Results cached 1 hour — set force_refresh=true for real-time. Feed results into generate_content or plan_content_week.
- Scope: mcp:write | Credits: ~1-5

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| source | enum: youtube, google_trends, rss, url | Yes | Data source. "youtube" fetches trending videos, "google_trends" fetches ' + 'daily search trends, "rss" fetches from a custom RSS feed URL, "url" ' + 'extracts trend data from a web page. |
| category | string | No | Category filter (for YouTube). Examples: general, entertainment, ' + 'education, tech, music, gaming, sports, news. |
| niche | string | No | Niche keyword filter. Only return trends matching these keywords. |
| url | string | No | Required when source is "rss" or "url". The feed or page URL to fetch. |
| force_refresh | boolean | No | Skip the server-side cache and fetch fresh data. |

##### adapt_content
Rewrite existing content for a different platform — adjusts character limits, hashtag style, tone, and CTA format automatically. Use after generate_content when you need the same message across multiple platforms. Pass project_id to apply platform-specific voice overrides from your brand profile.
- Scope: mcp:write | Credits: ~1-5

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| content | string (max 5000) | Yes | The content to adapt. Can be a caption, script, blog excerpt, or any text. |
| source_platform | enum: youtube, tiktok, instagram, twitter, linkedin, facebook, threads, bluesky,  | No | The platform the content was originally written for. Helps preserve intent. |
| target_platform | enum: youtube, tiktok, instagram, twitter, linkedin, facebook, threads, bluesky,  | Yes | The platform to adapt the content for. |
| brand_voice | string (max 500) | No | Brand voice guidelines to maintain during adaptation (e.g. "professional", "playful"). |
| project_id | string (UUID) | No | Optional project ID to load platform voice overrides from brand profile. |

#### Insights (2 tools)

##### get_performance_insights
Query performance insights derived from post analytics. Returns metrics like engagement rate, view velocity, and click rate aggregated over time. Use this to understand what content is performing well.
- Scope: mcp:analytics | Credits: ~0

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| insight_type | enum: top_hooks, optimal_timing, best_models, competitor_patterns | No | Filter to a specific insight type. |
| days | number (1-90) | No | Number of days to look back. Defaults to 30. Max 90. |
| limit | number (1-50) | No | Maximum number of insights to return. Defaults to 10. |
| response_format | enum: text, json | No | Optional response format. Defaults to text. |

##### get_best_posting_times
Analyze post analytics data to find the best times to post for maximum engagement. Returns the top 5 time slots (day of week + hour) ranked by average engagement.
- Scope: mcp:analytics | Credits: ~0

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| platform | enum | No | Filter to a specific platform. |
| days | number (1-90) | No | Number of days to analyze. Defaults to 30. Max 90. |
| response_format | enum: text, json | No | Optional response format. Defaults to text. |

#### Loop Summary (1 tool)

##### get_loop_summary
Get a one-call dashboard summary of the feedback loop state (brand profile, recent content, and current insights).
- Scope: mcp:read | Credits: ~0

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| project_id | string (UUID) | No | Project ID. Defaults to active project context. |
| response_format | enum: text, json | No | Optional response format. Defaults to text. |

#### pipeline (4 tools)

##### check_pipeline_readiness
Pre-flight check before run_content_pipeline. Verifies: sufficient credits for estimated_posts, active OAuth on target platforms, brand profile exists, no stale insights. Returns pass/fail with specific issues to fix before running the pipeline.
- Scope: mcp:read | Credits: ~0

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| project_id | string (UUID) | No | Project ID (auto-detected if omitted) |
| platforms | array | Yes | Target platforms to check |
| estimated_posts | number (1-50) | Yes | Estimated posts to generate |
| response_format | enum: text, json | No | Response format |

##### run_content_pipeline
Run the full content pipeline: research trends → generate plan → quality check → auto-approve → schedule posts. Chains all stages in one call for maximum efficiency. Set dry_run=true to preview the plan without publishing. Check check_pipeline_readiness first to verify credits, OAuth, and brand profile are ready.
- Scope: mcp:read | Credits: ~0

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| project_id | string (UUID) | No | Project ID (auto-detected if omitted) |
| topic | string | No | Content topic (required if no source_url) |
| source_url | string | No | URL to extract content from |
| platforms | array | Yes | Target platforms |
| days | number (1-7) | Yes | Days to plan |
| posts_per_day | number (1-3) | Yes | Posts per platform per day |
| approval_mode | enum: auto, review_all, review_low_confidence | Yes | auto: approve all passing quality. review_all: flag everything. review_low_confidence: auto-approve high scorers. |
| auto_approve_threshold | number (0-35) | Yes | Quality score threshold for auto-approval (used in auto/review_low_confidence modes) |
| max_credits | number | No | Credit budget cap |
| dry_run | boolean | Yes | If true, skip scheduling and return plan only |
| skip_stages | enum: research, quality, schedule | No | Stages to skip |
| response_format | enum: text, json | Yes |  |

##### get_pipeline_status
Check status of a pipeline run, including stages completed, pending approvals, and scheduled posts.
- Scope: mcp:read | Credits: ~0

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| pipeline_id | string (UUID) | No | Pipeline run ID (omit for latest) |
| response_format | enum: text, json | No |  |

##### auto_approve_plan
Batch auto-approve posts in a content plan that meet quality thresholds. Posts below the threshold are flagged for manual review.
- Scope: mcp:read | Credits: ~0

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| plan_id | string (UUID) | Yes | Content plan ID |
| quality_threshold | number (0-35) | Yes | Minimum quality score to auto-approve |
| response_format | enum: text, json | Yes |  |

#### Plan Approvals (3 tools)

##### create_plan_approvals
Create pending approval rows for each post in a content plan.
- Scope: mcp:write | Credits: ~0

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| plan_id | string (UUID) | Yes | Content plan ID |
| posts | string (min 1) | No | Posts to create approval entries for. |
| project_id | string (UUID) | No | Project ID. Defaults to active project context. |
| response_format | enum: text, json | No |  |

##### list_plan_approvals
List MCP-native approval items for a specific content plan.
- Scope: mcp:write | Credits: ~0

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| plan_id | string (UUID) | Yes | Content plan ID |
| status | enum: pending, approved, rejected, edited | No |  |
| response_format | enum: text, json | No |  |

##### respond_plan_approval
Approve, reject, or edit a pending plan approval item.
- Scope: mcp:write | Credits: ~0

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| approval_id | string (UUID) | Yes | Approval item ID |
| decision | enum: approved, rejected, edited | Yes |  |
| edited_post | string | No |  |
| reason | string (max 1000) | No |  |
| response_format | enum: text, json | No |  |

#### Planning (5 tools)

##### plan_content_week
Generate a full content plan with platform-specific drafts, hooks, angles, and optimal schedule times. Pass a topic or source_url — brand context and performance insights auto-load via project_id. Output feeds directly into quality_check_plan then schedule_content_plan. Costs ~5-15 credits depending on post count.
- Scope: mcp:write | Credits: ~1-3

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| topic | string | Yes | Main topic or content theme |
| source_url | string | No | URL to extract content from (YouTube, article) |
| platforms | enum: youtube, tiktok, instagram, twitter, linkedin, facebook, threads, bluesky,  | Yes | Target platforms |
| posts_per_day | number (1-5) | Yes | Posts per platform per day |
| days | number (1-7) | Yes | Number of days to plan |
| start_date | string | No | ISO date, defaults to tomorrow |
| brand_voice | string | No | Override brand voice description |
| project_id | string | No | Project ID for brand/insights context |
| response_format | enum: text, json | Yes |  |

##### save_content_plan
Save a content plan to the database for team review, approval workflows, and scheduled publishing. Creates a plan_id you can reference in get_content_plan, update_content_plan, and schedule_content_plan.
- Scope: mcp:write | Credits: ~1-3

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| plan | string | Yes |  |
| project_id | string (UUID) | No |  |
| status | enum: draft, in_review, approved, scheduled, completed | Yes |  |
| response_format | enum: text, json | Yes |  |

##### get_content_plan
Retrieve a persisted content plan by ID.
- Scope: mcp:write | Credits: ~1-3

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| plan_id | string (UUID) | Yes | Persisted content plan ID |
| response_format | enum: text, json | Yes |  |

##### update_content_plan
Update individual posts in a persisted content plan.
- Scope: mcp:write | Credits: ~1-3

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| plan_id | string (UUID) | Yes |  |
| post_updates | enum: approved, rejected, needs_edit | No |  |
| response_format | enum: text, json | Yes |  |

##### submit_content_plan_for_approval
Create pending approval items for each post in a plan and mark plan status as in_review.
- Scope: mcp:write | Credits: ~1-3

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| plan_id | string (UUID) | Yes |  |
| response_format | enum: text, json | Yes |  |

#### Quality (2 tools)

##### quality_check
Score post quality across 7 categories: Hook Strength, Message Clarity, Platform Fit, Brand Alignment, Novelty, CTA Strength, and Safety/Claims. Each scored 0-5, total 35. Default pass threshold is 26 (~75%). Run after generate_content and before schedule_post. Include hashtags in caption if they will be published — they affect Platform Fit and Safety scores.
- Scope: mcp:read | Credits: ~0-1

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| caption | string | Yes | The post text to score. Include hashtags if they will be published — they affect Platform Fit and Safety/Claims scores. |
| title | string | No | Post title (important for YouTube) |
| platforms | enum: youtube, tiktok, instagram, twitter, linkedin, facebook, threads, bluesky,  | Yes | Target platforms |
| threshold | number (0-35) | Yes | Minimum total score to pass (max 35, scored across 7 categories at 0-5 each). Default 26 (~75%). Use 20 for rough drafts, 28+ for final posts going to large audiences. |
| brand_keyword | string | No | Brand keyword for alignment check |
| brand_avoid_patterns | string | No |  |
| custom_banned_terms | string | No |  |
| response_format | enum: text, json | Yes |  |

##### quality_check_plan
Batch quality check all posts in a content plan. Returns per-post scores and aggregate pass/fail summary. Use after plan_content_week and before schedule_content_plan to catch low-quality posts before publishing.
- Scope: mcp:read | Credits: ~0-1

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| plan | string | No | Content plan with posts array |
| threshold | number (0-35) | Yes | Minimum total score to pass (max 35, scored across 7 categories at 0-5 each). Default 26 (~75%). Use 20 for rough drafts, 28+ for final posts going to large audiences. |
| response_format | enum: text, json | Yes |  |

#### Remotion (2 tools)

##### list_compositions
List all available Remotion video compositions defined in Social Neuron. Returns composition IDs, dimensions, duration, and descriptions. Use this to discover what videos can be rendered with render_demo_video.
- Scope: mcp:write | Credits: ~5-20

##### render_demo_video
Render a Remotion composition to an MP4 or GIF file locally. Uses the Remotion bundler and renderer from the root project. This can take 30-120 seconds depending on composition length. Output is saved to public/videos/.
- Scope: mcp:write | Credits: ~5-20

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| composition_id | string | Yes | `Remotion composition ID to render. Use list_compositions to see available IDs. ` + `Examples: CaptionedClip, ProductAd-30s, TwitterAd.` |
| output_format | enum: mp4, gif | No | Output format. Defaults to "mp4". |
| props | string | No | JSON string of input props to pass to the composition. ' + 'Each composition accepts different props. Omit for defaults. |

#### Screenshots (2 tools)

##### capture_app_page
Navigate to a Social Neuron app page and take a full-page screenshot. Logs in with test credentials, navigates to the specified page, waits for content to load, then captures a screenshot. Output is saved to public/assets/screenshots/.
- Scope: mcp:read | Credits: ~1

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| page | enum: dashboard, ideation, creation, library, distribution, analytics, automations, settings, storyboard, video-editor, avatar-lab, brand-brain,  | Yes | App page to capture. Maps to internal route paths. |
| viewport | enum: desktop, mobile, tablet | No | Viewport size. desktop=1920x1080, mobile=390x844, tablet=768x1024. Defaults to desktop. |
| theme | enum: light, dark | No | Color theme. Defaults to light. |
| selector | string | No | Optional CSS selector to capture a specific element instead of the full page. |
| wait_ms | number (min 0) | No | Extra milliseconds to wait after page load before capturing. Useful for animations. Defaults to 2000. |

##### capture_screenshot
Take a screenshot of any URL. Launches a headless Chromium browser, navigates to the URL, and captures either the full page or a specific CSS selector. No login is performed.
- Scope: mcp:read | Credits: ~1

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| url | string | Yes | The URL to screenshot (e.g. https://example.com). |
| viewport | enum: desktop, mobile, tablet | No | Viewport size. Defaults to desktop. |
| selector | string | No | Optional CSS selector to capture a specific element instead of the full page. |
| output_path | string | No | Custom output file path. Defaults to public/assets/screenshots/<hostname>-<timestamp>.png. |
| wait_ms | number (min 0) | No | Extra milliseconds to wait after page load before capturing. Defaults to 1000. |

#### suggest (1 tool)

##### suggest_next_content
Suggest next content topics based on performance insights, past content, and competitor patterns. No AI call, no credit cost — purely data-driven recommendations.
- Scope: mcp:read | Credits: ~0

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| project_id | string (UUID) | No | Project ID (auto-detected if omitted) |
| count | number (1-10) | Yes | Number of suggestions to return |
| response_format | enum: text, json | No |  |

#### Usage (1 tool)

##### get_mcp_usage
Get your MCP API usage breakdown for the current billing month. Shows per-tool call counts and credit usage. Useful for monitoring API consumption and staying within tier limits.
- Scope: mcp:read | Credits: ~0

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| response_format | enum: text, json | No | Optional response format. Defaults to text. |

#### YouTube Analytics (1 tool)

##### fetch_youtube_analytics
Fetch YouTube channel analytics. Supports channel overview, daily breakdown, video-specific metrics, and top-performing videos. Requires a connected YouTube account.
- Scope: mcp:analytics | Credits: ~0

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| action | enum: channel, daily, video, topVideos | Yes | Type of analytics to fetch: "channel" for overview, "daily" for day-by-day, ' + '"video" for a specific video, "topVideos" for best performers. |
| start_date | string | Yes | Start date in YYYY-MM-DD format. |
| end_date | string | Yes | End date in YYYY-MM-DD format. |
| video_id | string | No | YouTube video ID. Required when action is "video". |
| max_results | number (1-50) | No | Max videos to return for "topVideos" action. Defaults to 10. |
| response_format | enum: text, json | No | Optional response format. Defaults to text. |

### Workflow Recipes

#### Recipe 1: Weekly Content Batch
```
1. get_ideation_context(project_id) -> understand what's working
2. generate_content(prompt, content_type, project_id) x5 -> create week's content
3. quality_check(content, platform) each -> validate
4. get_best_posting_times(platform) -> find optimal slots
5. schedule_post(content, platform, scheduled_time) each -> queue
```

#### Recipe 2: Performance Review & Optimization
```
1. fetch_analytics(days=7) -> raw performance data
2. get_performance_insights(project_id) -> AI analysis
3. get_loop_summary(project_id) -> actionable next steps
4. generate_content(prompt informed by insights) -> improved content
```

#### Recipe 3: Cross-Platform Repurposing
```
1. generate_content(prompt, platform="youtube") -> create primary content
2. adapt_content(content, source="youtube", target="instagram") -> adapt
3. adapt_content(content, source="youtube", target="tiktok") -> adapt
4. adapt_content(content, source="youtube", target="linkedin") -> adapt
5. schedule_post each adapted version -> distribute everywhere
```

#### Recipe 4: Brand-Aware Autopilot
```
1. get_brand_profile(project_id) -> verify brand voice loaded
2. update_autopilot_config(schedule, platforms) -> configure
3. get_autopilot_status() -> verify running
4. fetch_analytics(days=3) -> check early results
```

#### Recipe 5: Comment Engagement
```
1. list_comments(platform, status="pending") -> see new comments
2. moderate_comment(id, action) -> flag spam/inappropriate
3. reply_to_comment(id, reply_text) -> engage with audience
4. list_comments(platform, status="replied") -> verify replies sent
```

### Error Reference

| Error | Cause | Fix |
|-------|-------|-----|
| 401 Unauthorized | API key expired or invalid | Re-authenticate: `npx -y @socialneuron/mcp-server login --device` |
| 402 Insufficient Credits | Credit balance too low for operation | Purchase credits or upgrade plan |
| 403 Scope Denied | API key lacks required scope | Generate new key with correct scopes at Settings > Developer |
| 404 Not Found | Resource doesn't exist (wrong ID) | Verify the ID exists with a list operation first |
| 409 Conflict | Duplicate operation (e.g., double-scheduling) | Check existing scheduled posts before creating new ones |
| 422 Validation Error | Invalid parameters | Check parameter types and constraints in tool reference above |
| 429 Rate Limited | Too many requests | Wait until X-RateLimit-Reset, then retry |
| 500 Server Error | Internal error | Retry once; if persistent, check service status |

### CORRECT vs WRONG Patterns

**CORRECT:**
```
1. get_credit_balance() -> check you have enough credits
2. generate_content(prompt="5 hooks about...", content_type="hook", platform="tiktok")
3. quality_check(content=result, platform="tiktok") -> score >= 0.6
4. schedule_post(content=result, platform="tiktok", scheduled_time="2024-01-15T09:00:00Z")
```

**WRONG:**
```
1. generate_content(prompt="make something") -> too vague, no content_type
2. schedule_post(content=result) -> skipped quality_check, no platform
```

**CORRECT:** Use project_id to get brand-aware content:
```
generate_content(prompt="...", content_type="script", project_id="abc-123")
```

**WRONG:** Manually passing brand voice when project has a brand profile:
```
generate_content(prompt="...", content_type="script", brand_voice="professional...")
```

### Authentication

Three methods, all resulting in an API key stored in your OS keychain:

1. **Device Code (Recommended)**: `npx -y @socialneuron/mcp-server login --device` -- Opens browser, you approve, CLI receives key automatically.
2. **PKCE Browser Flow**: `npx -y @socialneuron/mcp-server login` -- Full OAuth browser flow with PKCE S256 challenge verification.
3. **API Key Paste**: `npx -y @socialneuron/mcp-server login --paste` -- Generate key at socialneuron.com/settings/developer, paste in terminal.

API keys use `snk_live_` prefix, are SHA-256 hashed with random salt before storage, and expire after 90 days. Keys are stored in macOS Keychain, Linux secret-tool, or encrypted file fallback.

### Scopes & Access Control

| Scope | Access Level |
|-------|-------------|
| mcp:full | All operations (default for Pro/Team/MCP API) |
| mcp:read | Read-only: analytics, insights, lists, brand profiles |
| mcp:write | Content generation: scripts, videos, images |
| mcp:distribute | Publishing and scheduling to connected platforms |
| mcp:analytics | Performance data and analytics refresh |
| mcp:comments | Social engagement: reply, moderate, delete comments |
| mcp:autopilot | Automated content scheduling configuration |

### Rate Limits

- 100 requests/minute per user (default)
- Per-tool limits for expensive operations (video generation, publishing)
- Agent loop detection: >5 identical calls in 30 seconds triggers cooldown
- Session hard cap: 200 calls/hour

### Developer Pricing

API access requires a paid plan (Starter or above). Free and Trial plans do not include API access.

| Plan | Monthly | MCP Scopes | Monthly Credits |
|------|---------|-----------|----------------|
| MCP API | $19 | Full access | 400 |
| Starter | $29 | Read + Analytics | 800 |
| Pro | $79 | Full access | 2,000 |
| Team | $199 | Full access + Multi-user | 6,500 |

1 credit = $0.01 USD. Credits are consumed by content generation (videos, images, scripts, analysis).

### CLI Reference

```bash
# Authentication
socialneuron-mcp login [--device|--paste]
socialneuron-mcp logout

# Deterministic CLI (no LLM required)
socialneuron-mcp sn publish --media-url <url> --caption <text> --platforms <list> --confirm
socialneuron-mcp sn status --job-id <id>
socialneuron-mcp sn posts --days 7 --platform youtube
socialneuron-mcp sn refresh-analytics
socialneuron-mcp sn preflight --check-urls
socialneuron-mcp sn oauth-health --json
```

Add `--json` to any `sn` command for machine-readable output in scripts and CI pipelines.

### Security

- API keys SHA-256 hashed with random salt (never stored in plaintext)
- PKCE S256 challenge verification for browser auth flows
- Timing-safe hash comparison prevents side-channel attacks
- SSRF protection blocks private IPs, localhost, cloud metadata endpoints
- Rate limiting with agent loop detection
- Credentials stored in OS keychain (macOS Keychain, Linux secret-tool)
- Gateway-side userId override prevents horizontal privilege escalation
- Audit logging with PII-redacted parameters

### Links

- npm: https://www.npmjs.com/package/@socialneuron/mcp-server
- Docs: https://socialneuron.com/docs/developer-api
- Agent Discovery: https://socialneuron.com/.well-known/ai-plugin.json
- System Prompt: https://socialneuron.com/system-prompt.txt
- Examples: https://github.com/socialneuron/examples