Docs
Docs/AI Agents/MCP Server

MCP Server

View raw .md

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"

Claude Code plugin (skill + server)

The plugin bundles the server config and the Octopost agent skill, which tells Claude Code how to post, thread, schedule and queue for approval. Run these inside Claude Code and paste your API key when asked:

/plugin marketplace add octopost-ink/octopost-plugin
/plugin install octopost@octopost

Source: github.com/octopost-ink/octopost-plugin (skill and config only, MIT).

Agent skill only

Any agent that reads Agent Skills can add the skill. Connect the server separately with one of the options on this page:

npx skills add octopost-ink/octopost-plugin

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" }

One page per client, with the exact config: Claude Code, Cursor, VS Code, Windsurf, Codex, Gemini CLI.

VS Code

Add to .vscode/mcp.json in your workspace:

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

Errors you might see

Every error says what happened and what to do next. The common ones on a first call:

  • 401 "no Authorization header was sent" or "not an Octopost API key": send Authorization: Bearer op_... with the key from the API keys page.
  • 401 "does not match any Octopost account": the key was regenerated or mistyped. Copy it again.
  • "no active plan": finish the $1 trial checkout on the billing page.
  • "No X (twitter) account is connected": connect X on the accounts page, then retry.

Getting Your API Key

  1. Go to Dashboard > API Keys
  2. Copy your API key (starts with op_)
  3. 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 these 16 tools:

Posts

  • create_post - Publish a post now, with optional thread segments
  • schedule_post - Publish at an exact time
  • list_posts - List your posts, filtered by status
  • get_post - Details of one post, including its live URLs
  • update_post - Edit a draft or scheduled post
  • delete_post - Delete a post (and the published copies where the network allows it)
  • retry_failed - Retry the networks that failed on a post
  • cancel_scheduled - Turn a scheduled post back into a draft
  • reschedule_post - Move a scheduled post to a new time

Queue

  • queue_post - Add a post to the publishing queue, optionally held for approval
  • approve_queued_post - Approve a post waiting for approval
  • get_queue_status - See what is queued and when the next post goes out
  • update_queue_settings - Change queue interval, active hours, timezone, or pause it

Accounts and reference

  • list_accounts - See the connected social accounts (call this first)
  • list_presets - Your saved publishing presets
  • get_guide - Guides on getting started, scheduling, the queue, and each network

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 X"
  • "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"],
  "segments": [
    { "content": "https://example.com" }
  ]
}

See Threaded Posts for full details.