Floyi MCP Server

The Floyi MCP server connects compatible AI assistants directly to your Floyi workspace. Instead of switching between your AI assistant and the Floyi app, you work in one conversation: ask for your content gaps, generate a brief for the biggest one, turn it into a draft, and publish it to WordPress or GitHub — all through natural language.

MCP (Model Context Protocol) is an open standard that lets AI assistants securely use external tools. Floyi’s server exposes 99 tools covering the full pipeline: brand setup, audience personas, site architecture, topical research, AI Search Gaps, clustering, map building, briefs, drafts, quality review, publishing, and authority monitoring.

Last updated: 2026-07-18

• What the Floyi MCP server can do
• How to create an API key and connect your AI assistant
• How credits work when an AI assistant drives Floyi
• Security, workspaces, and built-in guardrails
• Troubleshooting common connection issues

An AI assistant connected to Floyi can:

• Explore your strategy — brands, topical maps, research trees, personas, and authority scores
• Find opportunities — content gaps, competitor gaps, AI search citation gaps
• Run the pipeline — take a brand from foundation through research, clustering, and map building
• Produce content — generate strategy-aware briefs and first drafts using Floyi’s own generation pipeline
• Read work back — pull finished briefs and MCP-readable draft content out of Floyi for review or reuse; the server flags web-editor-only content it cannot safely project
• Publish — send finished articles to connected WordPress sites or commit Markdown/MDX to connected GitHub repositories
• Monitor — refresh authority data, compare competitors, track AI search visibility

[!IMPORTANT] How writes work. Brief and draft generation run through Floyi’s own pipeline — the exact same generation tasks the web app uses. When you ask your assistant to “start a draft,” Floyi generates it natively (correct sections, internal links, map position, formatting) and saves it to your workspace. You are not asking the assistant to imitate Floyi; you are triggering Floyi to do the work, then reading the result back.

For the full tool list, see the MCP Tool Catalog. For example prompts and workflows, see MCP Use Cases & Workflows.

The MCP server uses the same API keys as Floyi’s REST API. One key works for both.

1. Switch Floyi to the Personal or team workspace the assistant should use.
2. Go to Settings > API Keys.
3. Click Create API Key and give it a descriptive name (e.g., “Claude - Content Team”).
4. Choose the key type. Integration defaults to the full read/write pipeline; Developer defaults to read-only access. Scopes control which tool calls succeed — a key without content:write cannot generate drafts, even though the client may still list the tool.
5. Copy the key immediately — it is shown only once.

[!TIP] One key holds all the scopes you grant it — you never need separate keys per feature. Create separate keys per person or tool instead, so you can revoke them independently. Scopes cannot currently be edited after creation; create a replacement key when the permission set needs to change.

Each key is bound to a workspace. A personal-workspace key sees your personal brands; a team-workspace key sees the team’s brands, and credit-spending actions draw from the team owner’s credit pools — the same as working in the app in that workspace.

{
  "mcpServers": {
    "floyi": {
      "type": "http",
      "url": "https://mcp.floyi.com/mcp",
      "headers": {
        "X-API-Key": "${FLOYI_API_KEY}"
      }
    }
  }
}

{
  "mcpServers": {
    "floyi": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp.floyi.com/mcp",
        "--header",
        "X-API-Key:${FLOYI_API_KEY}",
        "--transport",
        "http-only"
      ],
      "env": {
        "FLOYI_API_KEY": "fyi_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

[!NOTE] Never share your API key or commit it to a repository. If a key is exposed, revoke it in Settings > API Keys and create a new one — revocation takes effect immediately.

Start a new conversation and ask:

Show which Floyi workspace this key is bound to, then list its brands.

Confirm the returned workspace name before trusting the brand list. A good second prompt is “Read the Floyi capabilities first” — the floyi_capabilities tool teaches the assistant Floyi’s ground rules (which actions are irreversible, how long generations really take, and how credits work) before it starts working.

Tool calls themselves are free. Reading your map, searching topics, checking pipeline status, listing briefs — none of it costs credits, no matter how often the assistant calls.

Credits are spent only when a tool triggers a configured paid generation or data action. Most reuse the app’s pricing and workflow; the catalog calls out MCP-specific pricing where it differs, such as node-metrics fetching.

Built-in cost safety:

• Upfront balance checks — paid tools check the available balance before starting. If credits are insufficient, the error states the shortfall.
• Estimates and confirmations — high-blast-radius operations such as pipeline clustering and authority refresh enforce a confirmation step. Other paid tools expose their cost or support an estimate call, and the assistant is instructed to confirm that cost with you before starting.
• Balance visibility — paid responses return the cost and current available or remaining balance where the workflow provides it. Use floyi_credits for the authoritative current balance.
• Refund and settlement rules — a pending brief can be cancelled through MCP and its reserved credits refunded. Failed or cancelled pipeline clustering does not charge, and quality re-analysis settles only on success.
• Model choice — the assistant can list available AI models with their multipliers and choose a lower-cost model for an individual run or a one-at-a-time production sequence.

In a team workspace, credits come from the team owner’s pools — the same as in the app.

Access control

• Scopes — each key can execute only the tool calls its scopes allow. A client may still display tools the key cannot run.
• Workspace isolation — a key sees only its workspace’s brands. Team keys verify membership on every call.
• Audit logging — every tool call is logged. Settings currently shows each key’s last-used date; detailed audit records are retained server-side.
• Instant revocation — revoke a key in Settings > API Keys and it stops working immediately.

Guardrails on actions

The MCP server enforces the same rules as the app, plus agent-specific protections:

• High-blast-radius overwrites and paid runs use confirmation or estimate flows. Other destructive tools state their impact so the assistant can get your approval before acting.
• Map edits snapshot the map before applying, and hierarchy changes are revertible overrides.
• WordPress publishing defaults to WordPress-side draft status — nothing goes live without review.
• GitHub publishing commits directly to the configured branch, so the assistant must confirm the repository and branch first.
• Assistants can make targeted plain-text edits to draft sections, intros, and key takeaways. Full rich-text structure, formatting, links, embeds, visual review, and version restoration remain in the Floyi editor.
• Pipeline stage changes move forward by default. A guarded recovery path can return clustering or map-building stages to Topical Research; returning from Topical Authority remains blocked.

Rate limits

Every key is rate limited per minute according to its type:

How is this different from the Floyi REST API? The REST API is for code — scripts, integrations, and custom dashboards you build and maintain. The MCP server is for conversation — you (or a scheduled agent) direct the work in natural language and the assistant picks the right tools. They share API keys, scopes, and data; use whichever fits the job.

Does using MCP cost extra? There is no MCP connection fee or generic per-tool-call charge. Credits are spent only when you start one of the paid generation or data actions listed above.

Which AI assistants work with it? During the API-key beta: Claude Code, Claude Desktop through the local mcp-remote bridge, and clients that support Streamable HTTP plus custom headers. Native Claude web/Desktop connector support follows Floyi’s OAuth implementation.

Can my whole team use it? Yes — create separate keys for each person or automation while the team workspace is active. All calls are scoped to that team’s brands, and paid actions draw from the team owner’s credit pools. Do not share one key across the whole team.

What can’t it do? Complete rich-text editing and visual review, article images, connection setup, billing, team management, API-key management, and several app-specific import or analytics workflows remain in the app. See what still needs the web app.