Developer documentation

MCP for VibeCody

Connect an AI agent to your content workspace. It can read and edit calendars and drafts, start generation from your ideas, or submit finished posts and articles without using VibeCody's writer.

MCP agent guideREST API guide

Hosted MCP endpoint

https://app.vibecody.app/api/mcp

Streamable HTTP · JSON-RPC over POST · MCP protocol 2025-11-25 · Bearer token required

Connect an MCP client

Sign in, open a project, and go to Settings.
Create an Account MCP connection for all projects you can access, or a project-bound MCP token for just one project.
Copy the token when it is shown. It cannot be displayed again.
Add the endpoint and bearer token to your MCP client. For clients that accept a JSON server configuration:

{
  "mcpServers": {
    "vibecody": {
      "url": "https://app.vibecody.app/api/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_MCP_TOKEN>"
      }
    }
  }
}

Configuration format varies by client. Keep your token private and revoke it in Settings when it is no longer needed.

Use this page as the documentation URL when registering a connector; use https://app.vibecody.app/api/mcp as its hosted endpoint.

Access and permissions

An account and a token created in VibeCody are required. Tokens can be limited to View, Edit, or Manage. An account token sees only projects the user can currently access; a project token is bound to one project.

Content approval is a separate optional delegation. Full autonomy is an explicit owner grant with additional limits. Neither permission bypasses quality, connection, or provider policy checks. Generation consumes the account's available credits; connection setup, token creation, and adding credits happen in the dashboard.

This endpoint uses bearer API tokens, not OAuth with PKCE. OAuth for connected publishing accounts is a separate, user-authorized setup step.

Grant	What it permits
View	Read accessible projects, content, status, and delivery packages.
Edit	Create and revise ideas, calendars, content, and eligible operations.
Manage	Manage project-level settings, sharing, and connections where the user's role allows it.
Content approval	Separate delegation to approve an exact reviewed campaign-output revision.
Full autonomy	Explicit owner grant for eligible exact-revision distribution approval, with a UTC daily target limit. TikTok Direct Post still needs per-post consent.

Content workflows

Generate from an idea

Create a campaign with your idea in primaryNarrative, call generate_campaign_outputs, then read the output and revision with get_campaign. Inspect the returned operation instead of starting duplicate work.

Submit finished content

Create a campaign without calling generation. Use submit_campaign_text for a finished post or article, or submit_campaign_output for a complete destination-native object. This stores an ordinary editable campaign output without invoking the writer.

Read content back with get_campaign. To change it, call update_campaign_output with the current expectedRevision and full replacement content. Use a client-generated idempotency key for submission and other mutating operations.

For example, after creating a campaign whose destinations include linkedin_post, send this JSON-RPC request to submit finished copy:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "submit_campaign_text",
    "arguments": {
      "campaignId": "<CAMPAIGN_ID>",
      "destination": "linkedin_post",
      "text": "The finished LinkedIn post, written outside VibeCody.",
      "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000"
    }
  }
}

The same destination can have only one output in a campaign. To change an existing output, read its revision and use update_campaign_output; do not submit a second output. Reuse the same UUID only when retrying the exact same submission.

For editorial planning, use create_manual_calendar, create_calendar_item, and update_calendar_item. A calendar item is a plan, not the post body; submitted content can be linked to an eligible item with calendarItemId.

Short videos and carousels

Discover format capabilities and allowed catalog media, then use queue_reel or queue_carousel. Monitor get_job; review and edit a paused script with the script tools before resuming the same job.

External publishing

Create an external distribution batch, request approval of its exact revision, fetch the approved publishing package, publish with your own integration, and report the result back. Expiring media URLs are not durable identifiers.

Protocol and live schemas

The endpoint accepts one JSON-RPC 2.0 request per POST and returns a JSON response. It supports MCP initialize, ping, tools/list, and tools/call. JSON-RPC batches are not supported. The server currently advertises protocol version 2025-11-25 and accepts several earlier MCP versions.

A quick way to inspect the live tool catalog with an existing token:

curl -X POST https://app.vibecody.app/api/mcp \
  -H 'Authorization: Bearer <YOUR_MCP_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Each tools/list entry includes its description and JSON input schema. For tools/call, put the tool name in params.name and its arguments in params.arguments. Use those live schemas for required fields, allowed values, and output contracts; do not infer parameters from the examples on this page.

