API & MCP Reference

Connect FireBreath to Claude Code or any AI assistant using the Model Context Protocol (MCP). 24 tools for fully automated social media management.

Prefer a terminal workflow instead? See the CLI Manual.

What is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI assistants interact with external tools and services. FireBreath's MCP server exposes 24 tools that an AI agent can call to create posts, upload media, schedule content, manage accounts, and analyze performance — all without leaving the AI conversation.

Setup

Step 1: Generate an API key

Go to Settings → API Keys in your FireBreath dashboard and create a new API key. The key is shown only once — copy it immediately. Your key inherits your user role and permissions, so tools are automatically scoped to what you can access.

Step 2: Configure your AI assistant

Add FireBreath to your AI assistant's MCP configuration. For Claude Code, add this to your .mcp.json file:

{
  "mcpServers": {
    "firebreath": {
      "type": "url",
      "url": "https://firebreath.app/api/mcp",
      "headers": {
        "Authorization": "Bearer fb_your_key_here"
      }
    }
  }
}

No installation needed — the MCP server runs on FireBreath's infrastructure. Your API key scopes the session to your account and permissions.

Security note

Your API key acts as your identity. Never share it publicly or commit it to version control. If compromised, revoke it immediately from Settings → API Keys and generate a new one. Tools are automatically scoped to your role permissions.

Environment Variables

The MCP server reads from .env.local in the FireBreath project root, or from the env block in your MCP config. Only the API key is required — all others are read from the server's environment.

Variable	Purpose
`FIREBREATH_API_KEY`	Your personal API key (required)
`NEXT_PUBLIC_SUPABASE_URL`	Supabase project URL
`SUPABASE_SECRET_KEY`	Supabase service role key
`TOKEN_ENCRYPTION_KEY`	AES-256-CBC key for OAuth token decryption
`MINIMAX_API_KEY or ANTHROPIC_API_KEY`	AI caption generation (optional)
`QSTASH_TOKEN`	Post scheduling via QStash (optional)

Tools Reference (24 tools)

Publishing

firebreath_create_post

Create and optionally publish a post to one or more connected accounts. Supports publish, schedule, draft, and manual actions.

Params: content, integrationIds, action, scheduledAt?, mediaUrls?, manualInstructions?

firebreath_upload_media

Upload images or videos for use in posts. Accepts a local file path or a URL.

Params: filePath | url

firebreath_publish_post

Publish a draft or scheduled post immediately.

Params: postId

firebreath_retry_post

Retry a post that failed to publish.

Params: postId

firebreath_post_thread

Post a thread (chain of tweets) on X/Twitter. Supports Tier 2 posting strategy.

Params: integrationId, tweets[]

firebreath_reply_to_post

Reply to an existing published X/Twitter post.

Params: postId, content

firebreath_approve_post

Approve (lock) or revoke approval (unlock) a post.

Params: postId, action ("approve" | "revoke")

AI Caption Generation

firebreath_generate_caption

Generate AI-powered captions for one or more platforms. Returns 2 variations per platform with character counts. Requires MINIMAX_API_KEY or ANTHROPIC_API_KEY.

Params: prompt, platforms[], tone, language?, existingContent?, includeHashtags?

Media Staging & Batches

firebreath_list_media

List uploaded media. Use filter "ready" to find staged media.

Params: filter? ("all" | "ready"), limit?

firebreath_list_batches

List media batches grouped for posting.

Params: status? ("ready" | "posted" | "all")

firebreath_mark_media_used

Mark media or batches as used after posting.

Params: batchId | mediaIds[]

Management

firebreath_list_accounts

List all connected social media accounts with Account IDs (integration IDs).

firebreath_list_posts

List posts with optional state filter.

Params: state?, limit?

firebreath_get_post

Get full details of a specific post.

Params: postId

firebreath_update_post

Edit content, reschedule, or granularly modify media attachments.

Params: postId, content?, scheduledAt?, addMedia?, removeMediaAt?, replaceMediaAt?

firebreath_delete_post

Soft-delete a post.

Params: postId

Import & Sync

firebreath_sync_posts

Import existing posts from connected platforms. Already-imported posts are skipped.

Params: integrationId, limit?

Analytics & Learning

firebreath_get_analytics

Fetch engagement metrics for a published post. Instagram posts get media-type-specific metrics.

Params: postId

firebreath_get_channel_analytics

Get aggregate performance for a channel over a time period.

Params: integrationId, from?, to?

firebreath_get_account_insights

Instagram account-level insights: follower growth, demographics, optimal posting times.

Params: integrationId, period?, since?, until?, includeDemo?

firebreath_analyze_content

Retrieve published posts with analytics for content strategy analysis.

Params: integrationId?, limit?, sortBy?

Social Inbox

firebreath_list_inbox

List comments, replies, and mentions across all connected platforms with sentiment analysis.

Params: platform?, read?, sentiment?, limit?

firebreath_reply_inbox

Reply to a comment or reply directly from the social inbox.

Params: id, text

firebreath_sync_inbox

Sync latest comments and replies from all connected platforms into the inbox.

Params: integrationId?

Example Prompts

Here are some example prompts you can use with Claude Code or another MCP-compatible AI assistant:

Schedule a post to multiple platforms

"Schedule a post about our spring sale to Facebook and Instagram for tomorrow at 10 AM. Include a cheerful, promotional tone."

Post user-prepared media

"Check for any ready media batches and post them according to the instructions."

Analyze content performance

"Analyze my Instagram content from the last 30 days. What types of posts get the most engagement?"

Generate captions

"Generate captions for a post about our new product launch. Target Instagram, LinkedIn, and Twitter with a professional tone."

Weekly content planning

"Create a content calendar for next week. Schedule 2 posts per day across Instagram and Facebook based on what performed best last month."

Manage engagement

"Sync my inbox and show me all unread comments. Reply to any positive comments with a thank you, and flag any negative ones for me to review."

Recommended Workflow

FireBreath splits content production into two roles: producers (who create content, typically via MCP/AI) and reviewers (who verify and lock content, typically via the web app).

1.Producer creates content — AI agent uses firebreath_create_post with action "schedule".
2.Reviewer checks content — Opens the Review page in FireBreath, reads the post, edits if needed, and clicks Approve to lock it.
3.Post publishes automatically — At the scheduled time, the post is published via the platform API.
4.Analyze and learn — Use firebreath_analyze_content to understand what works and refine your strategy.

Back to Getting Started