> ## Documentation Index
> Fetch the complete documentation index at: https://mcp.shipcontent.com/llms.txt
> Use this file to discover all available pages before exploring further.

---
title: Run MCP locally
description: Start the local stack, then connect an MCP client to the same OAuth-protected endpoint used on Railway.
section: start
order: 30
status: verified-locally
mode: both
reviewed: 2026-11-12
sources: [src/lib/server/skills/SandboxRunner.ts, src/lib/server/skills/local-sandbox-commands.ts, src/lib/server/skills/local-sandbox-guardian-source.ts, src/lib/server/media/technique-choice-config.ts, src/lib/server/media/video-skill-styles-config.ts, src/lib/server/owner/video-skills-access.ts, src/proxy.ts, src/lib/host-routing.ts, src/lib/server/auth/PrincipalResolver.ts, src/lib/youtube/youtube.ts, src/lib/server/youtube/YouTubeService.ts, src/lib/server/auth/EmailSender.ts, src/lib/server/auth/TokenVerifier.ts, src/lib/server/owner/owner-session.ts, README.md, src/lib/server/http.ts, .env.example, docs/local-development.md, src/lib/server/auth/BetterAuth.ts, src/lib/server/auth/GoogleProvider.ts, src/lib/server/auth/GitHubProvider.ts, src/lib/mcp/agent-tools.ts, src/lib/server/mcp/AgentMcp.ts, src/components/owner/owner-onboarding.tsx, src/lib/server/x/XPublishing.ts, src/components/owner/x-panel.tsx, db/x.sql, src/lib/server/media/MotionRenderer.ts, src/worker/FalProvider.ts, Dockerfile.worker, src/lib/server/auth/AuthEmail.ts, src/app/reset-password/page.tsx, src/components/owner/password-recovery.tsx, src/lib/server/media/MotionPlanner.ts, src/lib/server/media/MotionSceneWriter.ts, src/lib/server/media/MotionTranscriber.ts, src/lib/server/media/media-http.ts, src/lib/marketing/post-catalogue.ts, src/lib/marketing/post-scheduling.ts, src/lib/server/marketing/PostScheduling.ts, db/publishing.sql, src/components/owner/post-schedule-controls.tsx, src/lib/server/marketing/PostScheduledAdapters.ts, src/lib/server/tiktok/TikTokMedia.ts, src/lib/server/tiktok/TikTokAccounts.ts, src/lib/server/tiktok/TikTokAccountsPrivateDatabase.ts, db/tiktok.sql, src/lib/server/analytics/Analytics.ts, src/lib/server/analytics/posthog-cookie.ts, src/lib/server/owner/OwnerHandler.ts, src/lib/media/video-draft.ts, src/components/studio/use-video-draft.ts, src/components/studio/prompt-box.tsx, src/lib/server/elevenlabs/ElevenLabsVault.ts, src/lib/server/elevenlabs/ElevenLabsConnection.ts, src/lib/server/elevenlabs/ElevenLabsPrivateDatabase.ts, src/lib/server/elevenlabs/ElevenLabsVoices.ts, src/app/api/elevenlabs/route.ts, src/worker/AccountVoiceProvider.ts, src/components/owner/elevenlabs-account-section.tsx, db/migrations/20261110T1900_elevenlabs_connection.sql]
tools: [get_onboarding_status, get_workspace, list_assets]
next: [/docs/start/first-call, /docs/contracts/request-ids]
---

For hosted use, `SHIPCONTENT_OWNER_ORIGIN` selects the human dashboard at `https://app.shipcontent.com`. Agents use `https://mcp.shipcontent.com/mcp`. Both hosts share one backend. Local development uses one loopback origin for both surfaces; leave the owner override unset.