Complete MCP tool catalog

Your MCP client can discover the current tool names, descriptions, and input schemas through tools/list. Start with whoami, list_projects, and get_project; do not guess project or resource IDs.

The groups below cover all currently registered tools, with descriptions from the MCP registry. Open a group to see what each tool does. Call list_content_destinations before choosing a content format. A listed format does not guarantee that a managed publishing connection is configured.

Workspace and settings (11)

Discover accessible projects, manage the workspace, and inspect destination formats and settings.

whoami: Show the authenticated MCP token, scope, bound project, current paid/starter credit balance, and the dashboard action required when credits are exhausted. Registration, credit purchase, and token creation remain user-only dashboard actions.
list_projects: List projects of every type. Includes lanes, destinations, and campaign/calendar/reel counts. Zero reels does not mean empty: LinkedIn and blog projects live in campaigns and calendars. Project tokens return the bound project, account tokens return projects accessible to their user, and admin tokens can search every project.
get_project: Get one project, including lanes, destinations, workstreams, role, and counts for reels, campaigns, calendars, and publishing connections.
create_project: Create a project. Account tokens create it for their user. Admin tokens must pass ownerEmail. Project tokens cannot create another project.
update_project: Rename a project.
delete_project: Delete a project. confirmationName must match the project name.
get_home: Get the project Home worklist: attention, production, and recent outputs.
get_settings: Get project settings: name, default avatar, members, and generationDefaults (brand, CTA, LinkedIn author, trend query).
update_settings: Update project name, default avatar, and/or generationDefaults. Use this for UGC brand/CTA rules.
update_destinations: Replace enabled destinations and optional primary destination.
list_content_destinations: List every destination-native content contract supported by the generator and external delivery package. Includes content kind, export formats, canonical managed-delivery path, scheduling declaration, and configuration state. Registry presence is not production certification.

Project members (4)

Inspect and manage project sharing, subject to the token and member permissions.

list_members: List project members and owner.
share_project: Share the project with an existing user by email.
update_member: Change a collaborator's role.
remove_member: Remove a collaborator.

Ideas and content planning (9)

Save ideas, build and edit content plans, and assess evidence before starting a reel.

get_idea_draft: Read the saved idea draft for one creator/output lane.
upsert_idea_draft: Create or replace the saved idea draft for one creator/output lane. Use source=generated for externally researched trend ideas and preserve the evidence/brief in the draft text.
list_plan_items: List UGC content-plan items (avatar calendar), with optional date range and avatar filter.
create_plan_item: Create one UGC content-plan item.
update_plan_item: Update one UGC content-plan item.
delete_plan_item: Delete one UGC content-plan item.
generate_plan: Generate a rolling UGC content plan for an avatar (story_arc / experiment mix).
queue_plan_item: Queue generation for one PLANNED UGC plan item (same as pregenerate in the app).
assess_reel_evidence: Assess a reel topic against the project's saved context before spending a credit. Returns risk, evidence requirement, whether research is likely needed, the effective gap action, and suggested agent choices. Use productVisibility, personaFraming, requiredBeats, and requiredCopy when those constraints are authoritative rather than asking the system to infer them from prose. This performs no external research and queues nothing.

Video, media, and generation jobs (19)

Inspect creators and media, queue reels or carousels, edit scripts, and monitor or resume durable jobs.

