MCP Server

Overview

The ShortsGen MCP (Model Context Protocol) server exposes every user-facing REST API as MCP tools. Third-party applications — Cursor, Claude Desktop, custom agents, or your own backend — can generate shorts, check job status, manage credits, and publish to Facebook on behalf of a ShortsGen user account.

The MCP server lives in the mcp-server/ directory at the repo root. It proxies HTTP requests to your running ShortsGen app — it does not embed pipeline logic directly.

Prerequisites

1. Node.js 20+ installed on the machine running the MCP server.
2. A running ShortsGen app — locally with npm run dev or deployed to production.
3. A ShortsGen account with credits (for generation tools).
4. An API key created in the web app (see below). Keys are prefixed with sg_.
5. Dependencies installed in both the repo root and mcp-server/ (npm install in each).

Quick start

1. Start ShortsGen: npm run dev
2. Sign in at /sign-in, open Settings → API keys, and create a key. Copy it immediately — it is shown only once.
3. Set environment variables (see below).
4. Run npm run mcp from the repo root.
5. Add the server to Cursor or Claude Desktop (see configuration sections below).
6. Test with the auth_health or get_credits tool in your MCP client.

Create an API key

API keys authenticate the MCP server (and any programmatic client) as your ShortsGen user. Each key is scoped to your account and can be revoked at any time.

1. Sign in and navigate to Settings.
2. Scroll to the API keys section.
3. Enter a descriptive name (e.g. "Cursor MCP") and click Create key.
4. Copy the full key (starts with sg_) and store it securely.
5. Set it as SHORTSGEN_API_KEY in your MCP client configuration.

The MCP server sends Authorization: Bearer sg_… on every request. The app also accepts x-api-key.

Environment variables

Set your app URL once in NEXT_PUBLIC_APP_URL. In MCP client config (Cursor, Claude), pass the same URL as SHORTSGEN_BASE_URL.

# App .env — your public app URL
NEXT_PUBLIC_APP_URL=https://clips.adomicarts.com

# MCP client config — use the same URL as SHORTSGEN_BASE_URL
SHORTSGEN_BASE_URL=https://clips.adomicarts.com

# Required for most MCP tools — create in Settings → API keys
SHORTSGEN_API_KEY=sg_your_key_here

# Optional — HTTP transport (default 3100)
MCP_HTTP_PORT=3100
MCP_HTTP_HOST=127.0.0.1

# Recommended — protects the MCP HTTP endpoint itself
MCP_HTTP_AUTH_TOKEN=your-mcp-secret

Run the MCP server

stdio transport (default)

Used by Cursor, Claude Desktop, and most local MCP clients. The server communicates over stdin/stdout — no port binding required.

# From the repo root (stdio — Cursor / Claude Desktop)
npm run mcp

HTTP transport

For remote third-party apps that connect over the network. Listens on port 3100 by default.

# From the repo root (HTTP — remote clients)
MCP_HTTP_AUTH_TOKEN=your-mcp-secret npm run mcp:http

From mcp-server/ directly

# Or from the mcp-server/ directory (loads NEXT_PUBLIC_APP_URL from parent .env)
cd mcp-server
npm install
SHORTSGEN_BASE_URL=https://clips.adomicarts.com SHORTSGEN_API_KEY=sg_your_key npm start
SHORTSGEN_BASE_URL=https://clips.adomicarts.com SHORTSGEN_API_KEY=sg_your_key npm run start:http

Cursor setup

Add the MCP server to Cursor via project or global MCP settings. Use the absolute path to your ShortsGen app directory for cwd.

{
  "mcpServers": {
    "shotsgen": {
      "command": "npm",
      "args": ["run", "mcp"],
      "cwd": "C:/path/to/your/shotsgen/app",
      "env": {
        "SHORTSGEN_BASE_URL": "https://clips.adomicarts.com",
        "SHORTSGEN_API_KEY": "sg_your_key_here"
      }
    }
  }
}

1. Create or edit .cursor/mcp.json in your project (or use Cursor Settings → MCP).
2. Paste the configuration above — set SHORTSGEN_BASE_URL to your NEXT_PUBLIC_APP_URL (https://clips.adomicarts.com).
3. Ensure ShortsGen is running before using MCP tools.
4. Restart Cursor or reload MCP servers from settings.
5. Open the MCP panel and verify shotsgen shows as connected.

Claude Desktop setup

Claude Desktop uses the same stdio configuration. Edit your Claude Desktop MCP config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "shotsgen": {
      "command": "npm",
      "args": ["run", "mcp"],
      "cwd": "/absolute/path/to/app",
      "env": {
        "SHORTSGEN_BASE_URL": "https://clips.adomicarts.com",
        "SHORTSGEN_API_KEY": "sg_your_key_here"
      }
    }
  }
}

Restart Claude Desktop after saving. Set SHORTSGEN_BASE_URL to your NEXT_PUBLIC_APP_URL (https://clips.adomicarts.com).

HTTP transport

Start the HTTP server with npm run mcp:http. Clients send MCP Streamable HTTP requests to:

POST http://127.0.0.1:3100/mcp
Authorization: Bearer your-mcp-secret
Content-Type: application/json

Health check (no auth required unless MCP_HTTP_AUTH_TOKEN is set on all routes — health is always open):

GET http://127.0.0.1:3100/health

When MCP_HTTP_AUTH_TOKEN is set, include Authorization: Bearer <token> on MCP requests. This token is separate from your ShortsGen API key — it only protects the MCP server endpoint.

Authentication

ShortsGen uses Better Auth with an API key plugin. When the MCP server sends a valid API key, the app treats the request as an authenticated session for your user — no browser cookies required.

• Production use: always use an API key via SHORTSGEN_API_KEY.
• Onboarding tools (auth_sign_up, auth_sign_in, api_key_create) can run without a key to create an account and first key.
• Revoke compromised keys immediately in Settings → API keys.

Available tools

Each MCP tool maps to one ShortsGen REST endpoint. Tool responses are JSON returned as text content.

Auth & API keys

Generation & jobs

generate_shorts accepts youtubeUrl, numVariations (1–8), and optional videoSettings (clipLength, exportQuality, captionStyle).

Credits & billing

Facebook publishing

Facebook publishing via MCP

Facebook OAuth requires a browser. The MCP flow uses a redirect URL returned by the API:

1. Call get_facebook_connect_url — the response includes redirectUrl.
2. Open that URL in a browser while signed in to ShortsGen and complete Meta OAuth.
3. Call get_facebook_status to confirm connection and list Pages.
4. Call select_facebook_page with the desired pageId.
5. Generate shorts, then call publish_to_facebook with jobId and clipId. Uploads may take several minutes.

See also the Connections page for in-app Facebook setup.

Excluded endpoints

These endpoints are intentionally not exposed as MCP tools:

Troubleshooting