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-21

• What the Floyi MCP server can do
• How to connect Claude, ChatGPT web, or Codex with a secure sign-in — no API key to manage
• How to connect developer clients with an API key
• 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

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

The fastest way to connect: add the Floyi endpoint in your assistant’s app or MCP settings, then approve the connection in your browser. You do not create, copy, or manage an API key — you sign into Floyi, choose the workspace, and approve.

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

claude mcp add --transport http floyi https://mcp.floyi.com/mcp

Approved connections appear in Floyi under Settings → API Keys → Connected Apps, showing the app, workspace, and last-used date. Disconnect there revokes access immediately.

• One active connection per app, per workspace, per user. Reconnecting the same app to the same workspace replaces your previous authorization — no duplicate entries. Teammates each have their own connections; a whole team can connect Claude to one team workspace simultaneously.
• Removing an app, connector, or MCP server inside a client does not always notify Floyi. If you want access cut off, disconnect it in Floyi — that is the authoritative revocation and takes effect immediately.
• Workspace binding is permanent per connection. You choose the workspace on the approval screen; to work in a different workspace, add a separate connection (e.g. name one connector “Floyi — Personal” and another “Floyi — Agency Team”).
• ChatGPT web and Codex connections are separate. Each has its own OAuth grant and permission settings, even when you use both through the ChatGPT desktop app.

Scripts, headless automations, and MCP clients that send custom headers can authenticate with an API key instead of OAuth. The MCP server shares keys with Floyi’s REST API — one key works for both.

1. Switch Floyi to the Personal or team workspace the key should use — a key is permanently bound to the workspace active when it is created.
2. Go to Settings > API Keys.
3. Click Create API Key and give it a descriptive name (e.g., “Reporting script”).
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.

{
  "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"
      }
    }
  }
}

Start a new conversation and ask:

Show which Floyi workspace this connection 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.
• Fair-use caps on free AI actions — a small set of free tools that trigger AI work on Floyi’s side (persona generation, brand-from-URL analysis, slug generation, research dedup, knowledge-base imports) have per-minute, daily, and monthly fair-use caps. The limits are generous for normal use; if a cap is reached, the tool says so and when to retry.

In a team workspace, credits come from the team owner’s pools — the same as in the app. This applies to OAuth connections bound to a team workspace too.

Access control

• OAuth connections — approved on a consent screen that shows the app and permissions; secured with short-lived, automatically rotating tokens. Revoke anytime in Settings > API Keys > Connected Apps.
• Scopes — each API key can execute only the tool calls its scopes allow (OAuth connections carry the standard full-pipeline permission set, shown on the approval screen). A client may still display tools the connection cannot run.
• Workspace isolation — a connection sees only its workspace’s brands. Team connections verify membership on every call; if you leave a team, your connections to it stop working.
• Plan enforcement — every call re-checks plan eligibility. A downgraded account’s connections and keys stop working immediately.
• Audit logging — every tool call is logged. Settings shows each connection’s last-used date; detailed audit records are retained server-side.
• Instant revocation — revoke a key or disconnect an app in Settings 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 connection is rate limited per minute:

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 the same data and permission model; 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? Claude (web and Desktop) via a custom connector, ChatGPT web via a developer-mode app, Codex in the ChatGPT desktop app, Claude Code, and any MCP client that supports Streamable HTTP. These clients can use OAuth; developer clients that support custom headers can use an API key instead.

Can my whole team use it? Yes. Each member connects their own assistant while the team workspace is selected on the approval screen — everyone gets their own connection, all scoped to the team’s brands, and paid actions draw from the team owner’s credit pools. For scripts and automations, create a separate API key per person or tool instead of sharing one.

Do I need an API key to use Claude, ChatGPT, or Codex with Floyi? No. These connection flows use OAuth — you sign in and approve without creating, copying, or managing an API key. API keys are only for developer clients and scripts.

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.