# 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](/mcp/video).

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (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

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

### Codex

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

### Cursor, Gemini, and Other MCP Clients

Point your MCP client at the helper binary:

```txt
/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 `2024-11-05`.

- `initialize` - Negotiates the protocol version and returns supported capabilities and server info.
- `notifications/initialized` - Completes the MCP handshake after `initialize`. This is a notification, so it does not return a response body.
- `ping` - Simple health check endpoint. Kickstart accepts this even before initialization completes.
- `tools/list` - Returns the full catalog of tool definitions, including each tool's description and JSON input schema.
- `tools/call` - Invokes a tool by name with arguments and returns structured tool output.

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:

```json
{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}
{"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

- `tools/list` is the authoritative source for exact input schemas and should be preferred over hand-written client assumptions.
- Every tool that accepts `projectName` uses case-insensitive matching.
- Website tools default `websiteName` to the first website on the project when you omit it.
- `sectionIndex`, `itemIndex`, and `blogPostIndex` are zero-based values returned by `get_website`.
- Use `list_refresh_scopes` before `refresh_project_data` to discover which project data can be refreshed programmatically in the current build.
- `refresh_project_data` reports a per-scope status of `refreshed`, `partial`, `skipped`, `unsupported`, or `failed`; inspect `details` before trusting a `partial` refresh as complete.
- Several workflows require IDs returned by earlier read calls, such as TestFlight group/build/localization IDs and Search Ads campaign IDs.
- To reduce rate limiting, competitor search, ranking, and keyword-check tools query Apple's public App Store API directly; richer competitor analysis can contact Kickstart's data service for details Apple does not include there.
- `tools/call` returns structured tool output with a `content` array; Kickstart currently returns text content there.

## 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

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`, and `check_keyword_rankings` for analysis.
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

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

### Create a project

```json
{"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

```json
{"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

```json
{"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

- If a tool is missing from `tools/list`, the installed Kickstart build may be older, the feature may be gated, or the user may not have the required entitlement. Do not fabricate calls to missing tools.
- If a project is not found, call `list_projects` again and let the user choose from the returned names.
- If an index-based website call fails, call `get_website` and rebuild the operation from the latest returned structure.
- If an App Store Connect, Search Ads, or analytics call fails, report the failing upstream service and keep local project data work separate from network-backed work.
- If a mutation partially succeeds upstream but the follow-up read fails, ask the user before retrying a public action such as responding to a review, submitting a nomination, or generating offer codes.

## Available General Tools

The general MCP surface provides 114 tools across 20 non-video categories. Every tool that accepts a `projectName` parameter uses case-insensitive matching.

### Projects (5)
- `list_projects` - Lists all projects with their basic info (name, tagline, launch date, App Store ID, task completion stats).
- `get_project` - Gets detailed information about a specific project including all metadata and press kit info.
- `create_project` - Creates a new project in Kickstart.
- `update_project` - Updates an existing project's metadata.
- `delete_project` - Deletes a project and all its associated data. Cannot be undone.

### Project Data Refresh (2)
- `list_refresh_scopes` - Lists refreshable project data scopes, including availability and unsupported app-layer-only refreshes.
- `refresh_project_data` - Refreshes selected scopes such as App Store optimization metadata, localizations, revenue details, reviews, keyword tracking, TestFlight, and crash signatures.

### Tasks (5)
- `list_tasks` - Lists tasks for a project. Filter by status (today/overdue/upcoming/completed/all) and category (product/distribution/feedback/intelligence/operations).
- `get_task_stats` - Gets task completion statistics by category and overall progress.
- `complete_task` - Marks a task as completed.
- `uncomplete_task` - Marks a completed task as incomplete.
- `get_todays_agenda` - Gets today's agenda: tasks due today, overdue tasks, and upcoming tasks for the next 7 days.

### Journal (4)
- `list_journal_entries` - Lists all journal entries sorted by creation date (newest first).
- `add_journal_entry` - Creates a new custom journal entry for a project.
- `update_journal_entry` - Updates an existing journal entry's body text by title match.
- `delete_journal_entry` - Deletes a journal entry by title match.

### Revenue and Subscriptions (2)
- `get_revenue_summary` - Gets revenue summary including total revenue, units sold, and breakdowns by territory, device, and product type.
- `get_subscription_analytics` - Gets subscription analytics including active subscribers, churn rates, and subscription events.

### App Analytics (1)
- `get_app_analytics` - Gets app analytics including impressions, downloads, installations, sessions, crashes, and breakdowns by territory, source, and device.

### Reviews (4)
- `get_reviews` - Gets customer reviews with rating, title, body, and response status.
- `respond_to_review` - Posts a developer response to a customer review, visible on the App Store.
- `delete_review_response` - Deletes a developer response from a review.
- `get_review_stats` - Gets review statistics: average rating, rating distribution, and recent trends.

### TestFlight (8)
- `get_testflight_summary` - Gets TestFlight summary including builds, groups, and tester counts.
- `get_testflight_feedback` - Gets feedback from beta testers including screenshots and crash reports.
- `list_beta_testers` - Lists beta testers for a specific group.
- `get_beta_app_localizations` - Gets beta app localizations (feedback email, description, URLs) for each locale.
- `update_beta_app_localization` - Updates a beta app localization's feedback email, description, or URLs.
- `get_beta_build_localizations` - Gets build-level localizations ("What to Test") for a specific build.
- `update_beta_build_localization` - Updates or creates the "What to Test" text for a build in a specific locale.
- `get_beta_tester_metrics` - Gets usage metrics (sessions, crashes, feedback) for beta testers in a group.

### Optimization (2)
- `get_optimization_scores` - Gets App Store Optimization scores for title, subtitle, keywords, and description with an overall weighted score.
- `get_optimization_suggestions` - Gets detailed optimization suggestions organized by severity for improving your App Store listing.

### Localizations (2)
- `list_localizations` - Lists all App Store localizations with completion status and character counts.
- `get_localization_stats` - Gets localization statistics: completion rates, missing locales, and suggested markets.

### In-App Events (4)
- `list_events` - Lists in-app events with state, badge type, schedule, and localization info.
- `create_event` - Creates a new in-app event.
- `update_event` - Updates an existing in-app event.
- `delete_event` - Deletes an in-app event.

### Editorial Nominations (5)
- `list_nominations` - Lists editorial nominations with state and details.
- `create_nomination` - Creates a new editorial nomination.
- `update_nomination` - Updates an existing nomination.
- `submit_nomination` - Submits a draft nomination for editorial review.
- `delete_nomination` - Deletes (archives) a nomination.

### Competitors (10)
- `list_competitors` - Lists tracked competitor apps with cached info.
- `add_competitor` - Adds a competitor app by App Store ID.
- `remove_competitor` - Removes a tracked competitor app.
- `search_apps` - Searches the App Store for apps matching a query.
- `get_search_rankings` - Checks App Store search rankings for a keyword and reports where tracked competitors appear.
- `get_competitor_analysis` - Gets competitive analysis: pricing, ratings, and keyword analysis.
- `list_tracked_keywords` - Lists competitor keywords being tracked for a project.
- `track_keyword` - Adds a competitor keyword to track and optionally fetches today's rankings.
- `remove_tracked_keyword` - Stops tracking a competitor keyword for a project.
- `check_keyword_rankings` - Fetches keyword ranking data and reports ranks for the app and competitors.

### Subscription Management (5)
- `list_subscription_groups` - Lists all subscription groups and their subscriptions, including pricing, state, and localizations.
- `create_subscription_group` - Creates a new subscription group for an app.
- `create_subscription` - Creates a new subscription within a group.
- `update_subscription` - Updates an existing subscription's properties.
- `delete_subscription` - Removes a subscription from sale and deletes it. Cannot be undone.

### Offer Codes (4)
- `list_offer_codes` - Lists all offer code configurations organized by subscription group and subscription.
- `create_offer_code` - Creates a new offer code configuration for a subscription.
- `generate_offer_codes` - Generates a batch of one-time use offer codes. Returns the code values.
- `list_offer_code_generations` - Lists past offer code generation batches including the generated codes.

### Release Checklists (5)
- `list_checklist_templates` - Lists release checklist templates.
- `create_checklist_template` - Creates a new checklist template with categories and items.
- `create_checklist_instance` - Creates a checklist instance from a template for tracking a release.
- `get_checklist_instance` - Gets a checklist instance with all categories, items, and statuses.
- `update_checklist_item` - Updates the status of a checklist item.

### Press Kit (1)
- `get_press_kit` - Gets press kit content including markdown description, contact info, and configuration.

### Website Builder (13)
- `get_website` - Returns the full website state: metadata, theme, header, footer, blog posts, and every section with nested items.
- `list_website_section_types` - Returns a catalog of all 18 section types with descriptions, fields, and item schemas.
- `create_website` - Creates a new website with default header and footer.
- `add_website_section` - Adds a new section with field values and optional inline nested items.
- `update_website_section` - Partially updates section-level fields by index.
- `remove_website_section` - Removes a section by index.
- `add_section_items` - Adds nested items to an existing section (FAQ questions, features, testimonials, etc.).
- `add_blog_post` - Adds a blog post to the website. The first paragraph becomes the summary used on the blog index and RSS feed.
- `update_blog_post` - Partially updates a blog post by its `blogPostIndex` from `get_website`.
- `remove_blog_post` - Removes a blog post by its `blogPostIndex` from `get_website`.
- `remove_section_item` - Removes a nested item from a section by index.
- `update_website_settings` - Updates site metadata, theme, header, footer, custom domain, privacy, and code injection.
- `reorder_website_sections` - Moves a section from one position to another.

### Apple Ads (31)
- `search_ads_credential_doctor` - Checks Apple Ads credential readiness, OAuth access, accounts, and permission warnings.
- `list_search_ads_accounts` - Lists Apple Ads ad accounts available to the configured credentials.
- `get_search_ads_campaigns` - Lists Apple Ads campaigns with status, serving state, budgets, markets, and optional app filtering.
- `get_search_ads_ad_groups` - Lists ad groups for a campaign.
- `get_search_ads_keywords` - Lists targeting keywords for a campaign or ad group.
- `get_search_ads_negative_keywords` - Lists campaign-level or ad-group-level negative keywords.
- `get_search_ads_ads` - Lists ads for a campaign or ad group.
- `get_search_ads_creatives` - Lists creatives for an app, including custom product page creatives.
- `check_search_ads_app_eligibility` - Checks app eligibility for one or more countries or regions.
- `get_campaign_report` - Gets campaign performance: impressions, taps, installs, spend, TTR, CVR, CPA, and daily trend rows.
- `get_keyword_report` - Gets keyword performance: impressions, taps, installs, spend, and conversion rates.
- `get_search_ads_report` - Gets campaign, ad group, keyword, search term, or ad performance reports.
- `create_search_ads_impression_share_report` - Creates an impression share custom report job after explicit confirmation.
- `list_search_ads_impression_share_reports` - Lists impression share custom report jobs.
- `get_search_ads_impression_share_report` - Gets status and download details for an impression share report.
- `build_search_ads_campaign_draft` - Builds a cautious paused campaign draft from a project and budget inputs.
- `apply_search_ads_campaign_draft` - Applies a paused campaign draft and verifies created paused entities.
- `start_search_ads_campaign` - Enables a verified campaign, its ad groups, and optional ads.
- `create_search_ads_campaign` - Creates an Apple Ads campaign, paused by default.
- `update_search_ads_campaign` - Updates campaign name, countries, daily budget, or status.
- `create_search_ads_ad_group` - Creates an ad group, paused by default.
- `update_search_ads_ad_group` - Updates ad group name, default bid, or status.
- `create_search_ads_keywords` - Adds targeting keywords to an ad group.
- `update_search_ads_keywords` - Updates keyword bids or statuses.
- `create_search_ads_negative_keywords` - Adds campaign-level or ad-group-level negative keywords.
- `update_search_ads_negative_keywords` - Updates negative keyword statuses.
- `delete_search_ads_negative_keywords` - Deletes negative keywords.
- `create_search_ads_creative` - Creates a custom product page creative.
- `create_search_ads_ad` - Creates an ad attached to a creative, paused by default.
- `update_search_ads_ad` - Updates an ad name or status.
- `delete_search_ads_ad` - Deletes an ad.

### Achievements (1)
- `list_achievements` - Lists celebrated milestones including revenue, download, rating, and review milestones.

## Requirements

- Kickstart installed in `/Applications`.
- Kickstart opened at least once so it can populate local data.
- App Store Connect API keys configured in Kickstart for App Store Connect-backed tools.
- Search Ads credentials configured in Kickstart for Search Ads tools.
- Network access for App Store, Search Ads, competitor lookup, ranking, and analytics requests.