list_video_catalog: List published, licensed video catalog assets with immutable version IDs and preview URLs.
get_video_format_capabilities: Describe supported short-video formats, blueprint media requirements, fallbacks, caption styles, and whether catalog content is required.
list_avatars: List avatars for a UGC/short-video project.
list_reels: List reels in the project.
list_carousels: List carousels in the project.
list_assets: List media assets in the project.
archive_asset: Archive one project asset.
list_jobs: List recent generation jobs.
get_job: Get one generation job, including status and related reel/carousel. Completed reel jobs include video (generation-video.v1): resolved language and avatar/blueprint IDs, exact spoken text, word timings, timed subtitle cues and SRT, effective subtitle style/position, render URLs and dimensions, plus retention and post-render QA.
resume_job: Resume a paused generation from its durable checkpoint. An agent may add verified evidence or change evidenceMode/evidenceGapAction before resuming; the same job is reused and no second generation credit is charged.
pause_job: Cooperatively pause a queued or running reel generation. In-flight provider work may finish, but the worker stops at the next durable stage boundary and the job remains resumable.
retry_job: Retry a failed reel generation from its durable checkpoint. An agent may add verified evidence or change evidenceMode/evidenceGapAction before retrying; the same job is reused and no second generation credit is charged. The FAILED-to-QUEUED state transition prevents duplicate concurrent retries.
queue_reel: Queue a short video through one explicit blueprint. Call get_video_format_capabilities first, then pass blueprintId or rely on the project's saved blueprint. Use scriptSource mode=prompt for the normal direct path, or provided to preserve approved copy exactly. Native Selfie is a videoModel available only with prompt_to_video; it produces one raw silent creator clip and is not a blueprint. The agent controls evidence policy: auto classifies risk and degrades safely, required insists on grounded claims, and creative is for experiential or already approved copy. Pass activeAvatarId when the selected blueprint requires a creator. Pass language to override that avatar's default; when omitted, the selected avatar's default language wins over the project language. Use idempotencyKey for safe retries.
get_reel_script: Get the structured script and approval state for the latest generation of a reel.
update_reel_script: Replace the structured script of a paused reel before TTS. The complete generated-script object is required.
approve_reel_script: Approve a paused reel script and resume the same generation job without repeating ingestion or script generation.
queue_carousel: Queue a carousel using project defaults plus optional title and brief.
queue_project_image: Generate one original image in project Media from a prompt, optional owned image reference and aspect ratio. Costs one credit; check get_job for progress and result.assetId, then reuse that asset in videos, carousels or posts. Requires a configured image provider and project edit access. Use idempotencyKey for safe retries.
get_content_delivery_package: Get a read-only content delivery package for an external publisher. Supports completed UGC reels, rendered generic carousels, and approved destination-native campaign outputs such as CMS articles, social posts, video plans, carousel plans, YouTube metadata, and local posts. It returns exact content, delivery readiness, export formats, original media when available, and a stable fingerprint. This never submits to a provider and does not require a publishing connection.

Campaigns and editable content (15)

Generate from a brief or submit finished native content, read exact output revisions, review, and approve.

list_campaigns: List content campaigns. Default is a compact summary (id, status, destinations, output statuses). Pass detail=true for full briefs.
get_campaign: Get one campaign and every existing output, including complete generated or externally supplied content, quality state, and revision. Read this before editing; it does not generate anything.
create_campaign: Create a content campaign around your idea (use primaryNarrative for the specific topic and direction). This only saves the campaign; call generate_campaign_outputs for our writer, or submit_campaign_text / submit_campaign_output for ready copy.
update_campaign: Update campaign metadata or status.
generate_campaign_outputs: Generate campaign outputs for LinkedIn, WordPress, Instagram, Google Business, and other campaign destinations. Spends owner credits.
regenerate_campaign_output: Regenerate one campaign output (full or scoped section).
submit_campaign_text: Submit ready text directly as an ordinary campaign output without our writer. For social posts pass the exact body; for CMS articles pass plain text plus an optional title; for Google Business pass the exact summary. Text is preserved in body/markdown/summary, while required native metadata is filled mechanically. Saves an unapproved draft; review and approval are separate. Video, carousel, and other structured packages require submit_campaign_output.
submit_campaign_output: Submit a complete destination-native post or article supplied by the external agent, without running the Content Factory writer. The destination must belong to the campaign and cannot already have an output. Saves an unapproved draft; use regenerate_campaign_output with scope=review for quality/evidence review, then approve and schedule separately. Retry with the same UUID to replay safely.
update_campaign_output: Edit campaign output content. Requires expectedRevision.
list_campaign_output_revisions: List revisions for one campaign output.
approve_campaign_output: Approve one exact quality-checked campaign-output revision when the token owner explicitly delegated content approval. Requires a client idempotency key. This never grants provider/legal attestations, schedules content, spends money, or submits to a provider.
request_campaign_output_approval: Request human review for a campaign output. Use this when the token has no content-approval delegation or a person should decide. Returns its current revision and dashboard URL; it never approves, schedules, or publishes the output.
queue_canonical_content: Create and generate canonical multi-destination content (LinkedIn/blog/social) from a short brief.
queue_google_business_post: Create and generate a Google Business local post campaign.
queue_campaign_evidence: Add, exclude, or retry evidence sources for a LinkedIn/blog/GBP campaign, then queue generation.

