Developer docs · MCP

Connect BeyondBeings to your AI agent

The BeyondBeings MCP server gives any AI agent — Claude, OpenClaw, Hermes, or any Model Context Protocol host — the full BeyondBeings studio. Your agent researches a trending idea, writes the headline, generates a finished editorial graphic or carousel, and hands you a permanent URL to post anywhere.

Connect once, then just tell your agent what to make. Setup takes about two minutes.

Connect your agent Prefer the CLI?

What your agent can do

The same end-to-end pipeline you get on the website, exposed as agent tools — think, write, design, deliver.

Think

studio_chat, trending_ideas — content ideas, hooks, angles, and full carousel plans in the house voice, grounded on live web facts.

Write

write_headlines — three on-image headline options in the right voice (editorial stays factually faithful).

Design

generate_graphic, generate_carousel — BeyondBeings engineers the prompt, writes the title, and composites it. recomposite_title re-edits a headline with no re-render.

Deliver

Every result returns a permanent public imageUrl your agent posts to Slack, Discord, or anywhere using its own tools.

Step 1 — Get your API key

The MCP server authenticates with a long-lived BeyondBeings API key (it never expires until you revoke it).

1.Create a free account (or sign in).
2.Open Settings → API Keys and click Create key.
3.Copy the key — it starts with bb_live_ and is shown only once.

A key carries your account's tier, model access, and daily limit. Keep it secret — treat it like a password. You can revoke a key anytime from the same page, and it stops working immediately.

Step 2 — Connect your agent

MCP is a standard, so every host uses the same server definition: a command, its args, and an env block with your key. The server runs locally over stdio and talks to BeyondBeings over HTTPS.

Claude Desktop

Edit your config file, then restart Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "beyondbeings": {
      "command": "npx",
      "args": ["-y", "--package=@beyondbeings/mcp", "beyondbeings-mcp"],
      "env": {
        "BEYONDBEINGS_API_KEY": "bb_live_your_key_here"
      }
    }
  }
}

OpenClaw, Hermes & other MCP hosts

OpenClaw, Hermes, Cursor, Cline, and any MCP-compatible runtime accept the same server definition — add it wherever your host lists MCP servers (a config file or a UI). The three things every host needs are the command, the args, and your key:

Generic MCP server entry

{
  "command": "npx",
  "args": ["-y", "--package=@beyondbeings/mcp", "beyondbeings-mcp"],
  "env": {
    "BEYONDBEINGS_API_KEY": "bb_live_your_key_here",
    "BEYONDBEINGS_API_URL": "https://beyondbeings.com"
  }
}

Prefer a global install? Then the binaries are on your PATH and you can point command at them directly:

Global install

npm install -g @beyondbeings/mcp
# now "command": "beyondbeings-mcp" (server) and the "bb" CLI both work

Configuration

Variable	Default	What it does
BEYONDBEINGS_API_KEY	—	Your `bb_live_` key. Required.
BEYONDBEINGS_API_URL	https://beyondbeings.com	Override the API host (rarely needed).

Generation can run up to ~13 minutes in the worst case, and the server emits progress updates as it works. If your host lets you set a per-tool timeout, give it room (≥ 900 seconds).

Step 3 — Put it to work

That's it. Now just ask your agent in plain language. A few examples:

“Find a trending tech-news story, write a bold headline, and make a 4:5 graphic for it. Then post it to #marketing.”

“Plan a 5-slide carousel about the history of ancient companies, then generate every slide.”

“Here's a press release — make a faithful editorial graphic in editorial mode and don't embellish the facts.”

“What's left in my generation quota today?”

Tools reference

Twelve tools, grouped by the job they do. Your agent picks the right ones for each request.

Think & write

studio_chat

Ask the BeyondBeings strategist for ideas, hooks, carousel plans, captions, or refinements — house voice, live web grounding, and it reads pasted X/Twitter links.

trending_ideas

Today's grounded, viral-leaning content ideas (real events, people, phenomena).

write_headlines

Three fresh on-image headlines for a topic or headline, in the chosen mode's voice.

