Kickstart Download Kickstart

General MCP

Project data, App Store Connect, website editing, reviews, revenue, analytics, and more.

For video-specific automation, including .ksvideo creation, narration, 3D devices, and movie export, use the Video MCP documentation.

What is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI assistants interact with external tools. Kickstart includes a bundled MCP helper that exposes project data - revenue, reviews, TestFlight builds, competitors, websites, and more - so AI tools can read and act on it directly.

This means you can ask Claude, Codex, Gemini, or another MCP client questions such as "How is my app performing this month?" or "Create a new subscription group", and they can use your real Kickstart data to answer.

How to Set Up

Kickstart ships with a KickstartMCP command-line helper bundled inside the app. MCP clients invoke it directly over stdio - no server to start, no port to configure.

  1. Make sure Kickstart is installed in /Applications.
  2. Open Kickstart at least once so your data is populated.
  3. Add the following to your MCP client's configuration.

Claude Code

claude mcp add kickstart -- /Applications/Kickstart.app/Contents/Helpers/KickstartMCP

Codex

codex mcp add kickstart -- /Applications/Kickstart.app/Contents/Helpers/KickstartMCP

Cursor, Gemini, and Other MCP Clients

Point your MCP client at the helper binary:

/Applications/Kickstart.app/Contents/Helpers/KickstartMCP

After adding the configuration, restart your AI tool so it picks up the new MCP server. You can also find the path in Kickstart's Settings > General.

Protocol Endpoints

Kickstart uses stdio transport with JSON-RPC 2.0 and supports MCP protocol version 2025-06-18 with compatibility for 2024-11-05.

Kickstart accepts both single JSON-RPC requests and batch arrays. Operational methods other than ping require the full initialize -> notifications/initialized handshake first.

Raw Client Flow

Most users should let Claude, Codex, Cursor, Gemini, or another MCP client handle this automatically. If you are building a client yourself, this is the expected request sequence:

{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":1,"method":"tools/list"}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_projects","arguments":{}}}

Usage Notes

Agent Operating Loop

A capable agent should treat Kickstart as a stateful source of truth. Do not guess IDs, indexes, or tool availability; discover them, call the narrowest tool that does the job, then read back the result.

  1. Start every session with initialize, notifications/initialized, then tools/list. Hide or skip workflows whose tools are not listed.
  2. Call list_projects before project-specific work and use the returned project name when calling other tools. Matching is case-insensitive, but exact names make logs easier to audit.
  3. Read before writing. For example, call get_website before changing website sections, list_subscription_groups before subscription edits, and get_testflight_summary before build-localization work.
  4. Preserve IDs and indexes returned by read tools. App Store Connect IDs, Search Ads campaign IDs, TestFlight IDs, section indexes, item indexes, and blog post indexes should be copied from Kickstart responses.
  5. After a mutating call, read back the same resource if another call depends on the updated state. This avoids stale indexes after section reordering, deletion, or item insertion.
  6. Prefer small, reversible operations. Destructive tools such as delete_project, delete_subscription, delete_event, and remove_blog_post should only be used when the user explicitly asks for that outcome.
  7. Summarize important tool results to the user, especially public App Store actions such as review responses, in-app events, nominations, subscriptions, and offer-code generation.

Response Handling

Kickstart returns normal MCP responses. The actual tool payload is usually JSON encoded as text inside the first content item, so external clients should parse that text before deciding what happened.

Successful tool response

Look for result.content[0].type == "text", then parse result.content[0].text as JSON. Most read tools return arrays or objects with fields such as projects, tasks, reviews, sections, items, or summary. Mutating tools usually include a status message and enough updated state to plan the next call.

Tool-level errors

If result.isError is true, the MCP call reached Kickstart but the requested operation failed. Show the error to the user, then recover using a read call when possible. Common causes include missing projects, missing App Store Connect credentials, unavailable Pro-only tools, invalid website indexes, App Store API failures, or a tool schema mismatch.

JSON-RPC errors

