Developers · Model Context Protocol

Floniks MCP server

Connect Floniks to any MCP client — Claude.ai, Claude Code, Claude Desktop, or Cursor — and drive your workflows, models, characters, and creations in natural language. Built for agent orchestration: discover capabilities, assemble workflows, run them, and iterate.

Endpoint

/api/v1/mcp

Protocol

MCP 2024-11-05

Transport

Streamable HTTP

Auth

API key / OAuth

Overview

The Model Context Protocol (MCP) lets an AI client call your Floniks account through a typed set of tools. Once connected, you can ask your assistant to list and build workflows, browse models and templates, reuse character/location passports for cross-shot consistency, execute jobs, and read results — all without leaving the chat.

Discover

list_models, list_templates, list_characters, list_creations

Assemble

generate_workflow, create_workflow, update_workflow, get_template

Run & iterate

execute_workflow, single_task, get_task, get_credit_balance

Quickstart

Claude Code, ~1 minute

1
Create an API key on the API page (starts with mk_; the plaintext is shown once).
2
Add the server to Claude Code:

bash

claude mcp add --transport http floniks https://api.floniks.com/api/v1/mcp \
  --header "Authorization: Bearer mk_YOUR_KEY"

Run /mcp in Claude Code — floniks should appear as connected. Then try one of the recipes below.

Authentication

Every request authenticates with a Bearer token. Two token types are accepted:

Floniks API key (mk_…) — paste it as the Bearer token. Best for Claude Code, Claude Desktop, and Cursor.
OAuth 2.1 — Claude.ai’s web connector runs an OAuth flow automatically; just sign in when prompted.

An API key acts like a password: it can call every API on your account and spend your credits. Never embed it in front-end code or commit it to git. Rotate it on the API page if exposed.

Connect a client

Claude.ai (web)

1
Open Settings · Connectors , then Add connector → Custom MCP server.
2
Set the server URL to https://api.floniks.com/api/v1/mcp and connect. Sign in via OAuth, or choose API key and paste your mk_ key.

Claude Code (CLI)

bash

claude mcp add --transport http floniks https://api.floniks.com/api/v1/mcp \
  --header "Authorization: Bearer mk_YOUR_KEY"

Claude Desktop & Cursor

These clients speak stdio, so bridge to the HTTP endpoint with mcp-remote — no build step. Add this to claude_desktop_config.json (Claude Desktop) or ~/.cursor/mcp.json (Cursor), then fully restart the app.

json

{
  "mcpServers": {
    "floniks": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://api.floniks.com/api/v1/mcp",
        "--header", "Authorization: Bearer mk_YOUR_KEY"
      ]
    }
  }
}

Advanced: you can also run the stdio server directly from source — pnpm --filter @pixify/mcp-server build and point command: node at dist/index.js with a PIXIFY_API_KEY env var.

Tools reference

19 tools today, grouped by purpose

Workflows

list_workflowsList the authenticated user's workflows, newest first.

get_workflowFetch a full workflow definition (nodes + edges + viewport).

create_workflowCreate a new workflow from nodes/edges (React Flow format).

generate_workflowGenerate a workflow graph from a natural-language brief — no credits charged.

update_workflowReplace a workflow’s name / nodes / edges. Owner-only.

delete_workflowDelete one of your workflows.

execute_workflowRun a workflow with inputs; returns a task id.

get_taskPoll task status + outputs (2xxx = done, 5xxx = failed).

Discovery & assets

list_templatesBrowse public workflow templates.

get_templateGet a template’s full node/edge graph to clone.

list_modelsList available AI models by capability type & provider.

get_model_paramsGet a model’s parameter schema (basic/advanced) to fill node config.

list_model_aliasesList single-task model aliases (AI Image/Video) — required for single_task.

list_node_typesList all node types (I/O, cost, which need a model) to compose workflows.

list_charactersList your character passports (cross-shot consistency).

list_locationsList your location passports (scene consistency).

list_creationsList your past single-task generations + output URLs.

Generation

single_taskOne-shot generation (text→image, image→video…) without a workflow. Spends credits; auto-refunds on failure.

Account

get_credit_balanceRead your credit balance before running jobs.

Roadmap

Coming soon

mint_character / mint_locationCreate a consistency passport from a reference.

upload_image / upload_videoUpload media and get a hosted URL for inputs.

Agent recipes

What to say once connected

Generate a poster

“List image models, pick a fast one, then build and run a textToImage workflow for “neon city street food festival, 4:5”.”

One-shot image (no workflow)

“List text→image model aliases, pick a fast one, then single_task it for “neon city street food festival, 4:5”. Poll get_task for the output URL.”

Short drama with a consistent lead

“List my characters, then build a 3-shot workflow (textToImage → imageToVideo per shot) that reuses the lead’s reference so the face stays consistent across shots.”

Clone a template and run it

“Find the “short-drama-cat-rain” template, clone it into a new workflow with create_workflow, then run it with my own prompt.”

Iterate after a run

“Run workflow X, poll get_task, and if a node failed, update_workflow to swap the model from list_models and run again.”

For an orchestration agent, the reliable loop is: discover (list_models / list_templates / list_characters) → assemble (create_workflow / update_workflow) → run (execute_workflow) → poll (get_task) → iterate. Check get_credit_balance first to avoid mid-run failures.

Troubleshooting

401 / Unauthorized: The Bearer token is wrong, expired, or has stray whitespace. Recreate a key on the API page and paste it exactly.
Claude Desktop doesn’t show floniks: Fully quit and relaunch (Quit, not just close the window). Verify npx is on your PATH and the mcp-remote args match the example.
execute_workflow runs but inputs are ignored: Match input keys to the node id (most reliable) or its label from get_workflow, e.g. { "textInput-123": "a fishing harbor at dawn" }.
Inspect the raw protocol: Use the official inspector: npx @modelcontextprotocol/inspector, then enter the URL and Bearer token to watch JSON-RPC frames.

Going deeper?

Prefer raw HTTP? The same capabilities are available as a REST API with an OpenAPI schema and webhooks.

Open the API console