Design

generate_graphic

Generate one graphic. Pass a rough prompt or just a topic + headline — BeyondBeings writes the full prompt, title, and accent color. Returns the image inline + a permanent imageUrl. Default aspect 4:5.

generate_carousel

Generate a 2–10 slide carousel in one call, grouped under a shared id. Returns each slide + an ordered URL list.

recomposite_title

Re-bake a graphic's headline (text, color, font, position) without re-running the AI model — fast and cheap.

Discover & manage

list_models

The image models you can request, with provider, pricing band, and tier availability.

list_modes

Generation modes (general vs editorial), aspect ratios, industries.

list_industries

Industry presets that bias ideation and styling.

check_quota

How much of today's generation budget is left.

list_generations

Browse your recent generations (newest first).

get_generation

Fetch one past generation by id.

The server also ships ready-made prompt templates your host can surface as one-click starts: daily_content, carousel_from_topic, react_to_news, youtube_thumbnail, ig_editorial_headline, and carousel_5_slide.

Direct REST API

Prefer to call the API directly (no MCP host)? Every endpoint lives under https://beyondbeings.com/api and takes the same key as a bearer token.

Generate a graphic with curl

curl -X POST https://beyondbeings.com/api/generate \
  -H "Authorization: Bearer bb_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a 1500-year-old company that still operates today",
    "title": "THIS COMPANY IS 1500 YEARS OLD",
    "includeTitle": true,
    "aspectRatio": "4:5",
    "mode": "editorial"
  }'
# → { "imageUrl": "https://...", "id": "...", "title": "...", "aspectRatio": "4:5", ... }

Endpoint	Method	Purpose
/api/generate	POST	Generate a graphic (writes prompt + title server-side).
/api/studio	POST	House-voice ideation, plans, captions (grounded).
/api/title-alternatives	POST	Three alternative headlines for a title.
/api/suggestions	GET	Today's trending content ideas.
/api/generations	GET	List your recent generations (cursor-paginated).
/api/generations/{id}	GET	Fetch one generation by id.
/api/generate/{id}/recomposite	POST	Re-bake a title overlay.
/api/quota	GET	Remaining daily generation budget.
/api/catalog	GET	Models, modes, aspect ratios, industries (public).

/api/generate is synchronous — it returns once the image is ready (allow up to ~13 minutes). The returned imageUrl is a permanent public link.

Prefer the terminal?

The same package ships a bb CLI — generate, plan carousels, brainstorm, and script it into CI. The MCP server and CLI share one core and one API key.

CLI docs

FAQ

Don't see your question? Email info@beyondbeings.com.

What is the Model Context Protocol (MCP)?

MCP is an open standard for connecting AI agents to external tools. A host (Claude Desktop, OpenClaw, Hermes, Cursor, and others) launches an MCP server and can then call its tools during a conversation. The BeyondBeings MCP server exposes graphic generation, ideation, and headline writing as tools your agent can use.

Does my agent post to Slack itself, or does BeyondBeings?

Your agent delivers. Every result includes a permanent, public image URL. Your agent then posts that URL to Slack, Discord, or any channel using its own already-connected tools. BeyondBeings hands back the asset; delivery is the host's job — which means it works with whatever integrations your agent already has.

Do I need to write image prompts myself?

No. Pass a rough prompt or even just a topic plus a headline, and BeyondBeings engineers the full visual prompt, writes the title, picks the accent color, and composites the headline. The studio_chat tool can also plan the whole post for you first.

How long does generation take?

A single graphic usually takes 30–120 seconds (up to ~13 minutes in the worst case as the model cascade falls back). The server sends progress updates so well-behaved hosts won't time out. Ideation, headlines, and trending ideas are fast (a few seconds).

Is it free?

The MCP server and CLI are free and open. A BeyondBeings account is required for an API key; generation counts against your plan's daily limit (a free account included). Ideation and headline tools don't consume your generation quota.

Give your agent a design studio

Create a free account, mint a key, and connect it to your agent in two minutes.

Get your API key