Your First Conversation

Now that you've connected BlokMCP to your AI assistant, let's walk through your first conversation and learn how to interact with your Storyblok content.

Testing the Connection

Start with a simple test to make sure everything is working:

Option 1: Check Available Tools

What Storyblok tools do you have access to?

Claude should respond with a list of available tools like fetch_stories, get_story, fetch_components, fetch_assets, etc.

Option 2: Get Space Information

Show me information about my Storyblok space

Claude will fetch and display your space details including name, ID, plan, and settings.

Option 3: List Recent Stories

List my 10 most recent stories

You should see a list of your recent stories with titles, IDs, and status.

If any of these work, congratulations - BlokMCP is successfully connected!

Understanding How It Works

Natural Language, Not Commands

You don't need to learn specific commands or API syntax. Just describe what you want in natural language:

Good examples:

"Show me all unpublished blog posts"
"Create a new page called 'About Us'"
"Update the hero image on the homepage"
"Publish all stories in the 'ready' folder"

You don't need to:

Know tool names (fetch_stories, update_story, etc.)
Know API parameters or IDs
Use specific formats or syntax

Claude will figure out which tools to use and how to call them based on your request.

Multi-Step Operations

Claude can handle complex, multi-step operations in a single conversation:

Find all blog posts from last month that are in draft status,
update their category to "Archive", and publish them.

Claude will:

Fetch stories with the right filters
Update each one
Publish them
Report back on what was done

Asking for Clarification

If your request is ambiguous, Claude will ask for clarification:

You: "Publish that story"
Claude: "I found several stories. Which one would you like to publish?"

This helps prevent mistakes and ensures Claude does exactly what you want.

Getting Oriented in Your Space

Before diving into content operations, it's helpful to understand your space structure:

Explore Your Content Structure

What's the structure of my Storyblok space? Show me:
1. Available content types (components)
2. Folder organization
3. Common workflows

List Available Components

What content types are available in my space?
Show me their names and key fields.

Understanding Folders

How are my stories organized? Show me the folder structure.

Check Workflows

What workflows are set up in my space?

Common First Tasks

Here are some common things people do in their first conversation:

1. Review Recent Content

Show me the 20 most recently updated stories

2. Check Unpublished Content

List all unpublished stories

3. Explore Assets

How many assets do I have? Show me recent uploads.

4. Review Team Collaborators

Who has access to this space?

5. Understand Space Settings

What's my space plan and current usage?

Your First Content Operation

Let's try a simple content operation:

Create a Draft Story

Create a new blog post called "Getting Started with BlokMCP"
as a draft in the "blog" folder

Update a Story

Find the story "Getting Started with BlokMCP" and
update the introduction to say "This guide shows you how to use BlokMCP."

Publish a Story

Publish the "Getting Started with BlokMCP" story

Delete a Story

Delete the "Getting Started with BlokMCP" story

Note: Be careful with delete operations - they're permanent!

Learning as You Go

Ask Claude for Help

Claude knows what it can do with BlokMCP. Don't hesitate to ask:

What kinds of things can you help me with in Storyblok?

How can I bulk publish stories?

Show me an example of updating component schemas

Explore Tool Capabilities

What can you do with assets?

Can you help me with workflow approvals?

What datasource operations are available?

Best Practices

Be Specific

Instead of:

"Update that story"

Be specific:

"Update the story 'Summer Sale' to change the banner image"

Confirm Destructive Operations

For operations that delete or significantly modify content:

You: "I want to delete all stories in the 'archive' folder"
Claude: "I found 47 stories in the 'archive' folder. Are you sure you want to delete them all?"
You: "Yes, proceed"

Start Small

When trying bulk operations for the first time:

Start with a small test set
Verify the results
Then scale up

Example:

Update the first 3 blog posts to add a "migrated" tag,
so I can verify it's working correctly

Use Preview/Draft Mode

Before publishing:

Create or update as drafts first
Review in Storyblok's preview
Then publish when ready

Understanding Responses

Claude will typically show you:

What action was taken
Which stories/components/assets were affected
Any errors or warnings
Confirmation of success

Example response:

I've updated 5 stories in the "blog" folder:
1. "Summer Sale" (ID: 123) - Published
2. "New Collection" (ID: 124) - Published
3. "Customer Stories" (ID: 125) - Published
4. "Behind the Scenes" (ID: 126) - Published
5. "Sustainability" (ID: 127) - Published

All stories are now live.

When Things Go Wrong

Rate Limits

If you hit rate limits:

I've hit the rate limit (10 requests/minute on the free plan).
Please wait a moment before trying again.

Solution: Wait 60 seconds or upgrade your plan for higher limits.

Permission Errors

If your token doesn't have sufficient permissions:

I can't perform that operation. Your Storyblok token
doesn't have permission to publish stories.

Solution: Update your management token permissions in Storyblok.

Not Found Errors

If Claude can't find what you're looking for:

I couldn't find a story called "Sumemr Sale".
Did you mean "Summer Sale"?

Claude will often suggest alternatives or ask for clarification.

What's Next?

Now that you've completed your first conversation, explore more:

Ready-to-Use Examples

Conversation Starters →

Copy/paste examples for:

Content management
Asset operations
Bulk publishing
Schema updates
And more

Task-Based Guides

Content Workflows →

Learn how to:

Bulk publish stories
Translate content
Schedule releases
Set up workflows

Tools Reference

Tools Reference →

Detailed documentation of all 130+ tools available.

Tips for Success

Be conversational - Talk to Claude like a colleague
Ask questions - Claude can explain and guide you
Start simple - Get comfortable with basic operations first
Use drafts - Test changes before publishing
Review results - Always check what was done
Iterate - Refine your requests based on results

Conversation Starters - Ready-to-use examples
Common Tasks - Frequently requested operations
Troubleshooting - Common issues and solutions