GitHub
Copied to clipboard!

Frequently Asked Questions

Last Updated: November 2025 Version: 1.0

Table of Contents

  1. General Questions
  2. Installation & Setup
  3. Authentication & Security
  4. Content Management
  5. File Management
  6. Translations & Locales
  7. Troubleshooting
  8. Performance & Limits
  9. Best Practices

General Questions

What is Vibe CMS?

Vibe CMS is a modern, headless content management system designed specifically for AI-first workflows. It allows you to manage content, files, and translations through natural language using Claude Code via the Model Context Protocol (MCP).

How is Vibe CMS different from WordPress or other CMS platforms?

Traditional CMS (WordPress, etc.):

  • Click through admin interfaces
  • Fill out forms manually
  • Limited automation
  • Monolithic architecture

Vibe CMS:

  • Natural language commands via Claude
  • API-first headless architecture
  • Built-in AI workflow support
  • Flexible, decoupled frontend

Do I need to know how to code to use Vibe CMS?

Basic use: No coding required - interact with Claude using natural language.

Advanced use: Yes - integrating Vibe CMS into your website requires JavaScript/TypeScript knowledge and the vibe-cms-sdk.

What is MCP and why do I need it?

MCP (Model Context Protocol) is a standardized way for AI assistants like Claude to interact with external tools. Think of it as a bridge that lets Claude directly manage your Vibe CMS content.

Without MCP: You manually use Vibe CMS dashboard With MCP: Tell Claude what you want, and it handles the CMS operations

Can I use Vibe CMS with Claude Code?

Yes! Vibe CMS is designed to work seamlessly with Claude Code through MCP.

Setup: Claude Code uses project-specific .mcp.json files in your project root. This allows each project to have its own Vibe CMS configuration.

Benefits:

  • Project-specific configuration
  • Version control friendly
  • No global config conflicts
  • Easy team collaboration

See Chapter 1 for detailed setup instructions.

Is Vibe CMS free?

Pricing varies by plan. Check https://vibecms.com/pricing for current options. Most plans include:

  • Free tier for development/testing
  • Paid tiers for production use
  • Enterprise options for large teams

Installation & Setup

Where do I install the MCP server?

The MCP server configuration goes in your project's .mcp.json file:

  • Location: project-root/.mcp.json
  • Scope: Project-specific configuration
  • Version control: Can be committed to Git (without sensitive tokens)

See Chapter 1 for detailed instructions.

Do I need to install anything besides the config file?

No - if you use the NPX method (recommended). NPX automatically downloads and runs the MCP server package when Claude needs it.

Yes - if you prefer global installation:

npm install -g vibe-cms-mcp-server

What are the prerequisites?

Required:

  • Claude Code (latest version)
  • Vibe CMS account and project
  • API token from your project

For NPX method (recommended):

  • Node.js and npm installed

For SDK integration (optional):

  • JavaScript/TypeScript project
  • npm or yarn package manager

Can I use Vibe CMS with multiple projects?

Yes! You can configure multiple Vibe CMS projects as separate MCP servers.

Before adding multiple servers:

  1. Create a new project in vibecms.ai
    • Click "New Project" in the dashboard
    • Give it a descriptive name (e.g., "Documentation", "Staging")
  2. Generate an API token for the new project
    • Settings → API Keys → Generate New Token
    • Copy the token immediately

Then add to your .mcp.json:

{
  "mcpServers": {
    "vibe-cms-prod": {
      "command": "npx",
      "args": ["-y", "vibe-cms-mcp-server"],
      "env": {
        "VIBE_PROJECT_ID": "proj_production_id",
        "VIBE_API_TOKEN": "vibe_token_prod_xxx"
      }
    },
    "vibe-cms-docs": {
      "command": "npx",
      "args": ["-y", "vibe-cms-mcp-server"],
      "env": {
        "VIBE_PROJECT_ID": "proj_docs_id",
        "VIBE_API_TOKEN": "vibe_token_docs_xxx"
      }
    },
    "vibe-cms-staging": {
      "command": "npx",
      "args": ["-y", "vibe-cms-mcp-server"],
      "env": {
        "VIBE_PROJECT_ID": "proj_staging_id",
        "VIBE_API_TOKEN": "vibe_token_staging_xxx"
      }
    }
  }
}