To test the optional Studio technique chooser locally, set `TECHNIQUE_CHOOSER_ENABLED=true` in `.env.local` on the app server and restart your own local process. This is a server-only flag. Only the exact string `true` enables it; absent, `false` and all other values keep it off. Leave production off. See [Find a technique](/docs/workflows/videos#video-skills) for the workflow, browser read contract and bookmark limits.

To test video skill styles locally, set `VIDEO_SKILL_STYLES_ENABLED=true` in `.env.local` on the app server and restart your own local process. This is a server-only flag with the same rule: only the exact string `true` enables it. With that flag, a new or changed style is saved only for an owner listed in `SHIPCONTENT_VIDEO_SKILLS_USERS`. Leave production off. See [video skills](/docs/workflows/videos#video-skills) for what a style changes.

The local app uses the same OAuth-protected `/mcp` endpoint and the same tool catalog as Railway. Local operation changes the origin and service configuration, not the agent contract.

Set `RESEND_API_KEY` and `SHIPCONTENT_EMAIL_FROM` on the app server to send verification and password-reset emails. The example sender is `ShipContent <no-reply@shipcontent.com>`; its domain must be verified in Resend. Verification also accepts `SHIPCONTENT_AUTH_EMAIL_FROM`. Keep the key on the server. Signup sends a one-hour, single-use setup link when Resend is configured. Signup stores no usable password and creates no session. Open the setup email, choose your password, then sign in. If the setup link expires, use **Forgot password?** to get a new link. Google and GitHub require verified email; automatic linking also requires the existing local email to be verified. At `/login`, select **Forgot password?** to open `/reset-password`. Reset links expire after one hour, work once, and end browser sessions and MCP tokens, consent and grants after a successful reset. Reconnect each agent with new consent. A send receipt does not prove inbox delivery.

## Start the stack

Install Node.js 24.5+, pnpm, Docker, `ffmpeg`, and `ffprobe`. Use `.env.local` for local settings and provider keys that you intend to use. Run:

```sh
pnpm dev
```

When the stack is ready, open `http://localhost:3000/login` and sign in. Connect your MCP client to `http://localhost:3000/mcp`, using its OAuth flow. The owner grants the client workspace access at `/agent-access`. Use `localhost` consistently so the browser session cookie matches the configured issuer.

If port 3000 is busy, use `PORT=3100 pnpm dev` and connect to `http://localhost:3100/mcp`.

Updated October 27, 2026. Before starting a second preview, follow **Isolated
previews** in the repository's **Local development** guide for the complete
service, port, and bucket settings and their precedence.

For Google sign-in, put the development project's `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` in the ignored `.env.local` file. Register `http://localhost:3000/api/auth/callback/google` in that project's Web application client. If the app runs on port 3100, register the exact port 3100 callback too. The password option stays available. Owners with a password account can continue using it. A matching Google or GitHub email can link only when the existing ShipContent email and the provider email are both verified.

To enable GitHub sign-in, register a development GitHub OAuth App with the exact callback `http://localhost:3000/api/auth/callback/github`. Put its `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET` in the ignored `.env.local` file. If the app runs on port 3100, `pnpm dev` moves the auth issuer; also register `http://localhost:3100/api/auth/callback/github`. Keep the production GitHub OAuth App credentials separate. GitHub sign-in only starts an owner session; the owner must still approve each MCP client's account grant.

The local password flow also requires email verification. Set `RESEND_API_KEY` and `SHIPCONTENT_AUTH_EMAIL_FROM` only when you intend to send real email from this local app. Automated tests use the Effect `EmailSender` test layer; the running app has no automatic test or console sender. Missing sender configuration blocks delivery and leaves signup pending.

## First tool call

Call `list_workspaces`. Select a returned `workspaceId` for every other tool. If the list is empty, ask the owner to review the grant at `/agent-access`; a valid OAuth token alone does not grant a workspace.

## If the stack stops

Check the terminal output and the repository's local development procedure for Docker and database repair, including migrations and the limits on database resets.

YouTube operators configure `YOUTUBE_CLIENT_ID`, `YOUTUBE_CLIENT_SECRET`, `SHIPCONTENT_YOUTUBE_VAULT_ACTIVE_KEY_ID` and `SHIPCONTENT_YOUTUBE_VAULT_KEYS`. See [YouTube setup](/docs/channels/youtube#operator-setup).

## X publishing configuration

X is optional. Configure `SHIPCONTENT_X_CLIENT_ID` and `SHIPCONTENT_X_CLIENT_SECRET` for the confidential web app. Use `SHIPCONTENT_X_CONNECTION_DATABASE_URL` for the connection role and `SHIPCONTENT_X_WORKER_DATABASE_URL` for the worker role. Set `SHIPCONTENT_X_VAULT_ACTIVE_KEY_ID` and `SHIPCONTENT_X_VAULT_KEYS` to an active key ID and a JSON map of key IDs to base64 32-byte keys. Keep old keys while saved credentials use them.

X publishing is on when `SHIPCONTENT_X_CLIENT_ID` and `SHIPCONTENT_X_CLIENT_SECRET` are set. X bills API use to the developer account; ShipContent sets no API budget.

The isolated bootstrap creates X connection and worker logins. Existing hosted data needs a reviewed, data-preserving schema update; do not reset a saved production database. See [X publishing](/docs/channels/x).

## Video configuration

For the optional first-video controls, use the [server-only presentation selector](/docs/start/connect-hosted#video-configuration). It applies to this local stack too.

Updated 2026-10-28: the local skill runner needs no hosted sandbox credentials. The local skill runner starts host processes with the worker's environment and uses host tools. Run only trusted development commands.

For manual text-video fallback, Studio device drafts, OpenAI and ElevenLabs keys, motion browser path, and sandbox probe behavior, use the same variables as hosted. See [Video configuration](/docs/start/connect-hosted#video-configuration) and [Make a video](/docs/workflows/videos).

## Scheduled publishing configuration

Updated 2026-10-28. No operator flag controls scheduled publishing. A scheduled Instagram, YouTube, X, Facebook or Threads post needs the configuration of its channel. A scheduled YouTube upload keeps the visibility the owner saved. See [channel limits](/docs/channels/overview) and [scheduling errors](/docs/contracts/errors#scheduling-errors).

TikTok Accounts uses `TIKTOK_BUSINESS_APP_ID`, `TIKTOK_BUSINESS_APP_SECRET`, `TIKTOK_ACCOUNTS_AUTHORIZATION_URL` and `TIKTOK_ACCOUNTS_REDIRECT_URI`. Configure its separate `SHIPCONTENT_TIKTOK_ACCOUNTS_CONNECTION_DATABASE_URL`, `SHIPCONTENT_TIKTOK_ACCOUNTS_VAULT_ACTIVE_KEY_ID` and `SHIPCONTENT_TIKTOK_ACCOUNTS_VAULT_KEYS`. The schema bootstrap needs `SHIPCONTENT_BOOTSTRAP_TIKTOK_ACCOUNTS_CONNECTION_PASSWORD`. Register the exact HTTPS callback with its final slash. See [TikTok operator setup](/docs/channels/tiktok#operator-setup). Local tests use fake provider responses; a live TikTok return requires the registered HTTPS owner host.

Updated 2026-11-10: an owner on the video-skills list can connect their own ElevenLabs account in Settings. The app and the worker need `SHIPCONTENT_ELEVENLABS_VAULT_ACTIVE_KEY_ID` and `SHIPCONTENT_ELEVENLABS_VAULT_KEYS`: the key ID and a JSON map of base64 32-byte AES keys. Keep old keys while saved owner keys use them. The app saves the sealed owner key through the restricted connection database login. Without the vault settings the Settings card cannot connect, and voiceover keeps the built-in voices on `ELEVENLABS_API_KEY`.

For TikTok video retrieval, set `TIKTOK_ACCOUNTS_MEDIA_ORIGIN` to an owned HTTPS origin. Verify its URL ownership in TikTok before a publication send. A localhost origin cannot serve a live TikTok download.

## Signup analytics configuration

Signup funnel analytics are optional. Set `SHIPCONTENT_POSTHOG_KEY` on the app server to send `signup_started` and `signup_completed` events to PostHog. `SHIPCONTENT_POSTHOG_HOST` is optional; it defaults to the EU region. Each event carries only its name, the owner's user ID or the landing's anonymous ID, and the sign-in method. No event carries an email, a name, a token, or an IP address. The server links a landing visitor's anonymous ID to the signed-in owner when the browser sends the matching `ph_<key>_posthog` cookie. `signup_started` fires only for the password sign-up flow.

## Meta channel configuration

Facebook Login for Business and Threads use separate product credentials, vaults and restricted connection/worker database logins. Configure their registered callbacks and apply forward migrations before opening Connect. For saved databases, use the transactional Meta role provisioner after migrations; do not reset saved data. See [Facebook operator setup](/docs/channels/facebook#operator-setup) and [Threads operator setup](/docs/channels/threads#operator-setup). Keys and tokens stay on the server. A successful local setup does not prove live channel acceptance.

Password signup uses a mailbox setup link. Choose your password from that link before signing in. Password recovery ends existing browser sessions and agent credentials; sign in and reconnect each agent with new consent.
