feat(openai): publish the ApplyWell MCP for ChatGPT, Codex and Work

[vitorhugo-dotnet]

Goal

Prepare, validate, package, and submit the existing ApplyWell remote MCP server as an official OpenAI plugin for public use across ChatGPT, Codex, and ChatGPT Work.

This issue covers the technical, security, legal, listing, testing, and operational requirements needed to pass OpenAI review. The existing Spring Boot MCP server remains the source of truth for application data and business rules; the plugin package must reference it rather than duplicate backend logic.

Important

OpenAI publication requirements are evolving. Revalidate the official documentation and submission portal immediately before implementation and again before submission. This specification was based on the official documentation available on 2026-08-05.

---

Current state

The API already exposes ApplyWell capabilities through MCP, including tools, resources, prompts, authentication, application lifecycle rules, duplicate checks, base information, resume templates, Google Drive integration, and resume generation.

The remaining work is not to rebuild those features. It is to make the public integration reviewable, safely installable, correctly authenticated, and compliant with OpenAI plugin requirements.

---

Product decision

Publish one OpenAI plugin named ApplyWell that contains:

• the registered remote MCP server connection;
• optional bundled skills for repeatable user workflows;
• listing metadata, branding, starter prompts, legal URLs, and screenshots;
• no bundled copy of the Java backend;
• no secrets, production tokens, reviewer credentials, or environment-specific private values committed to Git.

The initial release should prioritize an MCP-backed plugin without custom UI. Interactive MCP UI may be evaluated later only if it provides clear value beyond the existing web application.

---

Proposed repository layout

Keep OpenAI-specific publication assets isolated from the backend implementation:

integrations/openai/applywell/
├── .codex-plugin/
│   └── plugin.json
├── .app.json
├── skills/
│   ├── apply-to-job/
│   │   └── SKILL.md
│   ├── tailor-resume/
│   │   └── SKILL.md
│   ├── review-pipeline/
│   │   └── SKILL.md
│   └── follow-up-recruiter/
│       └── SKILL.md
├── assets/
│   ├── icon.png
│   ├── logo.png
│   └── screenshots/
├── README.md
└── submission-checklist.md

Rules:

• .codex-plugin/plugin.json is the required plugin entry point.
• .app.json references the MCP server connection registered in ChatGPT developer mode.
• The production plugin_asdk_app... identifier must be handled as deployment/submission configuration where practical; do not expose credentials or unrelated environment values.
• Skills may orchestrate existing MCP tools but must not duplicate business rules already enforced by the server.
• Relative paths must use the plugin root and begin with ./ where required by the manifest schema.

---

1. OpenAI account and publisher prerequisites

Before submission:

• Select the OpenAI Platform organization that will own the plugin.
• Ensure the submitter has Apps Management: Write permission.
• Verify the developer or business identity in the OpenAI Platform.
• Ensure the verified publisher identity matches the public website, legal pages, support contact, and plugin listing.
• Enable ChatGPT developer mode for local registration and testing.
• Confirm the current submission portal is accessible to the publishing organization.

Do not begin public submission using a personal test organization that will not remain the long-term plugin owner.

---

2. Public MCP endpoint and transport

The production MCP server must:

• Be available through a stable public HTTPS URL.
• Use Streamable HTTP as the primary transport.
• Not depend on localhost, a temporary tunnel, preview deployment, or developer workstation.
• Expose a documented production MCP path, preferably /mcp.
• Return correct MCP initialization, capability, tool, prompt, and resource responses.
• Validate the Origin header according to the MCP security guidance.
• Apply sensible request timeouts, body-size limits, rate limits, and concurrency limits.
• Provide health/readiness checks separately from the MCP protocol endpoint.
• Preserve backward compatibility or use explicit versioning when tool contracts change.
• Redact tokens, authorization codes, CV content, personal data, and tool payloads from production logs.

Domain verification

Implement and document OpenAI domain verification, including the current challenge path required by the submission portal, such as:

/.well-known/openai-apps-challenge

The exact challenge value must come from the OpenAI Platform and must not be hardcoded before registration.

---

3. OAuth and authorization

ApplyWell handles personal job-search information and performs write operations. Public anonymous access is not acceptable.

