@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

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

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/postsider-workflow/SKILL.md teaches the read-first, draft-first workflow. The repository root is a plugin marketplace, so the plugin installs from the repository directly:

claude plugin marketplace add lumizone/postsider
claude 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

19 tools, all prefixed postsider_.

Read

Write

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

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.
• A missing API key exits 1 with an explanatory message on stderr. stdout carries protocol frames only.

Development

pnpm --filter @postsider/mcp typecheck
pnpm --filter @postsider/mcp typecheck:tests
pnpm --filter @postsider/mcp test
pnpm --filter @postsider/mcp build
pnpm --filter @postsider/mcp version:gate
pnpm --filter @postsider/mcp validate:registry
pnpm --filter @postsider/mcp smoke:tarball
claude 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.