# Submit a project with ChatGPT, Claude Code, or Codex

This is the maintained submission workflow for Maximizing Potential. Start from the event-specific prompt at https://home.maximizingpotential.workers.dev/projects/submit/. The `assistant` query parameter selects `chatgpt`, `claude-code`, or `codex`; use that client’s connection instructions below. The `event` query parameter on this guide identifies the requested hackathon; retain that exact event ID throughout preparation. The participant reviews the actual details and files on the site before publication.

Origin: `https://home.maximizingpotential.workers.dev`
Dedicated MCP endpoint: `https://home.maximizingpotential.workers.dev/mcp`

Use the origin shown above consistently for the assistant connection, guide, and submission. Keep an existing connection on its original hostname; signing in on another hostname does not move that browser session or OAuth connection. The upload helper recognizes both official production hostnames and uploads only to the hostname in the saved receipt. An optional `MP_ORIGIN` setting pins that hostname and must match the receipt; it cannot redirect an upload to another server.

## Preserve the project before choosing hosting

This guide prepares a project for submission. It does not prescribe the project's architecture, feature count, or level of ambition. The optional build prompt is a starting point for the participant's own idea. Choose a useful outcome for the intended users, build and test the complete core workflow, and describe what is demonstrated versus still planned.

Preserve an existing project's source, framework, working features, authentication, persistent data, integrations, and deployment. Do not rewrite it as a smaller static app, remove useful features or assets, replace real services with canned responses, or substitute temporary memory for persistence to fit this site's uploader. Scope changes should follow the participant's goals and available time, with their agreement.

The built-in host's file-count and byte limits apply only to files uploaded to that host. They are not limits on the source repository or the complexity of an externally hosted project. A working external HTTPS demo is a normal submission route: its project page and judging entry live on Maximizing Potential, while the app keeps its own hosting. It uses the same participant review and publication process. Hosting choice does not by itself establish eligibility, quality, or judging completion; follow the selected event's actual rules.

Choose the route **before preparing a draft**:

| Project needs | Submission route |
| --- | --- |
| A working external demo, or a runtime, database, authentication, storage, device access, or build size incompatible with the built-in host | Preserve or help deploy the actual app, verify its public HTTPS demo, use `hosting_mode: external` and `files: []`. Include public source/video links and accurate backend dependencies when available. |
| A production browser build that works completely within the built-in sandbox and its upload limits | Use `hosting_mode: static` after checking the actual build. Upload only those public build files. |
| No working demo is available and the participant chooses to submit with that limitation | Use `hosting_mode: none` and `files: []`; describe exactly what exists and what judges can inspect. |

An upload-limit error calls for a hosting decision, not a weaker project. If external deployment is needed, explain its account, service, permission, or cost requirements and get the participant's authorization before making those changes. Do not invent a demo URL, silently switch to no-demo mode, or treat a failed upload as a reason to discard work. Do not change an existing saved draft's hosting mode by silently creating another draft; explain the necessary replacement and retain its identifiers for recovery.

## Connect the assistant once

Use the client-specific connection below. Do not request infrastructure credentials, copy an API key, or ask the participant to create a Cloudflare account. Reuse an existing Maximizing Potential connection when it already points to this endpoint. Do not overwrite a different server with the same name without checking.

**ChatGPT**

