> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.flockx.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.flockx.io/_mcp/server.

# Connect to Flockx with MCP

> Manage your Flockx agents, media, and social profiles, and generate or publish content, from Cursor, Claude Code, and any Model Context Protocol (MCP) client.

The Flockx Model Context Protocol (MCP) server lets you manage your organization's agents, media library, and connected social profiles - and generate images and video, and review and publish social content - directly from any MCP-compatible client - Cursor, Claude Code, Claude Desktop, and others. Instead of switching to the web app or writing API calls, you ask your assistant in plain language ("list my agents", "draft a LinkedIn post about our launch") and it acts on your Flockx organization on your behalf.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) is an open standard that lets AI assistants connect to external tools and data. The Flockx MCP server is a remote server you connect to over HTTPS. It exposes a small, curated set of tools (listed below) scoped to your organization.

Authentication uses your normal Flockx login through a standard OAuth 2.1 browser flow. You never copy or paste an API key for MCP - your client opens a browser window, you log in to Flockx, approve access, and the connection is ready.

> **Info**
>
> The server endpoint is `https://mcp.flockx.io/mcp`. Most clients only need this URL - they discover everything else (login, permissions, available tools) automatically.

## Prerequisites

Before you connect, make sure you have:

1. **A Flockx account** with access to at least one organization. If you do not have one, sign up at [flockx.io](https://flockx.io).
2. **An MCP-compatible client** - for example [Cursor](https://cursor.com), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), or Claude Desktop.
3. **A browser** on the same machine, for the one-time login step.

You do not need an API key, client secret, or any manual token configuration. The MCP login is handled entirely through the OAuth browser flow.

## Connect your client

The Flockx MCP server is a remote HTTP server. Configuration differs slightly per client, but the pattern is the same everywhere: point the client at `https://mcp.flockx.io/mcp` and complete the browser login when prompted.

#### Cursor

Add the Flockx server to your Cursor MCP configuration file at `~/.cursor/mcp.json` (create it if it does not exist):

```json
{
  "mcpServers": {
    "flockx": {
      "url": "https://mcp.flockx.io/mcp"
    }
  }
}
```

After saving, open **Cursor Settings > MCP**. You will see the `flockx` server with a **Needs Login** (or **Connect**) button. Click it - Cursor opens a browser window where you log in to Flockx and approve access. Once approved, the server status turns green and the Flockx tools become available to the assistant.

#### Claude Code

Add the server from your terminal with a single command:

```bash
claude mcp add --transport http flockx https://mcp.flockx.io/mcp
```

Then start Claude Code and run `/mcp`. Select **flockx** and choose **Authenticate** - Claude Code opens a browser for the Flockx login and consent step. After you approve, the tools are ready to use.

#### Claude Desktop

Open **Settings > Connectors** (or **Developer > Edit Config**) and add a custom connector pointing at:

```
https://mcp.flockx.io/mcp
```

Claude Desktop will prompt you to sign in through your browser the first time you use a Flockx tool. Approve the request to finish connecting.

#### Generic MCP client

Any client that supports remote (Streamable HTTP) MCP servers with OAuth 2.1 can connect:

* **Server URL:** `https://mcp.flockx.io/mcp`
* **Transport:** Streamable HTTP
* **Auth:** OAuth 2.1 (authorization code with PKCE). The server advertises its requirements at `https://mcp.flockx.io/.well-known/oauth-protected-resource/mcp`, and clients that support Dynamic Client Registration will self-register automatically.

When the client first calls the server with no credentials, the server responds with a `401` and a pointer to the metadata above. A compliant client uses that to discover the Flockx login, complete a PKCE browser login, and obtain an access token scoped to your organization.

## Choose your organization

Your Flockx account can belong to more than one organization, and each organization has its own agents, media, and connected profiles. Because your MCP login identifies *you* but does not pick an organization for you, every tool that reads or writes data needs to know which organization to act in. This keeps data access explicit and predictable rather than guessing on your behalf.

The flow is:

1. **Discover** the organizations you can use by calling `list-organizations`. It returns each organization's `id` and `name`.
2. **Select** one of two ways:
   * Pass the `organization_id` argument on any tool call (ask your assistant "…in my *Acme* organization" and it fills this in), or
   * Set the `X-Organization` header once in your client config to pin an organization for the whole session.

If you supply both, the `organization_id` argument wins for that call. If you supply neither, the tool fails with a clear message telling you to call `list-organizations` first - it never picks one silently.

> **Info**
>
> Most people just ask their assistant to "list my organizations" once, then refer to the one they want by name. The assistant passes the matching `organization_id` for you.

To pin an organization for every call without repeating yourself, add the `X-Organization` header to your client config. For Cursor:

```json
{
  "mcpServers": {
    "flockx": {
      "url": "https://mcp.flockx.io/mcp",
      "headers": {
        "X-Organization": "your-organization-id"
      }
    }
  }
}
```

## Capabilities

Every tool runs against the organization you select (see [Choose your organization](#choose-your-organization)). You can only see and change assets that belong to an organization you are a member of.

### Organizations

| Tool                 | What it does                                                                                                                                                      |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list-organizations` | List the organizations you can act in. Call this first to get the `id` you pass as `organization_id` (or set as the `X-Organization` header) on every other tool. |

### Agents

| Tool           | What it does                                                                                    |
| -------------- | ----------------------------------------------------------------------------------------------- |
| `list-agents`  | List the agents in your organization, optionally filtered by name.                              |
| `get-agent`    | Get the full configuration of one agent (personality, channels, integrations, knowledge graph). |
| `create-agent` | Create a new agent with a name and optional personality, website, and category.                 |
| `update-agent` | Update an existing agent's name, personality, or website.                                       |

### Media

| Tool                   | What it does                                                                                                                                                                                                    |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list-media`           | List media assets (images, videos, documents, written artifacts), optionally filtered to one agent, by kind (`resource_type`), by document format (`format`), or by the pipeline that produced them (`source`). |
| `get-media`            | Get the details of a specific media asset, including its URL and metadata.                                                                                                                                      |
| `add-media`            | Add a media asset to your library, either by `url` (subject to your plan's storage limits) or by supplying `text_content` directly to author a markdown document or HTML visualization with no upload step.     |
| `update-media`         | Update a media asset's name, description, or - for text artifacts - its content.                                                                                                                                |
| `generate-image`       | Start generating an image with the organization's brand context applied. Returns a `generation_id` to poll with `get-image-generation`.                                                                         |
| `get-image-generation` | Check whether an image generation has finished, and collect the image URL when complete.                                                                                                                        |

### Social

| Tool                      | What it does                                                                                                                                                         |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list-social-profiles`    | List the social accounts (Instagram, Facebook, and others) connected to your organization.                                                                           |
| `list-social-posts`       | List your organization's social posts at any stage - draft, approved, scheduled, published, or errored - optionally filtered by `status` or to only scheduled posts. |
| `generate-social-content` | Start generating social post drafts from a brief. Generation runs in the background; check `list-social-posts` a little later to see the results.                    |
| `publish-social-draft`    | Approve, schedule, or publish an existing draft, depending on the arguments you pass.                                                                                |

### Video generation

| Tool                   | What it does                                                                                                                                                                             |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `generate-video`       | Start generating a video - from a text prompt, by animating an existing image, or from up to nine reference images. Returns a `video_generation_id` to poll with `get-video-generation`. |
| `get-video-generation` | Check whether a video generation has finished, and collect the video URL when complete.                                                                                                  |

### Storefront

The Flockx storefront sells one-off, pay-once digital products - independent of any subscription. These tools let you browse the catalog and buy a product on the spot; only `video` products are fulfilled today.

| Tool                         | What it does                                                                                                                                                           |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list-storefront-products`   | Browse the storefront catalog, optionally filtered by product type, tag, or region (for regional pricing).                                                             |
| `get-storefront-product`     | Get a product's full detail - its price, customization options, and required inputs - before buying it.                                                                |
| `create-storefront-checkout` | Start a real, paid purchase and get back a Stripe-hosted checkout link to open in a browser. Nothing is generated and no money moves until you complete payment there. |
| `get-storefront-purchase`    | Check a purchase's payment and fulfillment status, and collect the result URL once it is ready.                                                                        |

> **Info**
>
> A storefront purchase is billed to and generated for an organization, but is always scoped to whoever bought it: `get-storefront-purchase` only shows purchases made by your account, regardless of which organization you were acting in at checkout.

## Permissions

When you connect, your client requests a set of permissions (called *scopes*) that define what the assistant can do. Flockx groups them by asset type and by read versus write:

| Scope              | Grants                                                                  |
| ------------------ | ----------------------------------------------------------------------- |
| `agents:read`      | List and view agents                                                    |
| `agents:write`     | Create and update agents                                                |
| `media:read`       | List and view media, and check image generation status                  |
| `media:write`      | Add and update media, and generate images                               |
| `socials:read`     | List social profiles and posts, and check video generation status       |
| `socials:write`    | Generate social drafts and video, and publish or schedule social drafts |
| `storefront:read`  | Browse storefront products and check purchase status                    |
| `storefront:write` | Start a storefront checkout (purchase)                                  |

You approve these permissions on the consent screen during login. Write actions (creating or updating assets) always respect your organization's plan limits and quotas, exactly as they do in the web app.

## Try it out

Once connected, ask your assistant something like:

* "Which Flockx organizations can I use?" (runs `list-organizations`)
* "List the agents in my *Acme* organization."
* "Create a Flockx agent named *Cafe Concierge* in *Acme* with a friendly, helpful personality."
* "Show me the media assets attached to my *Cafe Concierge* agent."
* "What social profiles are connected in *Acme*?"
* "What's in my *Acme* review queue?" (lists `DRAFT` social posts)
* "Draft three LinkedIn posts about our new product launch for *Acme*."
* "Generate a brand image of a cup of coffee for *Acme* and add it to the library."
* "Make a five-second video of our logo animating in."
* "What can I buy in the Flockx storefront?"
* "Buy the AI video reel product for *Acme* with a prompt about our new menu."

The assistant calls the matching Flockx tool, passes the organization you named, and shows you the result. If you have not named an organization yet, start with the first prompt so the assistant knows which one to use.

> **Warning**
>
> `publish-social-draft`, `generate-video`, and `create-storefront-checkout` take real, sometimes irreversible action - a scheduled or immediate publish goes out to your connected social accounts, video/image generation consumes your plan's generation quota, and checkout hands back a real Stripe payment link. Review what your assistant is about to do before confirming.

## Troubleshooting

| Issue                                          | What to check                                                                                                                                                                    |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Client shows "Needs Login" and never connects  | Make sure a browser is available on the same machine and complete the Flockx login when the window opens.                                                                        |
| "No organization specified" error              | Call `list-organizations` (ask "which organizations can I use?"), then name the one you want, or set the `X-Organization` header in your client config.                          |
| "Organization … is not available to you" error | The `organization_id` is not one you belong to (or belongs to a different app). Call `list-organizations` to see the ids you can use.                                            |
| `list-organizations` returns an empty list     | Your account is not a member of any organization in this app yet. Set one up in the Flockx web app first.                                                                        |
| "Not found in your organization" errors        | The agent or media ID you referenced belongs to a different organization. Use `list-agents` or `list-media` (with the right `organization_id`) to find IDs in your organization. |
| Tools are missing in the client                | Re-open your client's MCP settings and confirm the `flockx` server status is connected (green), then refresh the tool list.                                                      |

## Related

* [API Authentication](https://docs.flockx.io/documentation/getting-started/api-authentication) - for direct REST API access with an API key
* [Create an Agent](https://docs.flockx.io/documentation/getting-started/create-agent) - build your first agent in the web app
* [Agent Workbench](https://docs.flockx.io/documentation/getting-started/agent-workbench) - manage agents in the web app