PostSider

@postsider/mcp

MCP (Model Context Protocol) server that gives AI agents selected access to a PostSider instance through its public API. Works with Claude Code, Claude Desktop, Codex, Cursor, and any MCP-compatible client. Talks to cloud (api.postsider.com) or a self-hosted instance, authenticated with an organization API key.

PostSider is a shared operational calendar: the agent prepares and schedules work, and a human reviews what actually goes live.

Install

1. Create an API key

In PostSider, open Settings -> API and generate an organization API key.

2. Connect your client

Claude Code:

claude mcp add postsider -e POSTSIDER_API_KEY=your_api_key -- npx -y @postsider/mcp

Codex CLI and its IDE extension share MCP configuration. Use one of these options for a server named postsider.

Hosted MCP with OAuth (no organization key pasted into a config file):

codex mcp add postsider --url https://mcp.postsider.com/mcp

Complete the PostSider sign-in and permission flow in your client.

Alternatively, run the local MCP package over stdio with an organization API key stored in your environment or secret manager:

codex mcp add postsider --env POSTSIDER_API_KEY=your_api_key -- npx -y @postsider/mcp

The local organization key has broad access to your workspace. Never commit it to a repository or include it in an agent prompt. For a guided walkthrough and a first safe draft, see https://postsider.com/developers/.

Claude Desktop or any generic MCP client:

{  "mcpServers": {    "postsider": {      "command": "npx",      "args": ["-y", "@postsider/mcp"],      "env": {        "POSTSIDER_API_KEY": "your_api_key"      }    }  }}

3. Verify with a read-only prompt

Ask your agent, and confirm it answers without changing anything:

List my connected PostSider channels. Do not create or modify anything.

Then:

Show my PostSider calendar for the next 14 days. Do not create or modify anything.

4. Only then prepare a draft

The MCP create-post tool defaults to draft, not schedule or now. posts:write is a powerful permission: it does not inherently require human approval for each publication. An agent must not schedule or publish without explicit authorization for the content, channel and timing. Use postsider_get_post to verify a write before reporting success.

Create one draft only for the selected channel. Show me the exact content first. Do not publish it.

From source

pnpm --filter @postsider/mcp build

Then point your client at the built entrypoint:

{  "mcpServers": {    "postsider": {      "command": "node",      "args": ["/absolute/path/to/apps/mcp/dist/index.js"],      "env": {        "POSTSIDER_API_KEY": "your_api_key",        "POSTSIDER_API_URL": "https://api.postsider.com"      }    }  }}

Claude Code plugin

The package directory is also a Claude Code plugin: .claude-plugin/plugin.json declares the API key as a secret user setting, .mcp.json starts this server at the pinned released version, and skills/ contains focused workflows for calendar review, content publishing, approvals, analytics, and agency operations. The repository root is a plugin marketplace, so the plugin installs from the repository directly:

Skill budget is full (5/5). The remote server advertises the skills it bundles through OpenAI's skills extension, which supports at most 5. All five slots are taken, so adding a new skill requires retiring or merging an existing one (loadSkillCatalog fails closed above 5).

claude plugin marketplace add lumizone/postsiderclaude plugin install postsider@postsider

Installation stores the key outside the plugin: pass it at install time with --config api_key=your_api_key, or set it afterwards with /plugin configure postsider@postsider inside Claude Code. The key is never written into the plugin directory.

What the agent can do

40 tools on the hosted server, 41 on the local stdio server, and 42 on the local stdio server when you opt in to approval decisions (see Configuration), all prefixed postsider_.

Read

Write

Access scopes (remote server)

Billing, team and roles, API keys, MFA, account deletion and resuming a paused workspace are deliberately not available to agents; they stay in the dashboard.

Every tool declares readOnlyHint, destructiveHint, idempotentHint and openWorldHint explicitly, so a client can tell a read from a kill switch.

For the exact API endpoint/scope matrix, a no-publication draft → readback → schedule → status test and the Claude/Codex/Cursor verification checklist, see API & MCP trust checklist.

Configuration

POSTSIDER_API_URL must be HTTPS. Plain HTTP is accepted only on loopback (localhost, 127.0.0.1, [::1]) for local development.

For a self-hosted instance, point POSTSIDER_API_URL at where the public API is served. Behind the bundled nginx the API lives under /api, so use your domain plus /api, e.g. https://social.example.com/api. The server appends /public/v1 to whatever you set.

Safety

• The API key is read from the environment and sent only to the configured PostSider API URL. It is never printed, logged, or included in an error.
• Credentials embedded in POSTSIDER_API_URL are rejected.
• Redirects are refused rather than followed: a redirect would move an authenticated request off the configured origin, so the client fails with an actionable message instead.
• Requests time out after 30 seconds, and a failing response body is read up to 8 KB before being reported.
• Tool arguments are validated locally, before any network call: ids must be non-empty, dates must be real ISO 8601 dates (2026-02-30 is refused, not sent to the API), post status draft or schedule, and media imports require a public HTTPS URL.
• Deciding an approval is opt-in and local only. postsider_decide_approval is absent unless you start the local stdio server with POSTSIDER_MCP_ALLOW_APPROVAL_DECISIONS=true, the hosted server never offers it (OAuth tokens cannot hold approvals:decide), and the API key itself must carry the approvals:decide scope. The API refuses a key that requested the approval or created the post, so an agent cannot approve its own work. The tool reads the approval first and ties its Idempotency-Key and an expectStage value to the current stage and request time, so a retry of the same decision is harmless and a stale call cannot decide a later stage (it gets a 409).
• A missing API key exits 1 with an explanatory message on stderr. stdout carries protocol frames only.

Development

pnpm --filter @postsider/mcp typecheckpnpm --filter @postsider/mcp typecheck:testspnpm --filter @postsider/mcp testpnpm --filter @postsider/mcp buildpnpm --filter @postsider/mcp version:gatepnpm --filter @postsider/mcp validate:registrypnpm --filter @postsider/mcp smoke:tarballclaude plugin validate --strict apps/mcp

Design

This server is a thin wrapper over selected /public/v1 REST API endpoints, authenticated with the raw API key. It has no dependency on the backend and pulls in only @modelcontextprotocol/sdk and zod, so it stays lean and easy to maintain. All tool registrations live in a single factory, so the stdio transport today and any future transport share one agent-facing surface.