On ChatGPT web, open [Plugins](https://chatgpt.com/plugins), select **+**, then **Add custom MCP server**. Name the plugin **Maximizing Potential**, enter `https://home.maximizingpotential.workers.dev/mcp` as its server URL, and choose **OAuth** with dynamic client registration (DCR), if the client asks for that choice. This server supports public-client S256 PKCE with no client secret; do not select CIMD or invent credentials. Review the client's disclosures, create and install the plugin, and complete Maximizing Potential sign-in and **Connect assistant**. In the conversation, type **@** and select the installed plugin. Account and workspace permissions can restrict custom MCP connections. A link to ChatGPT does not itself connect or install anything.

For an ordinary ChatGPT conversation, prefer a working external HTTPS demo link (`hosting_mode: external`, `files: []`) or accurately described project details without a demo (`hosting_mode: none`, `files: []`). Ask for missing facts, including a participant-supplied team name and contact email where required. Call `get_participant_profile` and `list_events`, then `prepare_submission` using a saved UUID request ID. Read the returned draft's `approval_url` and give it to the participant. There is no build, manifest, or terminal upload step for these two hosting modes.

If the plugin is unavailable, help prepare the project text and keep the selected event and track IDs. State clearly that this session has not saved new changes; previously saved work may still exist in My submissions. Offer to continue with connected Claude Code or Codex using that text and any existing draft ID. Do not invent tool results, scrape authenticated pages, copy browser tokens, or use an unapproved publication route. ChatGPT can only use the static-upload workflow when its actual environment has access to the files and can build, inspect, hash, and upload them; a pasted description or screenshot is insufficient.

**Claude Code on the web**

Cloud sessions at `claude.ai/code` use account connectors. Local `claude mcp add` or `claude mcp login` commands on a computer do not configure that cloud session.

1. Open [Claude connectors](https://claude.ai/customize/connectors) and add a custom web connector named **Maximizing Potential**, with URL `https://home.maximizingpotential.workers.dev/mcp`.
2. Use **OAuth** and, if asked how to identify the client, **Register automatically** (dynamic client registration). This server requires public-client S256 PKCE and supports DCR, not Claude's published identity/CIMD or a manually invented client secret.
3. Sign in to your own Maximizing Potential account, select **Connect assistant**, and enable the connector for the Claude Code session. Organization settings may require an owner to allow custom connectors.
4. Ask Claude to actually call `get_participant_profile` and `list_events`. Tool discovery/search may be needed first. If the tools remain absent, reconnect the connector in Claude's connector settings and reopen the session. If a new session is needed, use the same project/repository and branch and retain the event ID, track ID, existing draft ID, request ID, and private receipt. Keep credentials out of handoff text and Git.

Check direct network access separately. MCP connector requests pass through Anthropic's servers; a blocked terminal download does not prove the connector is disconnected. The terminal still needs access to this site's guide, upload helper, and upload endpoints. If those requests are blocked, open the session title menu, choose **Edit cloud environment**, then **Network access**. Under **Custom**, add only `home.maximizingpotential.workers.dev` to **Allowed domains**, retaining any existing project domains and common package-manager access you need. Save, wait about a minute, and retry the failed request. A network-only change does not require a new session. Do not request unrestricted network access or work around an organization restriction.

For the final hosted-app check, add `mp-project-apps.maximizingpotential.workers.dev` if the cloud environment blocks that returned URL. For an external demo, request access only to its specific host when needed.

If cloud tools or direct uploads remain unavailable, preserve the project files, repository/branch, selected event/track, and any existing draft details for a local Claude Code or Codex handoff. Recover existing saved work before preparing a new draft. Regular Claude chat uses a custom connector too, but file access and upload capabilities must be verified in that actual environment.

**Claude Code on your computer and Codex**

Use the supported MCP commands rather than editing configuration files. Inspect existing configuration before adding a duplicate connection.

**Codex**

```sh
codex mcp add maximizing-potential --url https://home.maximizingpotential.workers.dev/mcp
codex mcp login maximizing-potential
```

**Claude Code on your computer**

```sh
claude mcp add --transport http maximizing-potential https://home.maximizingpotential.workers.dev/mcp
claude mcp login maximizing-potential
```

If an older Claude Code version lacks `mcp login`, open `/mcp` in the interactive session, select Maximizing Potential, and authenticate. If a newly added server is not visible in the current assistant session, reconnect or restart that session as its client requires, then continue the same project. Do not report connection as complete merely because configuration was added.

Confirm that the current session successfully calls `get_participant_profile` and `list_events` before preparing a draft. A site sign-in, a configured connector, or a participant saying they clicked a button is not evidence that these tools work or that a project was submitted. If tools are missing, stop submission operations and give the setup steps for that environment; do not keep retrying unavailable tools. Distinguish work saved earlier from actions this session could not perform. If the assistant's command is not installed or its configuration is managed by an organization, show the client-specific setup step instead of requesting a site API key. Preserve the selected event and existing draft when reopening a session.

Use the current MCP tool list. If an existing connection does not yet expose a tool named in this guide, such as `refresh_upload`, refresh or reconnect that MCP connection before continuing. In local Claude Code, open `/mcp`, select Maximizing Potential, and choose its reconnect action. In Claude Code on the web, reconnect through Claude's connector settings and reopen the session. In Codex, reopen the project session if the active tools do not refresh. Reuse the saved draft; missing or stale tools are not a reason to create a second submission.

The browser opens Maximizing Potential sign-in or account creation, followed by **Connect assistant**. The OAuth connection has the `drafts:write` and `submissions:read` scopes: it can prepare this participant's private drafts and uploads and read progress. It cannot approve publication. Authentication and the assistant's own tool permissions may require additional interactions; do not promise one total click or bypass them. Passwords, OAuth tokens, and upload capabilities stay in private client storage and must never appear in the project, prompt, repository, logs, or a public URL.

## Prepare without publishing

1. Use the MCP discovery tools to read the authenticated participant profile and current events, tracks, and resources. Use the exact event from the prompt and its current `submission_open` and deadline values. Never infer that submissions closed from the calendar date or event name. The built-in hosting limits are documented below; `list_events` does not return those limits. An account profile contains participant-entered identity; it is not verified event registration. Prefill known contact and display-name fields only where appropriate. Never invent an email, teammate, registration, partner, or measured impact.
2. Inspect the project's source, README, build instructions, and functioning features. Prepare an accurate title, summary, description, technologies, community benefit, and public team name. Ask for the names of everyone who worked on the project, including the creator of a solo project, as they want to be credited publicly. Save these participant-supplied names in `participant_names`; do not infer them from the account profile, team name, repository, or email address. Participants can edit the list on the review page before publication. Explain prototype limitations. Include existing public HTTPS demo, repository, and video URLs only when available. Exclude private repository URLs and credentials.
3. Select one likely primary organization track from **that event's current configuration**, using its supplied challenge descriptions and resources. Tell the participant the reasoning briefly. If a description is missing or no choice is supported by the evidence, collect the track choice with all other genuinely missing information in one concise question. Do not infer an organization from another event. A pending organization is not a selectable track. Additional descriptive tags do not create duplicate entries.
4. Apply the hosting decision above to the actual project before creating a manifest or draft. Keep a working external demo when that preserves the app. Our optional built-in host serves browser files; it does not execute server code, SSR, databases, background processes, or authentication backends, and its sandbox does not provide service workers, localStorage/IndexedDB, cookies, camera, microphone, or geolocation. A compatible external API can support a static frontend only when the full workflow actually works under those constraints. Otherwise use a working external demo and describe its dependencies. Do not strip capabilities to make a static upload possible.
5. For static hosting only, produce a dedicated build directory containing `index.html` and relative assets. For example, use Vite `base: './'`. Inspect and test the production build's complete core workflow, including relevant reload, persistence, sign-in, failure, and accessibility behavior. The app runs in a sandbox with an opaque origin and no browser storage or cookies; an external HTTPS API must intentionally support those access constraints. Never upload the source repository, `.env`, server secrets, personal data, `node_modules`, or `.git`. This optional upload route allows 200 built files, 4 MiB per file, and 10 MiB total decoded files. If the build exceeds these limits, preserve the app and use external hosting; do not remove functionality to fit. Inspect all public files for secrets. Only upload material the participant may publish.
6. **Static hosting only:** read and inspect `/submit-project.mjs` before using it. This maintained helper creates a manifest and resumes uploads; it has no power to approve publication. Run `node submit-project.mjs manifest ./build-directory` to obtain the public file manifest, containing `path`, `size`, and SHA-256 for every file. Pass that manifest to the MCP `prepare_submission` tool with a new saved UUID `request_id` and metadata. An interrupted retry must reuse the same UUID and exact contents. Never create another entry merely because a response timed out.

Metadata fields:

- Required for new approval: `event_id`, `track_id`, `title` (120 characters), `summary` (300), `description` (8,000), `team_name` (120), `participant_names` (1–50 names, each at most 120 characters), `contact_email` (254), `impact` (3,000). The title, short summary, challenge, team name, and approved participant names form the required public summary. The contact email stays private. Description and impact are for judging and only become public if the participant explicitly chooses that option during review.
- Optional judging details: `technology` (1,000); HTTPS `demo_url`, `repo_url`, `video_url` (2,048 each); `tags` (array of descriptive strings); `backend_dependency` (plain-text explanation, without credentials). These fields stay off the public page unless the participant selects extra public details. Links must be safe for judges to open without shared credentials; the destination host controls access. Public source code and an open-source license are not required.
- `hosting_mode`: `static`, `external`, or `none`.
- For changes to an already published project, set `replaces_project_id` to its saved project ID. It must belong to this participant and event. The new approval screen identifies the replacement; publication atomically withdraws the previous entry and app, so only the new version remains active. Never omit this field when updating an existing submission.
- `files`: the exact build manifest for static hosting; an empty array otherwise.
- A draft may temporarily have `track_id: null` while a choice or organizer setup is missing. Approval requires an active track belonging to the selected event; never fill a placeholder track ID.
- A draft may omit `participant_names` or use an empty array while the participant collects the names. New approval requires at least one supplied name. Do not invent names to complete this field. Already-approved legacy submissions retain their existing recovery path.

Example request shape for an externally hosted project:

```json
{
  "request_id": "<saved UUID>",
  "metadata": {
    "event_id": "<event from the prompt>",
    "track_id": "<configured primary track>",
    "title": "<accurate project title>",
    "summary": "<accurate summary>",
    "description": "<what actually works and its limitations>",
    "team_name": "<public team name>",
    "participant_names": ["<name each participant wants credited publicly>"],
    "contact_email": "<private contact email>",
    "impact": "<intended benefit and any supported evidence>",
    "technology": "<actual tools>",
    "tags": [],
    "hosting_mode": "external",
    "demo_url": "<verified public HTTPS URL of the working app>",
    "backend_dependency": "<actual hosting and service dependencies, without credentials>"
  },
  "files": []
}
```

The example contains placeholders; use real values. For compatible built-in hosting, set `hosting_mode: static` and supply the helper's exact computed `files` manifest instead. Do not submit either example as a test record in a real event.

## Upload, review, and resume

For `external` and `none` hosting, skip file upload and give the participant the returned review URL. The remaining upload instructions apply only to static builds. An assistant without a terminal can use `upload_chunk` through MCP only when it can calculate real hashes and send the exact actual file bytes; do not fabricate a manifest.

For a static draft, `prepare_submission` provides a narrowly scoped, expiring upload capability. External and no-demo drafts skip uploading even if the response includes an unused upload field. Save the tool's result object (the object containing `id`, `revision`, `files`, and `upload`, not the surrounding MCP JSON-RPC or `content` wrapper) as a private mode-0600 `.mp-submission-receipt.json`, excluded from version control. Keep the original request ID and exact request payload privately with it so an interrupted preparation can be retried unchanged. The upload token is limited to the current draft revision and upload operations; it cannot authorize publication. Do not place it in shell arguments, environment printouts, or tool commentary.

Run:

```sh
node submit-project.mjs upload .mp-submission-receipt.json ./build-directory
```

The helper checks file hashes, uploads resumable 64-KiB chunks, and finalizes the saved manifest. Repeating the command safely replays the same chunks into the same draft; identical chunks do not create duplicate files or projects. It retries temporary failures at most five times per request, including non-JSON service errors, and respects `Retry-After`. If the server requests more than two minutes, it stops with the required wait instead of retrying early. The MCP `finalize_upload` tool accepts `{ "draft_id": "<saved draft ID>", "revision": "<saved revision>" }` when finalization needs retrying. Use `get_submission_status` with the same `draft_id` to check progress. If the upload capability expires or the private receipt is lost, call `refresh_upload` with `{ "draft_id": "<existing draft ID>" }` through the authenticated assistant. Save its returned draft/receipt object privately, replacing the expired receipt, then rerun the helper against the exact same build. This rotates the old upload capability and does not change the draft, approve it, or create a new submission. It is available only for the participant's own unapproved static draft while submissions remain open. Never ask the participant to copy a token from the browser. Follow the tool's current schema and actionable errors.

Open the returned review URL on Maximizing Potential after the static upload is ready. The participant sees the event, challenge, required public summary, private judging details, private contact field, and prepared browser-file manifest. They explicitly accept the current User Agreement and Terms of Service, judging permission, public-summary permission, and contributor authorization. Extra public details and public demo hosting are separate, initially unchecked choices. For a compatible browser build, recommend hosting the demo on Maximizing Potential, while keeping the participant in control. Hosting permission includes an automatically generated screenshot after publication; do not claim that an exact screenshot is previewed first. The participant may correct details and make these choices before selecting **Allow and submit**. Never click that button, synthesize its browser request, or approve on the participant's behalf. Connection consent, a copied prompt, and an assistant tool permission are not publication approval.

Approval binds the actual metadata, file manifest, User Agreement and Terms of Service versions, and sharing choices to that draft revision. Never choose permissions for the participant, infer consent from an earlier revision, or expand saved permissions during a retry. Preparing or uploading a static build does not authorize public hosting. Without hosting permission, those files remain off the public site. Without extra-details permission, judging text and links remain off the public page. People can share the public page link; submission does not transfer ownership, require open-source licensing, or authorize sponsor commercialization, AI training, or separate promotion. Material changes require a fresh review and approval. Do not silently alter approved files or public details. If the review is interrupted, return to the same saved review URL. Approved work can resume on that page or through supported status/resume tools; it must not create duplicate projects or judge assignments.

If the review link or assistant session is lost, the participant can sign in to [My submissions](https://home.maximizingpotential.workers.dev/projects/mine/) with the same account and open the existing project or draft. Recover that draft's ID and status before preparing anything new. For a missing receipt, the connected assistant can use `refresh_upload` with that ID as described above; the browser account page never exposes upload credentials. A missing local build must still be recovered or reproduced exactly against the saved file hashes. For a deliberate update to a published project, identify that entry and use `replaces_project_id` as described above.

## Verify and report the real result

Check each status separately:

- **Publication**: only call the project public after the public URL loads successfully.
- **App hosting**: only call the app hosted here after its hosted URL loads and its main interaction works. An external demo link or a staged upload is not a hosted app.
- **Judging assignments**: report assigned coverage, pending coverage, or organizer attention exactly as returned. A queue entry does not guarantee an eligible judge, completed review, score, prize, or event registration.

The system creates assignments using explicit event/track judge membership, workload, and conflicts. The assistant does not choose judges or grant judging access. If no eligible judge or configured review coverage exists, report organizer attention instead of claiming completion of judging assignments.

For temporary network or 5xx failures, retry the same saved operation with backoff. Honor 429 and its retry interval. Validation, authorization, closed-event, and conflict errors need the stated correction; do not repeatedly post unchanged invalid data. Retain the private receipt so a timeout cannot cause duplicate publication. An event freeze prevents updates; withdrawal and moderation remove public availability and active eligibility consistently with organizer rules. The participant can manage removal from the saved review/status page. Before results are finalized, withdrawal removes the gallery entry, hosted app, and screenshot from public view and ends active judging, which may prevent an award. After results, the Remove public showcase action preserves completed judging results and earned awards. Necessary organizer records and copies previously shared by others may remain. For privacy accommodations, direct participants to maximizing.potential.admin@gmail.com before submission or withdrawal; do not promise automatic private entry.

Finish with the actual public URL, hosted or external demo URL, the three statuses, backend dependencies, and any required organizer action. Keep contact information, credentials, private receipts, and judging records out of the response's public assets.

## Maintained integration references

The command-line clients' official documentation is authoritative for their own authentication and permission UI. Maximizing Potential's MCP tool schemas and this guide define the submission workflow. The public submission page links here so technical instructions can evolve without lengthening the participant prompt.

Official references: [ChatGPT custom MCP setup](https://developers.openai.com/api/docs/guides/custom-mcp-server), [Codex MCP setup and OAuth](https://developers.openai.com/codex/mcp), [Claude Code HTTP MCP setup and authentication](https://code.claude.com/docs/en/mcp), [Claude custom web connectors](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp), [Claude cloud network access](https://code.claude.com/docs/en/cloud-environments#network-access).