# Set up the ASOgenic MCP server

Use the section for the client that will actually call ASOgenic. Do not mix commands or
connection state between clients.

Server name: `asogenic`
Transport: Streamable HTTP
Server URL: `https://mcp.asogenic.com/mcp`
Interactive authentication: OAuth

There are two separate authorization layers. MCP OAuth signs the client into ASOgenic.
An App Store Connect Issuer ID, Key ID, and private `.p8` key authorize Apple access.
Browser login completes only the first layer. Always call `asogenic_auth_status` next.

## Codex CLI and Codex IDE extension

These two clients share MCP configuration:

```bash
codex mcp add asogenic --url https://mcp.asogenic.com/mcp
codex mcp list
codex mcp login asogenic
```

Complete browser OAuth, then start a new Codex session and call
`asogenic_auth_status`. A callback such as
`http://127.0.0.1:<port>/callback` is the CLI's temporary listener. It is expected and is
not the MCP server URL.

## ChatGPT Work developer-mode plugin

This creates a personal plugin in ChatGPT Work and is separate from `codex mcp add`.
Creating it does not authenticate Codex CLI, the IDE extension, or another Codex surface.

1. In ChatGPT, enable Developer mode under Settings → Security and login.
2. Open ChatGPT Plugins, select +, and create a plugin named ASOgenic with MCP URL
   `https://mcp.asogenic.com/mcp` and OAuth authentication.
3. Review the discovered tools, create the plugin, open it, and select + to install it.
4. Start a new Work chat, enable/select ASOgenic, and finish OAuth when prompted.
5. Call `asogenic_auth_status`.

Do not use `codex mcp login` to repair a ChatGPT plugin. Refresh/reconnect the plugin in
ChatGPT Plugins and start a new Work chat. Codex CLI/IDE users follow the Codex section.

## Claude Code

```bash
claude mcp add --transport http --scope user asogenic https://mcp.asogenic.com/mcp
claude mcp list
claude mcp get asogenic
```

Start `claude`, run `/mcp`, select ASOgenic, and complete OAuth. Confirm it is connected,
then call `asogenic_auth_status`. These commands are for Claude Code, not Claude Desktop.

## Claude, Cowork, and Claude Desktop

Remote connectors are configured through Claude's account UI, including on Claude Desktop.
Do not use Claude Code commands or desktop JSON configuration.

For an individual account: open Customize → Connectors → + Add → Add custom connector.
Name it ASOgenic, enter `https://mcp.asogenic.com/mcp`, keep the discovered OAuth method, finish adding
it, and complete sign-in. In a new conversation, enable ASOgenic from + → Connectors and
call `asogenic_auth_status`.

On Team or Enterprise, an authorized owner first adds it under Organization settings →
Connectors → Add → Custom → Web. Each member then connects it under Customize → Connectors
and enables it in the conversation.

## Cursor IDE and Cursor Agent CLI

Add this to global `~/.cursor/mcp.json` (or project `.cursor/mcp.json` only when
project-specific scope is intended):

```json
{
  "mcpServers": {
    "asogenic": {
      "url": "https://mcp.asogenic.com/mcp"
    }
  }
}
```

Enable ASOgenic in Cursor MCP settings, select Needs login, and finish OAuth. Start a new
Agent chat, confirm ASOgenic appears under Available Tools, and call
`asogenic_auth_status`. Cursor Agent CLI diagnostics are `cursor-agent mcp list`,
`cursor-agent mcp login asogenic`, and `cursor-agent mcp list-tools asogenic`.

## VS Code with GitHub Copilot

Run MCP: Add Server from the Command Palette, choose HTTP, use `https://mcp.asogenic.com/mcp`, and name
it asogenic. Then run MCP: List Servers, start ASOgenic, and approve OAuth. In Copilot Chat
Agent mode, enable ASOgenic through Configure Tools, start a new chat, and call
`asogenic_auth_status`.

## Other OAuth-capable MCP clients

Add a Streamable HTTP server named asogenic with URL `https://mcp.asogenic.com/mcp`, leave custom
headers empty, and use that client's Connect, Sign in, or Authorize action. Complete OAuth
in the same product, open a new session, and call `asogenic_auth_status`. If the client
does not support MCP OAuth, choose a supported OAuth-capable client. Platform API keys are
reserved for CI, cron, and other unattended automation. Do not copy commands or tokens from
another product.

