Integrations

Connect to Flockx with MCP

The Flockx Model Context Protocol (MCP) server lets you manage your organization’s agents, media library, and connected social profiles 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”, “create an agent named Cafe Concierge”) and it acts on your Flockx organization on your behalf.

What is MCP?

The Model Context Protocol 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.

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.
  2. An MCP-compatible client - for example Cursor, 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.

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

1{
2  "mcpServers": {
3    "flockx": {
4      "url": "https://mcp.flockx.io/mcp"
5    }
6  }
7}

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.

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.

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:

1{
2  "mcpServers": {
3    "flockx": {
4      "url": "https://mcp.flockx.io/mcp",
5      "headers": {
6        "X-Organization": "your-organization-id"
7      }
8    }
9  }
10}

Capabilities

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

Organizations

ToolWhat it does
list-organizationsList 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

ToolWhat it does
list-agentsList the agents in your organization, optionally filtered by name.
get-agentGet the full configuration of one agent (personality, channels, integrations, knowledge graph).
create-agentCreate a new agent with a name and optional personality, website, and category.
update-agentUpdate an existing agent’s name, personality, or website.

Media

ToolWhat it does
list-mediaList media assets (images, videos, documents), optionally filtered to one agent.
get-mediaGet the details of a specific media asset, including its URL and metadata.
add-mediaAdd a media asset to your library by URL (subject to your plan’s storage limits).
update-mediaUpdate a media asset’s metadata, such as its display name.

Social profiles

ToolWhat it does
list-social-profilesList the social accounts (Instagram, Facebook, and others) connected to your organization.
list-social-postsList your organization’s social posts, both published and scheduled.

Social tools are read-only today. Publishing posts through MCP is planned for a future release.

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:

ScopeGrants
agents:readList and view agents
agents:writeCreate and update agents
media:readList and view media
media:writeAdd and update media
socials:readList social profiles and posts
socials:writeReserved for future publishing support

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?”

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.

Troubleshooting

IssueWhat to check
Client shows “Needs Login” and never connectsMake sure a browser is available on the same machine and complete the Flockx login when the window opens.
”No organization specified” errorCall 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” errorThe 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 listYour 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” errorsThe 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 clientRe-open your client’s MCP settings and confirm the flockx server status is connected (green), then refresh the tool list.