If the top-level response contains error, the client sent an invalid MCP request, called an unknown method, skipped initialization, passed malformed JSON, or used an unknown tool name. Re-run tools/list and rebuild the call using the schema returned there.

Common General Workflows

Analyze an app launch

  1. Call list_projects, then get_project for the selected app.
  2. If the user wants fresh upstream data, call list_refresh_scopes, then refresh_project_data for the relevant available scopes before reading summaries.
  3. Call get_todays_agenda, get_task_stats, and list_tasks to assess operational work.
  4. Call get_revenue_summary, get_app_analytics, get_review_stats, and get_reviews when App Store Connect data is configured.
  5. Call get_optimization_scores, get_optimization_suggestions, list_localizations, and get_localization_stats for App Store listing quality.
  6. Return a concise written analysis with concrete next actions, and only mutate data if the user requested changes.

Edit a generated website

  1. Call get_website and keep the returned sectionIndex, itemIndex, and blogPostIndex values.
  2. Call list_website_section_types if you need to add a new section, because section type names and field names must match Kickstart's schema.
  3. Use add_website_section, update_website_section, add_section_items, remove_section_item, or reorder_website_sections for page content.
  4. Use add_blog_post, update_blog_post, or remove_blog_post for blog work.
  5. Use update_website_settings for site-level styling, navigation, footer, custom domain, analytics, and privacy settings.
  6. Call get_website again after structural changes so follow-up calls use fresh indexes.

Work with App Store Connect data

  1. Call the relevant list or summary tool first: get_testflight_summary, list_events, list_nominations, list_subscription_groups, list_offer_codes, or get_reviews.
  2. Copy exact IDs from the response into update, delete, submit, response, localization, and generation calls.
  3. For public-facing text, write complete production copy in the tool call. Do not rely on Kickstart to expand placeholders.
  4. After any create, update, submit, or delete call, read the same resource again so the user can verify the resulting App Store state.

Research competitors and keywords

Check get_keyword_data_mode first. If a mode is needed but unselected, explain both options and use set_keyword_data_mode with the user's choice. Do not switch to server analysis automatically to satisfy a tool requirement.

  1. Use search_apps to find App Store IDs, then add_competitor to track apps selected by the user.
  2. Use list_competitors, get_competitor_analysis, get_search_rankings, get_keyword_popularity, check_keyword_rankings, and discover_keywords_for_app for analysis. Keyword discovery requires Server-backed mode.
  3. Use track_keyword and remove_tracked_keyword to maintain the project's tracked keyword set.

Raw Tool Call Examples

These examples are intentionally plain JSON-RPC so any client, including Gemini, Claude, Codex, Cursor, or a custom script, can reproduce them. Always compare with tools/list in the running app before sending production mutations.

List projects

{"jsonrpc":"2.0","id":10,"method":"tools/call","params":{"name":"list_projects","arguments":{}}}

Create a project

{"jsonrpc":"2.0","id":11,"method":"tools/call","params":{"name":"create_project","arguments":{"name":"Example App","tagline":"Plan, launch, and improve faster.","description":"A focused planning app for indie developers.","launchDate":"2026-06-01"}}}

Read and update website settings

{"jsonrpc":"2.0","id":12,"method":"tools/call","params":{"name":"get_website","arguments":{"projectName":"Example App"}}}
{"jsonrpc":"2.0","id":13,"method":"tools/call","params":{"name":"update_website_settings","arguments":{"projectName":"Example App","siteName":"Example App","customDomain":"www.example.com","primaryColor":"#34C759","colorScheme":"dark","headerBrandName":"Example App","footerTagline":"Build better launches."}}}

Respond to a review

{"jsonrpc":"2.0","id":14,"method":"tools/call","params":{"name":"get_reviews","arguments":{"projectName":"Example App","limit":10}}}
{"jsonrpc":"2.0","id":15,"method":"tools/call","params":{"name":"respond_to_review","arguments":{"projectName":"Example App","reviewID":"REVIEW_ID_FROM_GET_REVIEWS","responseBody":"Thanks for the thoughtful feedback. We have passed this to the team and will keep improving the experience."}}}