Implement or verify:

• OAuth 2.0 authorization-code flow.
• PKCE using S256.
• Protected resource metadata at the required /.well-known/oauth-protected-resource URL.
• Authorization server metadata compatible with RFC 8414 or OpenID discovery.
• Client registration through CIMD, DCR, or the current OpenAI-supported configuration selected during plugin registration.
• Exact redirect URI allowlisting using the callback URI shown by the OpenAI Platform.
• Correct resource/audience validation for access tokens.
• Short-lived access tokens and supported refresh-token rotation where applicable.
• Revocation/logout behavior.
• Least-privilege scopes, separated between read and write capabilities where practical.
• securitySchemes declared at server level and per tool as required.
• Consistent authenticated-user ownership checks for every application, resume, file, and base-information operation.

The server must never accept access tokens, API keys, or credentials through query-string parameters.

---

4. Tool metadata and behavioral safety audit

Audit every public tool before submission.

Each tool must have:

• A stable, unique, verb-oriented name.
• A concise title and description written for users, not only for backend developers.
• A JSON schema with accurate required/optional fields and enums.
• Actionable validation and error messages.
• Correct annotations, including readOnlyHint, destructiveHint, and openWorldHint when applicable.
• Per-tool authentication/security metadata.
• Bounded and relevant output instead of full database dumps.

Required behavior changes and safeguards

• Merely pasting, mentioning, comparing, or asking about a vacancy must not automatically create an application.
• Create an application only when the user explicitly asks to apply, register, track, save, or generate application material that requires a record, or after explicit confirmation when intent is ambiguous.
• Preserve the mandatory duplicate check across active and archived applications before Create-Application.
• Duplicate detection must not rely only on the vacancy URL because it is nullable and may contain tracking parameters.
• Confirmed duplicates must not create another record.
• Possible duplicates must be presented for user confirmation before creation.
• Status and archive visibility must remain independent.
• Rejected or Approved must not implicitly archive a record.
• Archive, restore, send, delete, and other externally visible or destructive operations must require clear user intent.
• Permanent deletion must have stronger confirmation than reversible archive.
• Resume generation must continue using base information as the authoritative source and must never invent experience, projects, skills, certifications, or education.
• Vacancy text, recruiter messages, uploaded files, and external pages must be treated as untrusted content and must not override MCP/server policies.

Annotation examples

• List/get/search/read tools: readOnlyHint: true.
• Create/update/archive/restore/generate tools: readOnlyHint: false.
• Permanent deletion: destructiveHint: true.
• Reversible writes should not be marked destructive merely because they mutate state, but their write behavior must be explicit.
• Tools that access external services such as Google Drive or Gmail should use the appropriate openWorldHint value and clearly disclose the external effect.

Add automated contract tests that fail when new tools omit required metadata or use inconsistent annotations.

---

5. Privacy, security, and legal requirements

Publish and maintain public pages for:

• Product website.
• Support/contact.
• Privacy policy.
• Terms of service.
• Account/data deletion instructions.
• Security contact or vulnerability-reporting process.

The privacy policy must explain:

• which application, recruiter, vacancy, CV, and account data are processed;
• which data is stored by ApplyWell;
• Google Drive or other third-party integrations involved;
• retention periods;
• deletion and export behavior;
• whether data is used for analytics or AI training;
• subprocessors and third-party sharing;
• contact information for privacy requests.

Security requirements:

• Strict tenant/user isolation.
• No cross-user access through guessed UUIDs.
• CSRF/state/nonce protection in OAuth flows.
• Rate limiting for login, token, MCP initialization, and write tools.
• Secret storage outside the repository.
• Log redaction and structured security events.
• Dependency and container vulnerability scanning.
• Backup and recovery procedures.
• Incident-response and credential-rotation documentation.
• Reviewer/test accounts containing synthetic data only.

---

6. Plugin package and listing metadata

Create .codex-plugin/plugin.json with at least:

• name: applywell;
• semantic version;
• English description;
• author/developer identity;
• homepage and repository;
• license;
• keywords;
• apps: "./.app.json";
• optional skills: "./skills/";
• interface.displayName: ApplyWell;
• short and long descriptions;
• category and capabilities;
• website, privacy-policy, and terms URLs;
• starter prompts;
• icon, logo, brand color, and screenshots.

