How to Set Up MCP Server in Folio and Cursor

Model Context Protocol (MCP) is an open standard from Anthropic that allows AI agents to work directly with external systems. We integrated an MCP server into Folio CMS, so you can now create pages, edit articles, or upload files from Cursor IDE with a single prompt.

What you will need

A Rails application with Folio CMS (version with MCP support)
Cursor IDE (or another MCP-compatible client)
Admin account in Folio Console

The whole setup takes about 10 minutes.

Step 1: Install MCP into Folio

Run the generator that adds the required migrations and configuration files:

Bash

rails generate folio:mcp:install
rails db:migrate

Step 2: Configure resources

Edit config/initializers/folio_mcp.rb and define which models MCP should manage:

config/initializers/folio_mcp.rb

Ruby

12345678910111213141516171819202122232425

Folio::Mcp.configure do |config|
  config.enabled = true

  config.resources = {
    pages: {
      model: "Folio::Page",
      fields: %i[title slug perex meta_title meta_description published locale],
      tiptap_fields: %i[tiptap_content],
      cover_field: :cover,
      versioned: true
    },
    articles: {
      model: "SinfinDigital::FlashArticle",
      fields: %i[title subtitle slug published featured],
      tiptap_fields: %i[tiptap_content]
    },
    files: {
      model: "Folio::File::Image",
      searchable: true,
      uploadable: true
    }
  }

  config.locales = %i[cs en]
end

Each resource can have fields (simple attributes), tiptap_fields (rich text), cover_field (main image), and versioned (change history).

Step 3: Generate an API token

The token is tied to a specific user and inherits their permissions. It is shown only once, so save it.

Bash

# Generování nového tokenu
rails folio:mcp:generate_token[[email protected]]

# Seznam uživatelů s povoleným MCP
rails folio:mcp:list_enabled

# Deaktivace MCP pro uživatele
rails folio:mcp:disable[[email protected]]

Step 4: Configure Cursor IDE

Create a .cursor/mcp.json file in the project root. For production, change the URL to your domain.

.cursor/mcp.json

JSON

{
  "mcpServers": {
    "folio-local": {
      "type": "http",
      "url": "http://localhost:3000/folio/api/mcp",
      "headers": {
        "Authorization": "Bearer mcp_live_vas_token_zde"
      }
    }
  }
}

After saving, restart Cursor. The MCP server should appear in the list of available tools.

Step 5: Verify the connection

Test the connection directly from the terminal. If everything works, you will get a response with pong.

Bash

curl -X POST http://localhost:3000/folio/api/mcp \
  -H "Authorization: Bearer VAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"ping"}'

Available tools

For each configured resource, MCP automatically creates a set of CRUD tools plus specialized tools for files, versions, and translations.

Ruby

# CRUD operace (pro každý resource)
get_page(id)                              # Získání záznamu
list_pages(limit, offset, locale)         # Výpis záznamů
create_page(title, slug, tiptap_content)  # Vytvoření
update_page(id, title, ...)               # Úprava

# Práce se soubory
upload_file(url, alt, tags)               # Nahrání z URL
list_files(query)                         # Vyhledání

# Historie verzí (pokud versioned: true)
list_page_versions(id)                    # Seznam verzí
get_page_version(id, version)             # Konkrétní verze
restore_page_version(id, version)         # Obnovení

# Překlady
extract_translatable_texts(tiptap)        # Extrakce textů
apply_translations(original, translations) # Aplikace překladů

Working with Tiptap content

Tiptap is the rich text editor used in Folio. Content is stored as JSON. You can get the list of available node types through the MCP resource folio://tiptap/schema.

JSON

1234567891011121314151617181920

// Základní struktura Tiptap dokumentu
{
  "type": "doc",
  "content": [
    {
      "type": "paragraph",
      "content": [
        { "type": "text", "text": "Obyčejný odstavec" }
      ]
    },
    {
      "type": "folioTiptapNode",
      "attrs": {
        "type": "SinfinDigital::Tiptap::Node::Contents::Title",
        "version": 1,
        "data": { "title": "Nadpis", "tag": "H2" }
      }
    }
  ]
}

Attaching images

Watch the naming convention: the attribute name depends on whether it is a single image or a collection:

JSON

// Jeden obrázek (cover: :image)
"cover_placement_attributes": { "file_id": 123 }

// Více obrázků (images: :images)
"image_placements_attributes": [
  { "file_id": 123 },
  { "file_id": 124 }
]

Security and configuration

The MCP server uses the same rules as Folio Console: Bearer token authentication, authorization through Folio::Ability, and respects site boundaries. You can configure rate limiting and audit logging.

Ruby

# config/initializers/folio_mcp.rb
config.rate_limit = 100 # požadavků/minutu

config.audit_logger = ->(event) {
  Rails.logger.tagged("MCP") { Rails.logger.info(event.to_json) }
}

Troubleshooting

404 Not Found- Check that Folio::Mcp.enabled? returns true. Restart the Rails server after changing the configuration.

401 Unauthorized- Verify the token. The user must have mcp_enabled: true.

Validation Errors- MCP uses the same validations as Console. Check the required model fields.

The MCP server is part of Folio CMS. You can find the full documentation in the repository. Have questions? Get in touch.