Recovery Notes

Available General Tools

The general MCP surface covers the non-video categories below. Use tools/list for the discoverable catalog. Every tool that accepts a projectName parameter uses case-insensitive matching.

Projects (5)

Project Data Refresh (2)

Tasks (5)

Journal (4)

Revenue and Subscriptions (2)

App Analytics (1)

Reviews (4)

TestFlight (8)

Optimization (2)

Localizations (2)

In-App Events (4)

Editorial Nominations (5)

Competitors (6)

Keywords (8)

Keyword Insights (9)

Every tool in this group requires an active Kickstart Pro subscription, including reads of cached results. Use a linked projectName; App Store Connect credentials are not needed for ranking discovery or history. Ranking tools respect the installation's existing Server-backed mode and never change that choice, add tracked keywords, update a manifest, or request Apple fetching.

Start with discovery, select a keyword, then request its history. A fresh local list avoids another discovery download. New discovery network starts are paced at one per second across calls within the MCP process. Daily history downloads have no rate or volume quota and share the Core downloader's six concurrent request slots. Cancellation stops the request's pending work; completed encrypted data can be reused later.

Timeline and CPP analytics tools can use locally retained App Store Connect data in either keyword mode. They still require Pro. The rank impact tool additionally requires Server-backed mode because it reads ranking history. Missing Analytics does not prevent ranking history; refresh Analytics in Kickstart to populate acquisition comparisons. Detailed metrics are kept separate from Standard totals. App Store Search includes Search Ads and must not be described as organic-only traffic.

Downloaded discovery/history, derived ranks, and timeline data stay encrypted in the app/MCP shared local storage. MCP intentionally returns readable requested results to its authorized caller. The local discovery pacing is cooperative, not a server-enforced scraping restriction.

Subscription Management (5)

Offer Codes (4)

Release Checklists (5)

Press Kit (1)

Website Builder (14)

Apple Ads

Start with list_search_ads_accounts or search_ads_credential_doctor, then use the resource and query tools below. Before constructing an unfamiliar request, call describe_apple_ads_tool with its exact toolName. It returns complete argument guidance, filter/sort tables, detailed output schemas, and Apple endpoint links without credentials or Pro. Discovery keeps compact output-envelope types. tools/list retains argument structure, constraints, and safety guidance; established valid requests still work directly. Queries return one page of Apple's complete JSON. Preserve null values as unavailable evidence and follow the returned pagination. Numeric resource identifiers accept positive 64-bit integers or decimal strings. Opaque product-page identifiers remain strings. Money amounts, including draft budgets and target CPA, must be positive decimal strings such as "1.25", with explicit uppercase currencies.

Write startTime/endTime values use UTC strings such as 2026-09-21T10:00:00.000, without Z or an offset. Milliseconds may be omitted and are normalized to .000. Zoned values are rejected locally: convert the instant to UTC first, rather than removing the offset. Explicit endTime: null still clears an expiration.

API create and update tools require the Apple request in body and return the complete Apple JSON response. MCP 2.0.0 removes the deprecated flat arguments. Runtime validation rejects missing bodies and unknown wrapper arguments before HTTP. New campaigns, ad groups, ads, and targeting keywords default to paused. Every mutation requires confirm: true and uses the selected account. Bulk bodies expose allowPartialSuccess and per-item correlation IDs. A timeout or cancellation can leave a remote change in progress: read back before retrying.

Do not assume % is a wildcard in LIKE filters. September 18, 2026 probes matched campaign and supported-language names without %, while adding surrounding % returned no matches. Guidance includes this caution on every endpoint advertising LIKE; other endpoints have not been verified. Successful queries containing % in LIKE filter values return LIKE_PERCENT_LITERAL warnings. Filter values and Apple responses remain unchanged. Apple rejected promotedObjectId NOT_IN despite its documentation; NOT_EQUALS worked. campaignId IN worked for ad groups and ads. Keyword queries still require campaignId EQUALS when that filter is supplied; IN support has not been verified for keywords. Campaign-level negatives require campaignId EQUALS plus adGroupId IS_NULL, without a value.

