Docs
Everything your agent needs to run the channel.
Post Ripple exposes one agent surface: an MCP server for clients that speak MCP, and the same 51 tools as plain HTTP endpoints for everything else. Both authenticate with a personal, scoped API key. Both are included on every paid plan.
The MCP server is a thin local process. It registers 51 tools,
and each one is a single POST to the Post Ripple API — no state of its own, nothing cached, nothing
to keep in sync. If your client can't run an MCP server, you lose
nothing by calling the endpoints directly.
Keys are personal. A key acts as the member who created it, its membership is re-verified on every request, and it carries only the scopes you checked when you made it. Revoke it and every agent holding it loses access on the next call.
Quickstart
Connected in three steps
There's no SDK to install and no OAuth dance. One key, one config block, one question to confirm it worked.
Create a key
In Post Ripple, open Settings → API Keys and create one. Pick its scopes — publish is off unless you turn it on. The key is shown once, so paste it straight into your agent's config.
Paste one snippet
One line for Claude Code, one block for everything else. The server runs locally over stdio and reads your key from POSTRIPPLE_API_KEY. That's the whole configuration.
Ask your agent
Restart the client and try “What's in my Post Ripple workspace?” It calls whoami, and the call shows up in your audit log on the same API Keys page.
Client setup
Pick your client
The server is a local stdio process launched with npx, so any MCP client that can start one works. Swap pr_... for your key. There is no hosted endpoint to point at.
Claude Code
claude mcp add postripple \
-e POSTRIPPLE_API_KEY=pr_... \
-- npx -y @post-ripple/mcp@latestRun it, then restart Claude Code.
Claude Desktop
{
"mcpServers": {
"postripple": {
"command": "npx",
"args": ["-y", "@post-ripple/mcp@latest"],
"env": { "POSTRIPPLE_API_KEY": "pr_..." }
}
}
}Merge into the config, then quit and reopen the app.
Cursor
{
"mcpServers": {
"postripple": {
"command": "npx",
"args": ["-y", "@post-ripple/mcp@latest"],
"env": { "POSTRIPPLE_API_KEY": "pr_..." }
}
}
}Project-local file, same shape. Reload the window.
Codex
[mcp_servers.postripple]
command = "npx"
args = ["-y", "@post-ripple/mcp@latest"]
env = { POSTRIPPLE_API_KEY = "pr_..." }Add the block, then restart Codex.
opencode
{
"mcp": {
"postripple": {
"type": "local",
"command": [
"npx", "-y", "@post-ripple/mcp@latest"
],
"environment": {
"POSTRIPPLE_API_KEY": "pr_..."
}
}
}
}Merge into opencode.json, then restart opencode.
Any MCP client
command: npx -y @post-ripple/mcp@latest
env: POSTRIPPLE_API_KEY=pr_...Register a local stdio server with this command and env.
One optional variable is worth knowing: POSTRIPPLE_ORG pins a default organization for keys that span several. A per-call
organizationId always wins over it.
Scopes
You decide what a key can reach
Three scopes, checked independently when you create the key. A call
outside a key's scopes fails with insufficient_scope — it doesn't partially run.
read
25 tools
List content, posts, accounts, and analytics
Everything an agent needs to answer questions about the workspace. Nothing it can call changes state.
content:write
20 tools
Create and organize videos, groups, and content
Creates content in your libraries. It can't put a post on an account or wire a rotation to one — that needs publish. It isn't inert, though: adding videos to a rotation that a publish-scoped key (or a human) already wired up re-rolls which videos that rotation will publish, and when.
publish
6 tools
Schedule and cancel posts to connected social accounts, and manage rotation-group schedules
Required for schedule_post, publish_slideshow, anything that edits a queued post, and update_group_schedule — which hands an account a rotation queue that publishes on its own. Unchecked by default when you create a key; opt in deliberately.
Organizations
Which workspace am I in?
A key is personal, not per-workspace, so it works in every
organization you belong to unless you restricted it to one at
creation. Start with whoami: it reports who the key acts as, its scopes, and the organizations
it can work in.
After that there are three ways a call resolves a workspace. Pass
organizationId explicitly, set POSTRIPPLE_ORG once as a default, or rely on the key having access to exactly one.
If none of those apply, the call returns ambiguous_org rather than guessing which brand you meant.
> What's in my Post Ripple workspace?
⏺ postripple · whoami
member: you · scopes: read, content:write
organizations:
org_7fa2… My Brand
org_c41b… Second BrandReference
Read the details
Tool reference
All 51 tools
Every tool the server registers, grouped by the scope it needs, with what each one does and which ones are asynchronous.
Browse toolsHTTP reference
Call it without MCP
The endpoint pattern, both auth header forms, the response envelope, and every error code the API can return.
Read the API docsCommon questions
Before you wire it up
What do I need to use the Post Ripple API?
A paid plan and an API key. Every paid plan includes Agent API and MCP access. Create a key under Settings → API Keys in Post Ripple, give it to your agent as POSTRIPPLE_API_KEY, and you're connected.
Do I have to use the MCP server?
No. The MCP server is a thin wrapper over a plain HTTP API — every tool is a POST to https://api.postripple.app/agent/v1/<tool> with a JSON body and a bearer token. Use the MCP server if your client speaks MCP; call the endpoints directly from a script or a backend if it doesn't.
Which MCP clients work?
Any client that can launch a local stdio MCP server. That includes Claude Code, Claude Desktop, Cursor, Codex, and opencode. There is no hosted or remote MCP endpoint — the server runs on your machine and talks to the API from there.
Can an agent post to my real accounts?
Putting a post on an account, or wiring a rotation to one, requires the publish scope, which is off by default: schedule_post and publish_slideshow for a specific piece of content, and update_group_schedule for standing up or re-pointing an auto-publishing rotation group. A content:write key can still add videos to a rotation someone already wired up — which re-rolls which videos that rotation will publish, and when. If your team has approval enabled, publish-scoped calls create in-review items instead of scheduling, and return submittedForReview: true — and rotation groups are unavailable entirely while approval is on.
What happens if I have more than one workspace?
Keys are personal, so one key works in every organization you belong to unless you restricted it at creation. Pass organizationId per call, or set POSTRIPPLE_ORG to pin a default. If a call is ambiguous, the API returns ambiguous_org and whoami lists your organizations.
Can I see what an agent did?
Yes. Every call is audit-logged and attributed to the member who created the key, and the log is visible in-app under Recent agent activity on the API Keys page. You can revoke a key there at any time, and agents using it lose access immediately.
How do I stop an agent from double-posting?
Pass an idempotencyKey on schedule_post and publish_slideshow. Any unique string works. A retry carrying the same key resolves to the same post instead of creating a second one.
Give your agent the keys.
Create a scoped key, paste one snippet, and ask it what's in your workspace. Every paid plan includes Agent API and MCP access.