Using different projects: Specify which server to use:

  • "Using vibe-cms-prod, show me all collections"
  • "In vibe-cms-docs, create a user guide collection"
  • "With vibe-cms-staging, upload this test image"

Key points:

  • Each project needs its own Project ID and API Token
  • Use descriptive names for easy identification
  • Each MCP server name must be unique
  • See Chapter 1 for detailed instructions

How do I update the MCP server?

NPX method: Automatic - always uses latest version unless pinned

Global install:

npm update -g vibe-cms-mcp-server

Check version:

npm view vibe-cms-mcp-server version

Authentication & Security

How do I get an API token?

  1. Log in to Vibe CMS dashboard
  2. Navigate to Settings → API Keys
  3. Click "Generate New Token"
  4. Name it (e.g., "Claude MCP Access")
  5. Select required permissions
  6. Copy the token immediately (shown only once!)

What permissions does my API token need?

Minimum for read-only:

  • Read content
  • Read files

Recommended for full MCP usage:

  • Read content
  • Write content
  • Manage files
  • Manage schema

Enterprise/admin tasks:

  • All of the above
  • Manage users
  • Manage settings

Is my API token secure in the config file?

Yes, with caveats:

  • File is in your project directory
  • Can be gitignored to avoid committing
  • Readable by anyone with project access

Best practices:

  • Add .mcp.json to .gitignore if it contains tokens
  • Use different tokens for prod vs. dev
  • Rotate tokens every 90 days
  • Revoke immediately if compromised
  • Consider using environment variables for sensitive tokens

What if my API token is compromised?

Immediate steps:

  1. Log in to Vibe CMS dashboard
  2. Go to Settings → API Keys
  3. Find the compromised token
  4. Click "Revoke"
  5. Generate a new token
  6. Update your .mcp.json file
  7. Reload window in Claude Code

Prevention:

  • Never share tokens publicly
  • Add .mcp.json to .gitignore if it contains tokens
  • Use environment-specific tokens
  • Enable 2FA on your Vibe CMS account

Can I use environment variables instead of hardcoding tokens?

Yes! In your .mcp.json, reference environment variables:

{
  "mcpServers": {
    "vibe-cms-prod": {
      "command": "npx",
      "args": ["-y", "vibe-cms-mcp-server"],
      "env": {
        "VIBE_PROJECT_ID": "${VIBE_PROJECT_ID}",
        "VIBE_API_TOKEN": "${VIBE_API_TOKEN}"
      }
    }
  }
}

For SDK integration:

const vibeCMS = new VibeCMS({
  projectId: process.env.VIBE_PROJECT_ID,
  apiToken: process.env.VIBE_API_TOKEN
});

Content Management

What are collections?

Collections are like content types or templates. They define the structure of your content.

Examples:

  • Blog Posts (title, content, author, date)
  • Products (name, description, price, images)
  • FAQ Items (question, answer, category)

What's the difference between a collection and a content item?

  • Collection = The blueprint/template (e.g., "Blog Posts")
  • Content Item = Specific instance (e.g., "My First Post")

Analogy:

  • Collection = Database table schema
  • Content Item = Row in that table

What are singletons?

Singleton collections contain exactly one content item - useful for unique pages:

Examples:

  • Homepage content
  • About Us page
  • Site settings
  • Footer content

Regular collection: Many blog posts Singleton: One homepage

Can I change a collection's schema after creating content?

Yes, but with caution:

Safe changes:

  • Add new optional fields
  • Update field interfaces (e.g., input → textarea)
  • Change field order
  • Add translations

Dangerous changes:

  • Delete fields with data (data will be lost!)
  • Change field types (may cause data loss)
  • Make required fields (existing items may fail validation)

Best practice: Test schema changes in staging first!