## Unattended automation

CI, cron, and headless jobs use an ASOgenic platform API key created at
https://asogenic.com/dashboard. Store it in the job's secret manager. This is the only setup
where a fixed Authorization header is expected:

{
    "mcpServers": {
        "asogenic": {
            "url": "https://mcp.asogenic.com/mcp",
            "headers": {
                "Authorization": "Bearer <your key>"
            }
        }
    }
}

Never put App Store Connect credentials in MCP configuration, and never add a bearer header
to an interactive OAuth setup.

## Connect App Store Connect

After the MCP connection is authenticated, call `asogenic_auth_status`. If hosted Apple
access is missing or invalid, open the exact `next_action.url` in a browser and guide the
user to connect or replace the key in their signed-in ASOgenic dashboard. Never ask them
to send the private key through chat or an MCP tool. Then call `asogenic_auth_status` again.
Continue only when `asc_configured: true` and
   `asc_valid: true`, then call `asogenic_list_apps`.

The complete release workflow requires an Apple key with App Manager or a higher role.
Apple permits a `.p8` download only when the key is created. A lost key must be revoked
and replaced.

## Client-specific recovery

- Codex CLI/IDE: run `codex mcp list`, log in if needed, and start a new Codex session.
- ChatGPT Work plugin: refresh ASOgenic in ChatGPT Plugins, confirm `/mcp`, install and
  enable it, and start a new Work chat. Do not run the Codex CLI login as a substitute.
- Claude Code: run `claude mcp get asogenic`, then authenticate from `/mcp`. Clear stale
  authentication there or run `claude mcp logout asogenic` before a fresh login.
- Claude app/Desktop: confirm the account connector exists and is enabled for the current
  conversation. Team/Enterprise users may need an owner to add it first.
- Cursor: keep the URL-only entry, select Needs login, then open a new Agent chat.
- VS Code: start the server through MCP: List Servers, enable its tools, and use
  MCP: Reset Cached Tools if discovery is stale.
- Consent URL 404: close the old tab and start a fresh OAuth action from the same client.
  Transaction URLs are short-lived and single-use.
- `Auth required` or `no verified tenant for this request`: reconnect the exact surface
  making the call. Never copy OAuth tokens between clients.
- `asc_configured: false`: MCP authentication works. The Apple credential is still missing.
- `asc_valid: false`: verify the Issuer ID/Key ID pair, complete key text, key status, and
  Apple role. Have the user replace a known-invalid credential in the signed-in dashboard.
- `/readyz` works but tools fail: readiness does not prove MCP identity or Apple access.
- Brief HTTP 502: retry after recovery. Do not rotate credentials for a transient error.

## Run an optimization pass

The order that actually gets an app through Apple review:

1. `asogenic_auth_status`: credentials work.
2. `asogenic_list_apps` / `asogenic_resolve_app`: find the app. Keep the `session_key`.
3. `asogenic_intake_product_context`: tell ASOgenic what the app is (everything
   downstream depends on this).
4. Per locale: `asogenic_fetch_source` -> generate name/subtitle/keywords/description
   yourself (`asogenic_research_keywords`, `asogenic_assemble_locale`,
   `asogenic_get_field_spec` are aids) -> `asogenic_validate_record` ->
   `asogenic_approve_locale` -> `asogenic_publish`.
5. Store setup (each required before submission): category, age rating, version
   copyright, content-rights declaration, review info, base price, screenshots.
   Complete and verify App Privacy separately in the App Store Connect web UI.
6. `asogenic_get_release_readiness`: read `blockers` (must be empty) and `warnings`.
7. `asogenic_submit_for_review`.

## Limits

Your account gets 500 tool calls per month. This allowance is account-wide across
OAuth connections and platform API keys. Short-window rate limiting also applies (about
120/minute). A `RATE_LIMITED` error means slow down and retry in seconds. A
`QUOTA_EXCEEDED` error means the monthly allowance is spent. ASOgenic is free for a limited time. No card is required.

Full docs: https://asogenic.com/docs. FAQ: https://asogenic.com/faq