Editorial calendars (7)

Create a manual or researched calendar, add dated ideas, and edit cadence, items, and status.

list_calendars: List editorial calendars.
get_calendar: Get one editorial calendar and its items.
create_manual_calendar: Create an empty draft editorial calendar without research or generation. Add manual ideas with create_calendar_item, then activate with update_calendar. Auto-extension is disabled and manual review is required; publishing remains subject to connection and approval gates.
create_calendar: Create an editorial calendar (LinkedIn, WordPress, Google Business, etc.) and queue its first research/generation run.
update_calendar: Update editorial calendar cadence, status, timezone, or publishing connection.
create_calendar_item: Add an authored planning item to an editorial calendar. It starts as an IDEA and does not launch generation; change status to planned with update_calendar_item when ready for the calendar workflow.
update_calendar_item: Update one editorial calendar item.

Publishing accounts and profiles (13)

Inspect and configure publishing connections; finish interactive provider authorization with the user.

list_publishing_connections: List publishing connections. Credentials are never returned.
get_publishing_connection: Get one publishing connection. Credentials are never returned.
create_publishing_connection: Create a campaign publishing connection (LinkedIn member post, WordPress, Ghost, Google Business, etc.).
update_publishing_connection: Update a campaign publishing connection label or config.
revoke_publishing_connection: Revoke a publishing connection.
start_publishing_oauth: Start OAuth for a publishing connection. Returns authorizationUrl for the user to open in a browser.
certify_publishing_connection: Record a certification step or enable production on a publishing connection.
validate_publishing_connection: Validate a campaign publishing connection (WordPress, Ghost, LinkedIn, GBP, etc.). Credentials are never returned.
create_official_connection: Create an official social connection (TikTok, Instagram, YouTube, Facebook, Threads, LinkedIn, X, Pinterest, Telegram, Bluesky, Reddit, Snapchat).
list_google_business_locations: List Google Business locations discovered for a connected GBP account.
select_google_business_location: Bind a Google Business connection to one verified location.
get_linkedin_author_profile: Get the LinkedIn author profile stored on the project.
update_linkedin_author_profile: Update the LinkedIn author profile used for member posts.

Scheduling and managed publishing (9)

Preview, queue, retry, or cancel delivery and inspect normalized operation status.

schedule_campaign_output: Schedule an approved campaign output for a future publish time.
preview_publish: Preview how a campaign output would publish on a connection. Does not publish.
queue_publish: Queue publish or draft for an approved campaign output (LinkedIn, WordPress, Ghost, etc.). Google Business returns authorizationUrl for a fresh user-initiated Google sign-in instead of a background job.
retry_publish: Retry a failed campaign publish attempt.
cancel_publish: Cancel a queued or in-flight campaign publish attempt.
list_publish_attempts: List publish attempts for one campaign.
get_operation: Get one canonical long-running operation. Campaign publishing operations use the operationId returned by queue_publish and list_publish_attempts. Status and timeline are identical to the dashboard and REST API.
list_operations: List recent canonical operations for a project. This first slice covers managed Campaign Publishing; generation and Distribution operations are added through the same contract without copying their state.
get_operations: Get operator operations: costs, jobs, publishing health, and dead letters.

Distribution and external handoff (18)

Prepare immutable publication revisions, obtain approval, export packages, and report external delivery.