How do drafts and published content work?

Vibe CMS uses a draft-first workflow:

  1. Create content → Starts as draft
  2. Edit and preview → Still draft
  3. Publish → Makes live

Draft = Only visible in CMS, not in public API Published = Available via public API queries

Note: All edits are made to draft version - must explicitly publish changes!

Can I schedule content to publish later?

Not yet - manual publishing only. Scheduled publishing is on the roadmap.

Workaround: Use Edge Functions or your application logic to query by date:

const posts = await vibeCMS.getContent('blog-posts', {
  filter: {
    status: 'published',
    publish_date: { lte: new Date() }
  }
});

File Management

What types of files can I upload?

Supported formats:

  • Images: JPG, PNG, GIF, WebP, SVG
  • Documents: PDF, DOC, DOCX, TXT, MD
  • Media: MP4, MP3, WAV
  • Archives: ZIP, TAR, GZ (within size limits)

File size limits: Vary by plan (typically 10-100 MB per file)

How do folders work in Vibe CMS?

Folders are virtual paths, like file systems:

Examples:

  • /blog-images
  • /documents/2024
  • /avatars/users

Features:

  • Unlimited nesting depth
  • Created automatically on first file upload
  • Can be renamed or deleted (moves/removes files)

Can I organize files after uploading?

Yes! You can:

  • Move files between folders
  • Rename files
  • Update metadata (title, alt text, description)
  • Add SEO keywords

Example:

"Move the file [id] from /uploads to /blog-images/featured"

What is file metadata used for?

Metadata fields:

Field Purpose SEO Impact
Title Display name in CMS No
Alt Text Image accessibility High
Description Longer explanation Medium
Caption Display caption Low
Focus Keyword SEO targeting High

Best practice: Always add alt text for images (accessibility + SEO)!

How do I upload files from URLs?

Use the upload-from-URL tool:

"Download the image from https://example.com/image.jpg
and upload it to /blog-images with title 'Hero Image'
and alt text 'Person using laptop'"

Supported domains: Most public URLs work. Some sites may block programmatic downloads.

Translations & Locales

How does multi-language content work?

Each content item can have multiple translations (one per locale):

Example:

  • Content Item: "Welcome Post"
    • English (en-US): "Welcome to our blog!"
    • German (de-DE): "Willkommen zu unserem Blog!"
    • French (fr-FR): "Bienvenue sur notre blog!"

What is a locale?

A locale is a language + region combination (BCP 47 format):

Examples:

  • en-US = English (United States)
  • en-GB = English (United Kingdom)
  • de-DE = German (Germany)
  • de-CH = German (Switzerland)
  • fr-FR = French (France)

Why regions matter:

  • Different spellings (color vs. colour)
  • Different formats (dates, currency)
  • Cultural differences

Do I need to translate every field?

It depends on your collection schema. Each field can be:

  • Translatable - Different value per locale (most text fields)
  • Non-translatable - Same value across all locales (IDs, dates, etc.)

Typically translatable:

  • Titles, headings
  • Body content
  • Descriptions
  • Meta tags

Typically not translatable:

  • Dates
  • Numbers
  • IDs
  • File references (though you might use different images per locale)

How do I set a default locale?

In your Vibe CMS project settings:

  1. Navigate to Settings → Locales
  2. Select your primary locale
  3. Click "Set as Default"

Default locale is used as fallback when content isn't translated.

Can I add more locales later?

Yes! You can add/remove locales at any time:

Adding a locale:

"Add Spanish (es-ES) as a locale to my project"

Note: Existing content won't automatically translate - you'll need to create translations for each content item.

Troubleshooting

Claude doesn't recognize Vibe CMS commands

Check:

  1. MCP server configured in .mcp.json file
  2. JSON syntax is valid (use jsonlint.com)
  3. .mcp.json file is in project root directory
  4. Claude Code window reloaded after config changes
  5. Server name matches in config and commands

Test: "List all MCP servers" - should show vibe-cms-prod

"Authentication Failed" errors