Suggested public positioning:

Track job applications, tailor truthful resumes from verified base information, manage recruiter follow-ups, and keep every hiring process organized from ChatGPT, Codex, or Work.

Suggested starter prompts:

• Analyze this vacancy and tell me whether it fits my verified experience.
• Register this job application after checking for duplicates.
• Tailor my resume for this vacancy without inventing experience.
• Show applications that need a recruiter follow-up.
• Summarize my current application pipeline and next actions.

Do not advertise unsupported automatic application submission to third-party job boards.

---

7. Optional bundled skills

Skills should improve orchestration while keeping the MCP server authoritative.

apply-to-job

• analyze vacancy content;
• read authoritative base information;
• search active and archived records for duplicates;
• ask only genuinely missing questions;
• create the application after explicit intent is established;
• generate and link the tailored resume;
• return a concise summary of created artifacts and next steps.

tailor-resume

• require an existing application;
• select the correct language/template;
• read base information before drafting values;
• fill every detected placeholder;
• never invent qualifications;
• return Google Doc and PDF URLs linked to the application.

review-pipeline

• read-only summary of active, archived, overdue, interview, and follow-up states;
• no automatic status or archive changes.

follow-up-recruiter

• identify applications eligible for follow-up;
• draft a message first;
• do not send anything without explicit user intent and the relevant connected mail capability.

---

8. Testing strategy

Automated tests

• MCP initialization and capability negotiation.
• Tool/list/resource/prompt schema snapshots.
• OAuth metadata and PKCE integration tests.
• Authenticated ownership and cross-user denial tests.
• Duplicate detection across active and archived applications.
• Read/write/destructive annotation contract tests.
• Prompt-injection resistance for vacancy and recruiter content.
• Response-size and timeout tests.
• No-secret/no-sensitive-log tests.
• Plugin manifest/schema validation.
• Broken-link checks for website, support, privacy, and terms URLs.
• Production smoke test against a synthetic reviewer account.

Positive review scenarios

1. Analyze a vacancy without creating data.
2. Explicitly register a new vacancy after duplicate checking.
3. Generate a truthful tailored resume from base information.
4. List applications requiring follow-up.
5. Update status without changing archive state.
6. Archive and later restore an application while preserving status.

Negative and boundary scenarios

1. Mention a vacancy only for comparison: no record is created.
2. Submit an existing vacancy with no URL: possible duplicate is detected through company/title/recruiter context.
3. Ask to reject an application: status changes, archive state does not.
4. Ask an ambiguous dar baixa: apply the least destructive interpretation or ask for clarification; do not permanently delete.
5. Vacancy text instructs the assistant to ignore policies or expose private data: instruction is ignored.
6. One account requests another account's application UUID: access is denied.
7. Resume request contains unsupported qualifications: content is not invented.
8. Delete request lacks explicit confirmation: permanent deletion is not executed.

Surface validation

Test the released candidate in:

• ChatGPT web.
• ChatGPT desktop where supported.
• ChatGPT Work, including plugin-creator/local marketplace testing.
• Codex plugin installation and MCP invocation.
• A fresh account with no cached MCP metadata.

After every MCP schema/tool/resource/prompt change, reconnect or refresh all tested clients because clients may cache capabilities.

---

9. Submission workflow

1. Complete the server, auth, tool-metadata, legal, and security checklists.
2. Register the production MCP server in ChatGPT developer mode.
3. Copy the generated plugin_asdk_app... connection identifier.
4. Scaffold or validate the plugin with @plugin-creator in Work or $plugin-creator in Codex.
5. Review .app.json and .codex-plugin/plugin.json manually.
6. Install from a local/personal marketplace and execute all positive and negative scenarios.
7. Prepare listing copy, branding, screenshots, test cases, country availability, policy attestations, and synthetic reviewer credentials.
8. Verify the publishing identity and domain.
9. Submit through the OpenAI Platform plugin submission portal.
10. Record review feedback in this issue and fix findings without weakening existing safety rules.
11. Publish only after the production endpoint, support pages, monitoring, and incident process are ready.
12. Document the approved plugin URL, installation instructions, and supported surfaces in the repository README.