list_publishing_profiles: List official publishing profiles used to fan out reels to social platforms.
get_publishing_profile: Get one official publishing profile and its connected platforms.
create_publishing_profile: Create an official publishing profile for a project.
connect_publishing_profile: Attach an official API connection or an approved external OpenClaw Instagram identity to a publishing profile.
list_distribution_ready_renders: List ready UGC renders that can be published through official distribution.
list_distribution_ready_photos: List ready photo/image assets for TikTok photo, Instagram feed, LinkedIn image, and similar official posts.
list_distribution_batches: List official distribution batches (TikTok/Instagram/YouTube/X reel publishing).
create_distribution_batch: Create an official distribution batch from a ready render to connected social profiles.
get_distribution_batch: Get one official distribution batch.
update_distribution_revision: Create the next official distribution revision (caption, schedule, media, targets).
create_openclaw_instagram_connection: Register one exact Instagram account for EXTERNAL publication by an audited OpenClaw browser profile. Stores no Instagram credentials and cannot be used by VibeCody's managed publishing worker. The account must already be visibly verified in the stated Chrome profile.
get_distribution_revision_approval: Get TikTok approval context for a distribution revision (connectionId, fingerprint inputs). Requires a TikTok target.
request_distribution_approval: Request human review for the current immutable distribution revision. Returns the revision fingerprint and dashboard approval URL; it never grants approval or enqueues publishing.
approve_distribution_revision: Approve one exact immutable distribution revision using the token owner's standing Full autonomy grant, then queue its targets through the same outbox pipeline as the dashboard. Requires Manage permission, Full autonomy, an exact fingerprint, and a client idempotency key. Reusing the key with another payload conflicts. A strict per-token UTC daily target limit applies. TikTok Direct Post is excluded because TikTok requires explicit per-post user consent.
get_publishing_package: Get the canonical immutable publishing-package revision for an external publisher such as OpenClaw. Returns separate spoken transcript/subtitles and per-platform post copy, exact account identity, schedule, cover semantics, approval/status, media downloads, revision, and fingerprint. It never publishes. By default only an approved revision may be handed off.
report_external_publication: Record an OpenClaw/external publisher result for one EXTERNAL delivery target. This never controls a browser or calls the social provider. The exact approved fingerprint and a client UUID are mandatory; dryRun validates the transition without changing state. Same-key/same-payload replays are safe and changed payloads conflict.
retry_distribution_target: Retry one failed official distribution target.
query_tiktok_creator_info: Query live TikTok creator info (privacy options, duet/stitch flags) for an official TikTok connection.

Automation (4)

Configure recurring automation campaigns and inspect their runs.

list_automation_campaigns: List content automation campaigns, including official Instagram distribution and legacy publish targets.
create_automation_campaign: Create a content automation campaign. Prefer publishingProfileId with an empty publishTargets array for official Instagram distribution; human approval is mandatory.
update_automation_campaign: Update a content automation campaign. Official publishing profiles and legacy publish targets are mutually exclusive.
list_automation_runs: List UGC automation runs for a project or one campaign.

Platform operator only (3)

These tools require a separately enabled global admin token; ordinary account and project tokens cannot call them.

search_users: Search users by email. Global admin only.
list_failed_jobs: List recent failed generation jobs across projects. Global admin only.
list_agent_audit_events: List MCP audit events. Global admin only.

Review and publishing

Submitted content is a draft, not an approval or a publish request. For externally authored content, regenerate_campaign_output with scope: "review" prepares evidence and checks the existing copy without asking the writer to replace it. Review failures remain blocking.

An authorized agent can approve the exact revision; otherwise it can call request_campaign_output_approval for a human review link. Scheduling and publishing are separate actions and still require a ready connection and destination-specific checks. To publish through your own integration, request an approved package with get_content_delivery_package.

Before managed publishing, inspect list_publishing_connections and list_publishing_profiles. Provider OAuth returns a URL that a user must open; the agent cannot complete interactive authorization inside MCP. Preview before queuing, then track the returned operation. An ambiguous provider outcome must be reconciled before retrying.

Troubleshooting

Opening the endpoint in a browser sends GET and returns 405. MCP clients send POST requests.
For authentication errors, confirm the bearer token is active and belongs to the intended account or project.
For a permission error, check both the token permission and the user's current project access.
Browser-based clients must use an allowed Origin; native and server clients normally send no Origin.
For a slow generation or publish operation, poll its status using the returned ID rather than submitting it again.
If credits are exhausted, open the dashboard to add credits. MCP cannot purchase credits or create its own token.

For a native REST integration instead, see the REST API guide. REST access tokens and MCP tokens are different credentials.

Need help? Contact support.