RUNNING is not proof of delivery. Cross-check future startTime, expired endTime, the account time zone and current daypart, parent state, and reports. Report rows use totalMetrics and granularMetrics; missing metrics remain unavailable evidence.

Reads retry supported transient transport failures and HTTP 408/500/502/503/504 up to twice. Reads and writes refresh authentication once after 401 and retry 429 with bounded pacing inside the operation deadline. Writes do not retry transient failures; reconcile uncertain writes before retrying.

The Apple Ads interface supports App Store campaign management. Apple Maps campaign management, ad-account creation/delegation administration, and asset upload/deletion are outside its scope. Selecting an account without verified App Store product support is rejected without changing the shared selection.

Results expose the same JSON envelope in text and structuredContent, including errors, warnings, outcomes, and request metadata. httpRequestCount counts all HTTP attempts, including preflight reads; attemptCount is its compatibility alias and retryCount counts retries. HTTP 200 write errors still set isError; outcome distinguishes confirmed failure from partial or unknown application. This also preserves machine-readable evidence for older MCP clients. Kickstart-generated outcome resourceID values are strings; Apple IDs inside response retain their original types. Account listing and scoped delete helpers return synthesized summaries. Multi-ID negative-keyword deletion reports one outcome item per unique ID, with separate succeeded, alreadyDeleted, failed, unknown, and unattempted counts. Individual HTTP receipts in lastWriteResponse are not workflow totals.

Inspect report warnings before describing a grouped breakdown. On 2026-09-17, campaign and ad group reports requested with countryCode, ageRange, or gender returned aggregate rows without the requested dimension metadata. REPORT_GROUPING_UNVERIFIED identifies affected dimensions and row counts. Do not interpret those rows as a single-country or demographic result. A single row containing the requested dimension is valid; an empty report provides no grouping evidence.

On 2026-09-17, impression share, search-term popularity, and target CPA suggestions each reported RateLimit-Limit: 5. This is per reported window, not a fixed daily limit. Check requestMetadata.attempts[].rateLimitHeaders, particularly RateLimit-Remaining, RateLimit-Reset, and Retry-After; limits can change. Long windows allow a small burst shared by helper processes while quota is ample, then resume sustained pacing. Low or exhausted quota and Retry-After can cause waits or a rateLimitWait error when the operation deadline would be exceeded. Avoid parallel research loops.

Known immutable update fields are rejected locally, including campaign account/app identity and billing event, ad group pricing model, keyword identity, ad parent/creative IDs, and creative type/destination. Additional Apple fields remain accepted. Apple only soft-deletes resources, so a deleted record remains after cleanup. On 2026-09-17, a confirmed dailyBudget change was absent from change history and its field-level details; read budgets back directly rather than treating missing history as proof they were unchanged.

Kickstart's shared credential vault uses an AES-GCM envelope whose keys come from constants shipped in the app. It provides obfuscation rather than protection from someone who can read the vault and the binary. Credential sync copies the same wrapped blob to iCloud. File protection and iCloud account security remain separate protections.

Writes must use the selected account. A mismatched accountID is not an instruction to change the shared selection; if the user wants another shared account, select_search_ads_account verifies APPSTORE_APP_MANUAL and refuses unsupported accounts. During credential validation, a failed details refresh for the same selected account preserves previously verified product features, currency, and time zone where unavailable. Credential Doctor reports this warning; current ACL roles and membership still apply.

HTTP 200 recommendation validation errors with no result rows can be definite atomic rejections: every input is failed and noChangesApplied is true when all detail codes are recognized and identifiers are consistent. Mixed or conflicting evidence remains uncertain. Error strings summarize HTTP status, codes, fields, and guidance; complete payloads remain in response, outcome, and partialResult, including for text-only MCP 2024-11-05 clients. Delete annotations advertise idempotence; budget-order creation is marked destructive because it changes the shared spending limit.