Check:

  1. API token copied correctly (no extra spaces)
  2. Token hasn't expired
  3. Token has required permissions
  4. Project ID is correct
  5. Environment variables are properly set (if using)

Test: Generate a new token and update .mcp.json, then reload window in Claude Code.

Changes aren't appearing on my website

Common causes:

  1. Content is draft - Must publish first
  2. Cache not cleared - Check browser cache and CDN
  3. Wrong API endpoint - Verify using production vs. staging
  4. Query filters - Check your API query includes new content

Debug: Query directly via Vibe CMS dashboard to verify content exists.

"Rate limit exceeded" errors

Causes:

  • Too many API requests in short time
  • Exceeded plan's rate limits

Solutions:

  1. Wait a few minutes before retrying
  2. Batch operations when possible
  3. Upgrade to higher plan if needed
  4. Implement caching in your application

Files won't upload

Check:

  1. File size within plan limits
  2. File type is supported
  3. Folder path is valid (no special characters)
  4. API token has "Manage files" permission
  5. Storage quota not exceeded

Test: Try uploading a small text file first.

Performance & Limits

What are the API rate limits?

Varies by plan:

  • Free: 100 requests/hour
  • Basic: 1,000 requests/hour
  • Pro: 10,000 requests/hour
  • Enterprise: Custom limits

Best practices:

  • Implement caching
  • Use batch operations
  • Optimize queries with filters

How many files can I store?

Depends on plan:

  • Free: 1 GB storage
  • Basic: 10 GB storage
  • Pro: 100 GB storage
  • Enterprise: Custom storage

Note: Each project has separate storage quota.

Is there a limit on collections or content items?

Collections: Typically no hard limit (reasonable use) Content items: Plan-dependent

  • Free: 1,000 items
  • Basic: 10,000 items
  • Pro: 100,000 items
  • Enterprise: Unlimited

How can I improve query performance?

Optimization techniques:

  1. Use filters - Fetch only what you need
  2. Limit results - Paginate large datasets
  3. Cache responses - Reduce repeated queries
  4. Select specific fields - Don't fetch everything
  5. Index frequently queried fields - Contact support for indexing

Example optimized query:

const posts = await vibeCMS.getContent('blog-posts', {
  filter: { status: 'published' },
  limit: 10,
  fields: ['title', 'slug', 'published_at'],
  sort: '-published_at'
});

Best Practices

Content structure

DO:

  • Plan collections before creating content
  • Use descriptive field names
  • Set required fields appropriately
  • Use singletons for unique pages

DON'T:

  • Create overly generic collections
  • Use cryptic field names
  • Make everything required
  • Duplicate content across collections

File organization

DO:

  • Use logical folder structure
  • Name files descriptively
  • Add alt text to all images
  • Optimize images before upload

DON'T:

  • Upload files to root
  • Use generic names (image1.jpg)
  • Skip accessibility metadata
  • Upload unoptimized huge files

Translation workflow

DO:

  • Complete content in default locale first
  • Use professional translators for important content
  • Test all locales before launch
  • Keep translations in sync

DON'T:

  • Leave translations half-finished
  • Rely solely on machine translation
  • Forget to update translations when source changes
  • Mix languages within a translation

API usage

DO:

  • Implement caching
  • Handle errors gracefully
  • Use environment-specific tokens
  • Log API errors for debugging

DON'T:

  • Query on every page load without caching
  • Expose API tokens in frontend code
  • Ignore rate limit headers
  • Use production tokens in development

Security

DO:

  • Rotate API tokens regularly
  • Use least-privilege tokens
  • Enable 2FA on account
  • Monitor API usage
  • Add .mcp.json to .gitignore if it contains sensitive data

DON'T:

  • Share tokens publicly
  • Commit tokens to Git
  • Use admin tokens for frontend
  • Ignore security warnings

Still Have Questions?

Search the Documentation

Contact Support

Community Resources

Can't find your question? Submit a new FAQ suggestion

FAQ v1.0 | Last Updated: November 2025