Octospark MCP

Stdio MCP server for Octospark. The server exposes agent-safe tools for social accounts, drafts, scheduling, media upload, credit checks, and publish confirmation through the Octospark API gateway.

The MCP server is intentionally a thin client. It does not call X, R2, Stripe, OpenRouter, or the database directly.

Quick Start

Use the package directly with npx:

OCTOSPARK_API_URL=https://api.octospark.ai npx -y @octospark/mcp

For staging:

OCTOSPARK_API_URL=https://api-staging.octospark.ai npx -y @octospark/mcp

The package exposes one stdio binary: octospark-mcp.

Claude Code

claude mcp add octospark -e OCTOSPARK_API_URL=https://api.octospark.ai -- npx -y @octospark/mcp

For staging:

claude mcp add octospark -e OCTOSPARK_API_URL=https://api-staging.octospark.ai -- npx -y @octospark/mcp

Cursor

Add this to Cursor MCP settings:

{
  "mcpServers": {
    "octospark": {
      "command": "npx",
      "args": ["-y", "@octospark/mcp"],
      "env": {
        "OCTOSPARK_API_URL": "https://api.octospark.ai"
      }
    }
  }
}

Codex

Add this to ~/.codex/config.toml:

[mcp_servers.octospark]
command = "npx"
args = ["-y", "@octospark/mcp"]

[mcp_servers.octospark.env]
OCTOSPARK_API_URL = "https://api.octospark.ai"

Generic MCP Clients

Use a stdio server with:

{
  "command": "npx",
  "args": ["-y", "@octospark/mcp"],
  "env": {
    "OCTOSPARK_API_URL": "https://api.octospark.ai"
  }
}

Authentication

Authentication is handled through the Octospark API gateway. When a tool needs auth, use the Octospark device login flow from the CLI:

npm install -g @octospark/cli
OCTOSPARK_API_URL=https://api.octospark.ai octospark login
octospark whoami

For staging:

npm install -g @octospark/cli
OCTOSPARK_API_URL=https://api-staging.octospark.ai octospark login
octospark whoami

Agent Prompt

Paste this into an agent session:

Use Octospark only through the Octospark API gateway, CLI, or MCP server.
Install the CLI with `npm install -g @octospark/cli`.
Authenticate with `OCTOSPARK_API_URL=https://api.octospark.ai octospark login`.
Use Octospark tools for account checks, draft creation, scheduling, media upload, credit checks, and publish confirmations.
Do not call X, R2, Stripe, OpenRouter, or the database directly.
Ask before any mutating publish action.

Runtime Guarantees

Mutating tools use the API cost-estimate surface before execution and require explicit confirmation. Reads of stored post analytics are free at launch because Octospark has already collected the data.

Supported Platforms

The published package includes Bun-compiled native executables for:

• darwin-arm64
• darwin-x64
• linux-arm64
• linux-x64

Unsupported platforms fail early with a clear launcher error.

Maintainer Publishing

The package is published as @octospark/mcp. The public npm package is intentionally a thin launcher around the Bun native binaries produced by scripts/build.mjs.

Preflight

Run these checks from this package directory:

pnpm build
npm pack --dry-run

The pack dry run should show a tarball containing:

• bin/octospark-mcp.js
• dist/native/octospark-mcp-darwin-arm64
• dist/native/octospark-mcp-darwin-x64
• dist/native/octospark-mcp-linux-arm64
• dist/native/octospark-mcp-linux-x64