Docs/AI Agents/MCP Server

MCP Server

Octopost provides a Model Context Protocol (MCP) server that lets AI coding tools interact with your Octopost account directly. Create posts, manage your queue, check connected accounts, and more without leaving your editor or terminal.

What is MCP?

MCP is an open protocol that lets AI tools connect to external services. Once you add Octopost as an MCP server, your AI assistant can create and publish posts, manage your queue, and check your accounts on your behalf.

Setup

You only need one of these options. Pick the tool you use.

Claude Code

Run in your terminal:

claude mcp add octopost --transport http https://octopost.ink/mcp --header "Authorization: Bearer YOUR_API_KEY"

Gemini CLI

Run in your terminal:

gemini mcp add --transport http --header "Authorization: Bearer YOUR_API_KEY" octopost https://octopost.ink/mcp

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "octopost": {
      "url": "https://octopost.ink/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "octopost": {
      "serverUrl": "https://octopost.ink/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

OpenAI Codex

Add to ~/.codex/config.toml:

[mcp_servers.octopost]
url = "https://octopost.ink/mcp"
http_headers = { "Authorization" = "Bearer YOUR_API_KEY" }

Getting Your API Key

Go to Dashboard > API Keys
Copy your API key (starts with op_)
Replace YOUR_API_KEY in the setup instructions above

Or use the "Add MCP server" button on any dashboard page to copy a ready-to-use command with your key pre-filled.

Available Tools

Once connected, your AI assistant has access to these tools:

Posts

create_post - Create and optionally publish a post to multiple platforms
list_posts - List your posts with optional status filtering
get_post - Get details of a specific post
update_post - Edit a draft or scheduled post
delete_post - Delete a post
publish_post - Publish a draft immediately
retry_post - Retry failed platform deliveries

Queue

queue_post - Add a post to the publishing queue
approve_post - Approve a pending queued post
remove_from_queue - Remove a post from the queue
get_queue_settings - View queue configuration
update_queue_settings - Change queue timing and active hours

Accounts

list_accounts - See all connected social accounts

Reference

list_platforms - View supported platforms and their content limits
get_guide - Read detailed guides on topics like getting started, scheduling, the queue, and platform-specific info

Authentication

The MCP server uses your Octopost API key for authentication. The key is passed via the Authorization header as a Bearer token. Every request through the MCP server acts on behalf of your account.

Example Usage

Once set up, you can ask your AI assistant things like:

"Post 'Just shipped a new feature!' to Twitter and Bluesky"
"Add this to my queue for later: 'Check out our new docs'"
"Post about my new project and drop the URL as a reply so it doesn't get algorithmically down-ranked"
"Show me my recent posts"
"What accounts do I have connected?"
"Update my queue to post every 3 hours"

The AI assistant handles the MCP calls automatically.

Threading via MCP

create_post, schedule_post, queue_post, and update_post all accept a segments array parameter for threaded posts. Each segment becomes a reply on the main post. The canonical use case is the "link in reply" pattern — put the main message in content and the URL in a segment, so the main post isn't penalized for containing a link on Twitter/Threads.

{
  "content": "I shipped a thing.",
  "platforms": ["twitter", "threads", "bluesky", "mastodon"],
  "segments": [
    { "content": "https://example.com" }
  ]
}

See Threaded Posts for full details.