@socheli/mcp

A Model Context Protocol server that gives Claude — and any MCP-enabled agent — your Socheli content engine as tools.

List and inspect content, dispatch renders to your device fleet, check device status, publish across platforms, and read/curate the dated content plan — all from a chat with your agent.

API · SDK · CLI · MCP · Docs

What it is

@socheli/mcp is a Model Context Protocol server that exposes Socheli as agent tools, so Claude (or any MCP client) can inspect content, dispatch renders to the fleet, publish finished posts, and read & curate the dated content plan — by talking to it in natural language.

It is a dependency-free stdio JSON-RPC server built on top of @socheli/sdk, which it uses to talk to the Socheli HTTP API. Every tool call is a typed SDK call under the hood. Authentication is one Socheli API key.

Under the hood it speaks the 2024-11-05 MCP protocol over stdin/stdout using Content-Length-framed JSON-RPC, and advertises a tools capability with serverInfo { name: "socheli", version: "0.1.0" }.

Related MCP server: EchoFM Studio

Install

npm i -g @socheli/mcp
# or run on demand, no install:
npx @socheli/mcp

The package ships a socheli-mcp binary. Most users don't run it directly — they point an MCP client at it (see Quickstart).

Authentication

The server is configured with two environment variables — one for the API base URL, one for your API key:

These are passed to createSocheli({ baseUrl: process.env.SOCHELI_API_URL, apiKey: process.env.SOCHELI_API_KEY }). The SDK then authenticates to the API with Authorization: Bearer <SOCHELI_API_KEY> on every request. A wrong key yields 401; a server with no key configured yields 503.

Set these in your MCP client's env block (below), not in a shell, so the agent process inherits them.

Quickstart

Add Socheli to your MCP client. For Claude Desktop / Claude Code, drop this into your .mcp.json (or claude_desktop_config.json):

{
  "mcpServers": {
    "socheli": {
      "command": "npx",
      "args": ["@socheli/mcp"],
      "env": {
        "SOCHELI_API_URL": "https://api.socheli.com",
        "SOCHELI_API_KEY": "sk_live_xxx"
      }
    }
  }
}

Running from a checkout of the monorepo instead of npm? Use the source entry directly:

{
  "mcpServers": {
    "socheli": {
      "command": "node",
      "args": ["--import", "tsx", "packages/mcp/src/index.ts"],
      "env": {
        "SOCHELI_API_URL": "https://api.socheli.com",
        "SOCHELI_API_KEY": "sk_live_xxx"
      }
    }
  }
}

Then just talk to your agent:

• "Use socheli to list the last 5 items and their QA scores."

• "Generate a video about the science of habit on concept_lab and auto-publish it."

• "What devices are online right now?"

• "Show me everything planned for next Tuesday and archive anything scoring under 7."

• "Move the Instagram post on the 20th to the 25th at 2:30pm."

Tool reference

Core

Calendar & plan (plan_*)

The full plan_* CRUD is exposed too, so an agent can read and curate the dated content plan exactly the way the dashboard's day dialog does — open a day, open an event, edit / move / archive / delete. Posts live as PlannedPost records.

All mutations return the affected post. plan_archive is reversible (plan_update the status back to idea); plan_delete is not.

The PlannedPost

type PlannedPost = {
  id: string;
  date: string;        // YYYY-MM-DD
  time: string;        // HH:MM
  channel: string;     // brand / channel id
  platform: "youtube" | "instagram" | "tiktok" | "x" | "linkedin" | "telegram";
  topic: string;
  angle: string;
  format: string;      // short | explainer | …
  mood?: string;
  hook?: string;
  rationale: string;
  algoLever?: string;  // which algorithm lever this idea exploits
  scores?: Record<string, number>;
  overall?: number;
  status: "idea" | "approved" | "scheduled" | "generated" | "dropped" | "archived";
  planRunId: string;
  createdAt: string;
  updatedAt?: string;
};

How it works

The server implements the MCP JSON-RPC methods below over a Content-Length-framed stdio transport:

Each tool's run maps directly to an @socheli/sdk call — e.g. socheli_list_items → socheli.items.list(...), socheli_generate → socheli.generate(...), socheli_publish → socheli.items.publish(...). Tool errors are returned to the agent as text content with isError: true rather than as transport errors, so the model can read and react to them.

The Socheli surfaces

Socheli is built API-first. This MCP server is one of four public client surfaces, all speaking to the same control plane:

Full documentation lives at docs.socheli.com.

Developed in the Socheli monorepo

@socheli/mcp is developed inside the Socheli monorepo (as packages/mcp) alongside the API, SDK, CLI, and engine, and mirrored to this repo for publishing. Issues and PRs are welcome here.

License

MIT — see LICENSE.