Unknown wrapper arguments are rejected before any request. Use accountID, with that exact spelling. Account-scoped responses identify the account used. Query schemas describe endpoint-specific fields, operators, and sorting without restricting additional Apple payload fields. Impression-share pages support up to 10,000 rows. Search-term popularity and report pages support up to 5,000.

HTTP 403 responses preserve Apple's error and direct you to search_ads_credential_doctor to refresh stored permissions; check permissionsPersisted and warnings. list_search_ads_accounts with refresh: true lists current access without saving permissions. App and MCP writes revalidate stale permissions and check the shared credentials and account selection immediately before submission. Search Ads Basic (APPSTORE_APP_AUTOMATED) lacks the APPSTORE_APP_MANUAL capability required by App Store campaign endpoints.

Create, update, and delete tools accept the applicable expectedCampaignID, expectedAdGroupID, or expectedAppID guards. A mismatch prevents the entire request from being submitted. Atomic bulk rejections identify every unapplied input. Partial failures set isError and preserve successful IDs and every outcome; retry only confirmed failed items. Parent assertions remain all-or-nothing even with allowPartialSuccess. Scoped updates validate IDs in bounded queries. Repeat deletes report an already-deleted resource only after readback confirms its deleted state. For the plural negative-delete helper, already-deleted items do not count as new successes. A preflight rejection with no new deletions reports outcome.status: failed in either ID order; only actual successful deletions make a batch with failed or unattempted items partial.

Always verify important changes with an independent read. Changing campaign countries, including replacing one country with another, can remove ad-group geographic targeting. Accepted or uncertain changes preserve warnings with the previous targeting; definite rejections do not report targeting side effects. To clear maximum age, use maxAge: null; maxAge: {"include": null} and an empty include array are rejected locally because Apple has returned success without clearing the limit. Reverting Maximize Conversions to Manual CPT requires bid: null inside bidStrategy to clear the target CPA. For owned-app discovery, continue until an empty or short page, detecting repeated pages, because totalCount can describe only one page.

Creative queries use the accountID wrapper for account selection; Apple rejects an adAccountId filter. For example, find custom-page creatives with a supported filter, then match their destination.parameters.adamId to your app:

{"name":"query_search_ads_creatives","arguments":{"query":{"filters":[{"field":"creativeType","operator":"EQUALS","value":"CUSTOM_PRODUCT_PAGE"}],"pagination":{"offset":0,"pageSize":100}}}}

Follow an asset reference from a localization response using its UUID:

{"name":"get_search_ads_asset","arguments":{"assetID":"A426EE92-E6D3-41F9-9BA8-AF990C00D3D1"}}

Before changing a keyword, use identifiers from your own reads. This example requires the keyword to belong to campaign 42 and ad group 7 before applying the change:

{"name":"update_search_ads_keyword","arguments":{"keywordID":123,"expectedCampaignID":42,"expectedAdGroupID":7,"body":{"status":"PAUSED"},"confirm":true}}

Tool discovery remains stable if Pro access changes. Calls still enforce Pro access and explain whether the shared entitlement is missing, inactive, expired, or unreadable. Development and production apps store their entitlement snapshots separately.

Cancellation recovery is available by default. The following campaign workflows require the helper launch argument --apple-ads-workflows; the app's campaign planner remains available:

Draft application rechecks edited amounts, names, IDs, markets, and custom product pages before creating resources. The draft builder does not validate Apple eligibility or suggestions and does not provide evidence for keyword exclusions. Review its proposed fields and use the query tools to validate the draft before applying it. Agents can also compose research, campaign changes, and measurement from the API tools.

Compact discovery and workflow opt-in

