Skip to main content

MCP Server

Mixpost ships with a built-in MCP (Model Context Protocol) server that lets AI agents — such as Claude, ChatGPT, Cursor, or any MCP-compatible client — manage your workspaces directly. An agent can list your connected social accounts, browse posts, tags and media, read analytics, and create, schedule, publish, or clean up posts on your behalf, all through a single secure endpoint.

What is MCP?

The Model Context Protocol is an open standard for connecting AI assistants to external tools and data. The Mixpost MCP server exposes a set of tools that an AI agent can call to interact with your instance — no custom integration code required.

What you can do​

With the Mixpost MCP server, you can ask your AI assistant to:

  • "Show me everything scheduled for next week"
  • "Draft a post for my X and LinkedIn accounts announcing our new feature"
  • "Write a thread for X about our roadmap and save it as a draft"
  • "Post our launch on LinkedIn with the link in the first comment, mentioning @Acme"
  • "Schedule my latest draft for Tuesday at 9am"
  • "Take Friday's post off the calendar and keep it as a draft"
  • "Add this post to the publishing queue"
  • "Which social accounts are connected to my Acme workspace?"
  • "Create a 'Launch' tag and apply it to all my draft posts"
  • "Upload this image from a URL and attach it to a new post"
  • "Find my failed posts and tell me what went wrong"
  • "Duplicate last month's announcement and reschedule it for Friday"
  • "Move all the drafts from the old campaign to the trash"
  • "List the videos in my media library"
  • "Which of my accounts grew the most last month?"
  • "How did yesterday's launch post perform on each network?"
  • "Schedule this post for the best time to reach my audience next week"

Authentication​

There are two ways for a client to connect:

  • Sign in with OAuth — for clients that support it, such as ChatGPT and Claude on the web and desktop. You add the MCP server URL, click Connect, sign in to Mixpost and allow access. There is nothing to copy. See Sign in with OAuth.
  • Personal key — for clients that send a fixed Authorization header, such as Claude Code, Cursor, Codex or n8n. Create one under API in the user menu — see Create a personal key.
Step-by-step instructions for your instance

Open Integrations from the user menu. It lists Claude, ChatGPT, n8n, Cursor and other clients, each with the settings for your own instance ready to copy, and can create a personal key on the spot.

Connect your client​

The MCP server is exposed over streamable HTTP at a single endpoint on your instance:

https://example.com/mcp
Is Mixpost under a path? e.g. https://example.com/<path>/...

Keep that path in every address on this page, or requests return 404. Your exact address is under Admin Console → Status → Server & Drivers → Base URL.

Not sure what this means? Skip this note.

Point your MCP client at that URL. Clients that support OAuth sign you in; the others send a personal key in the Authorization header. The exact configuration depends on your client.

In Claude on the web or desktop, open Settings → Connectors and choose Add custom connector. Enter a name and the MCP server URL, then click Connect, sign in to Mixpost and allow access.

On Team and Enterprise plans, an owner adds the connector first under Organization settings → Connectors; each member then clicks Connect and signs in with their own account.

Sign in with OAuth​

Each Mixpost instance is its own OAuth server, so clients such as ChatGPT and Claude connect without a personal key. When a client connects, Mixpost shows a consent screen with the app's name, the domain it returns to — marked verified for well-known clients — what it will be able to do, and the account you are signed in with. Click Allow access to connect.

Screenshot:
OAuth consent screen
  • The app acts as you, with your role in each workspace, exactly like a personal key.
  • It works only on the MCP server. Its tokens are rejected by the REST API.
  • The client keeps itself signed in. Access tokens last an hour and the client renews them on its own. The renewal is valid for 90 days and starts over each time it is used, so you only sign in again after 90 days without using the app.
  • You stay in control. Connected apps, in the user menu, lists every app you allowed; Disconnect removes its access straight away.

Sign in with OAuth is on by default. On a self-hosted instance it can be turned off with MIXPOST_OAUTH=false, and ChatGPT and Claude can only reach an instance that is publicly available over HTTPS.

Administrators decide which clients may connect and can block one for everyone; client developers find the endpoints and flows in the reference. See OAuth.

Verify the connection​

Once your client is configured, confirm it works by asking your assistant to list your workspaces. If they come back, the endpoint and token are set up correctly and you can start working in any of them. If nothing happens, see Troubleshooting.

How it works​

Everything in Mixpost is organised into workspaces, and almost every tool operates on a single workspace. Because of this, the workflow always starts the same way:

  1. Call list-workspaces to get the uuid of each workspace the token can access.
  2. Pass the chosen uuid as the workspace argument to every other tool.

For publishing, you then resolve the accounts to post to:

  1. Call list-accounts (with the workspace uuid) to get the numeric account IDs.
  2. Call create-post with the same workspace uuid and those account IDs.

Your agent receives these instructions automatically when it connects, so in practice you can simply ask it in natural language — for example, "Draft a post for next Tuesday at 9am on my LinkedIn and X accounts" — and it will chain the right tools together.

See the full Tools reference for everything the server can do.

Roles and permissions​

The token owner's role in a workspace determines which tools they can use:

RoleRead (list / get)Create, update, schedule, delete
Viewer✅❌
Member✅✅
Admin✅✅

The one read tool reserved for members and admins is list-mentions, since mentions are only used to write posts.

If a workspace requires post approval, posts scheduled or queued through the MCP server enter the needs approval state instead of being published immediately.

For security, a workspace the token cannot access is reported as "not found" — identical to a workspace that does not exist — so it is impossible to probe for other workspaces.

Token efficiency​

Every response is trimmed to what an agent actually needs, so a conversation does not fill up with payload it will never read. Post listings return a compact summary rather than the dashboard's full object, and get-post returns the text and media ids of each content version but leaves the costly parts — resolved media, per-provider options, content URLs, video thumbnails — out unless they are named in its include argument. Tools that only flip a flag, such as unschedule-post and delete-post-version, answer with a short message instead of restating the whole post.

Timezones​

All dates and times are stored in UTC. Most tools accept an optional timezone argument (an IANA identifier such as America/New_York or Europe/Chisinau) that controls how datetimes are interpreted in your input and formatted in the response. When omitted, it falls back to your account's configured timezone, then to UTC. Each response echoes the timezone it used. The analytics tools that report figures — get-analytics-summary, get-account-analytics and get-post-analytics — are the exception: they always report UTC days and take no timezone.

Running into issues connecting or using the tools? See Troubleshooting.

On this page