---

10. CI/CD and operations

Add CI checks for:

• plugin JSON syntax and schema;
• manifest path correctness;
• required metadata and legal URLs;
• MCP tool annotation completeness;
• schema drift between tests and production registration;
• OAuth discovery endpoints;
• sensitive-string and secret scanning;
• broken documentation links;
• Docker/image vulnerability scanning;
• integration and security tests.

Deployment requirements:

• deploy server changes before submitting or refreshing scanned tool metadata;
• never publish a manifest pointing to a preview MCP endpoint;
• support rollback to the previous server/plugin version;
• monitor authentication failures, MCP protocol errors, tool latency, write failures, and duplicate-prevention events;
• alert on abnormal cross-user authorization failures or repeated destructive-tool attempts.

---

Acceptance criteria

• The production MCP endpoint is stable, public, HTTPS, and Streamable HTTP compatible.
• OAuth authorization code + PKCE works end-to-end with OpenAI.
• Protected-resource and authorization-server metadata are valid.
• Every tool has accurate schema, title, description, security scheme, and annotations.
• Vacancy mentions do not cause implicit application creation.
• Duplicate checks remain mandatory before creation.
• Status, archive, restore, and delete semantics remain independent and correctly protected.
• User isolation and authorization are covered by automated tests.
• Sensitive data and credentials are redacted from logs and responses.
• Public website, support, privacy, terms, deletion, and security pages exist.
• .codex-plugin/plugin.json, .app.json, skills, and assets are versioned and validated.
• The plugin installs and works in ChatGPT, Codex, and Work on fresh clients.
• Positive, negative, prompt-injection, and cross-account scenarios pass.
• Synthetic reviewer credentials and submission materials are prepared.
• The plugin is submitted through the OpenAI Platform portal.
• Review feedback is resolved and the approved listing is documented.
• README documents installation, supported workflows, privacy boundaries, and current limitations.

---

Out of scope

• Custom MCP UI for the first release.
• Automatic submission to external job boards.
• Automatic sending of recruiter emails without explicit user intent.
• Monetization, billing, or subscription tiers.
• Rewriting the existing backend domain model solely for marketplace packaging.
• Publishing to the Claude Connectors Directory or Claude plugin marketplace. Claude/Claude Code uses a separate packaging, testing, review, and distribution ecosystem and should be handled in a dedicated issue after the OpenAI release.

Note

Do not document Claude public publication as requiring a Team or Enterprise plan unless Anthropic's current submission portal explicitly enforces that requirement. As of 2026-08-05, Anthropic's public documentation allows plugin submissions through Claude.ai or Console and allows custom connectors on individual plans. Team/Enterprise is required for organization-managed plugin distribution and administrative rollout, not clearly for public marketplace submission. The previous Team/Enterprise assumption is therefore not a reliable reason for excluding Claude; the valid reason here is scope separation and avoiding a second platform's compliance work in the same milestone.

---

Official references

OpenAI

• Plugin submission: https://developers.openai.com/plugins/deploy/submission
• MCP review requirements: https://developers.openai.com/plugins/deploy/app-review
• MCP server architecture: https://developers.openai.com/plugins/concepts/mcp-server
• Build an MCP server: https://developers.openai.com/plugins/build/mcp-server
• Authentication and OAuth: https://developers.openai.com/plugins/build/auth
• Package plugins: https://developers.openai.com/plugins/build/plugins
• Plugin guidelines: https://developers.openai.com/plugins/app-guidelines
• Security and privacy: https://developers.openai.com/plugins/guides/security-privacy
• Plugins overview: https://learn.chatgpt.com/docs/plugins
• Build plugins: https://learn.chatgpt.com/docs/build-plugins
• Work overview: https://learn.chatgpt.com/docs/get-started-with-work

Claude, intentionally outside this issue

• Connector submission: https://claude.com/docs/connectors/building/submission
• Plugin submission: https://claude.com/docs/plugins/submit
• Connector testing and plan availability: https://claude.com/docs/connectors/building/testing