MCP 2.0.0 includes compact discovery and optional campaign workflows. This release removes legacy read aliases and flat write arguments; follow the migration guide below. Refresh tools/list after upgrading. The default catalog contains 85 Apple Ads tools. To continue using build_search_ads_campaign_draft, apply_search_ads_campaign_draft, or start_search_ads_campaign, add --apple-ads-workflows to the helper's launch arguments and restart it. This enables all three workflow tools, for 88 Apple Ads tools. Draft money values must use the current amount and currency object contract. Otherwise, compose planning and execution from the query and mutation primitives.

For full endpoint guidance, use:

{"name":"describe_apple_ads_tool","arguments":{"toolName":"query_search_ads_campaigns","section":"all"}}

The optional section can be request, response, examples, or all. The examples section points to this guide. Cache results by contentVersion. Full schemas retain Apple's open nested bodies and unrestricted response JSON. Safety checks and runtime validation are unchanged.

Write permissions now require separate ACL/role and product-feature verification within 24 hours. Kickstart refreshes expired permissions before writes; an unavailable refresh can block the write. Account-detail failures preserve previously verified metadata without renewing its verification time. Selected-account read denials trigger a permission check, but endpoint-specific denial alone does not revoke fresh permissions. Authentication and permission refresh can update the shared cache and vault. APPSTORE_APP_AUTOMATED-only accounts lack manual campaign support; refreshing credentials cannot add that capability. Credential Doctor reports the verification timestamps and permissionStaleReason. Do not change the shared account selection to resolve such errors.

Recovery lookups can now return snapshots from previous helper processes. Match the original requestID, sessionID, and recoveryID; integer and string spellings may identify multiple records. Records are cancellation evidence rather than final write outcomes. Recovery evidence is captured after signaling cancellation. Snapshots from older helpers whose cancellation ordering cannot be verified retain their resource IDs, but report conservative noChangesSubmitted: false and noChangesApplied: false with a message requiring readback. Read back uncertain resources before retrying.

Migrating to MCP 2.0.0

MCP 2.0.0 removes ten read aliases. Replace them with the following tools, supplying Apple's request object in query:

Removed command Replacement
get_search_ads_campaigns query_search_ads_campaigns
get_search_ads_ad_groups query_search_ads_ad_groups
get_search_ads_keywords query_search_ads_keywords
get_search_ads_negative_keywords query_search_ads_negative_keywords
get_search_ads_ads query_search_ads_ads
get_search_ads_creatives query_search_ads_creatives
check_search_ads_app_eligibility query_search_ads_app_eligibility
get_campaign_report query_search_ads_campaign_report
get_keyword_report query_search_ads_keyword_report
get_search_ads_report query_search_ads_campaign_report, query_search_ads_ad_group_report, query_search_ads_keyword_report, query_search_ads_search_term_report, or query_search_ads_ad_report, according to the report level

Move read filters into query.filters, dates into query.timeRange, and pagination into query.pagination. Resolve projectName to an App Store app ID before querying; use the endpoint's documented app filter. Creative queries return account pages: match destination.parameters.adamId yourself and follow pagination.

These eleven write names remain, but accept only the Apple body contract: create_search_ads_campaign, update_search_ads_campaign, create_search_ads_ad_group, update_search_ads_ad_group, create_search_ads_keywords, update_search_ads_keywords, create_search_ads_negative_keywords, update_search_ads_negative_keywords, create_search_ads_creative, create_search_ads_ad, and update_search_ads_ad.

Use each tool's published body schema rather than nesting the old flat arguments unchanged. Apple field names and structures differ: for example, dailyBudget becomes body.dailyBudget.value with an amount and currency, and keyword batches use body.items. Keep accountID, the update's resource ID, confirm, and applicable expected…ID guards outside body. Parent IDs for creation belong inside the Apple body. For example:

{"name":"update_search_ads_campaign","arguments":{"campaignID":42,"body":{"name":"Renamed campaign"},"confirm":true}}

Refresh the MCP tool catalog or restart the client after upgrading. Supported MCP wire protocol versions remain 2024-11-05 and 2025-06-18; the server contract version is separate.

Achievements (1)

Requirements