Interview Prep MCP Server

An MCP server that lets Claude and ChatGPT share the same study-progress database for interview prep, coursework, and spaced repetition. The current architecture supports multiple authenticated subjects in one database, with each user's tools scoped to their own study data.

The product source of truth is interview_prep_mcp_prd.md.

What It Implements

• Study hierarchy: Study -> Topic -> Subtopic.

• Append-only quiz attempts with score, model notes, and optional question text.

• Subtopic state snapshots with mastery, ease factor, interval, next review date, and streak.

• Server-side SM-2 scheduling so LLM clients never calculate intervals.

• MCP tools for reads, writes, and hierarchy management.

• Public-safe MCP initialization instructions that guide clients through the review loop and data boundaries.

• MCP prompts for due reviews, study-plan creation, progress review, and account data requests.

• Postgres persistence for production and SQLite fallback for local development.

• Per-user data isolation using the authenticated token subject.

• Repo-local Codex plugin packaging for development and workspace installs.

Related MCP server: acheron-mcp-server

Local Setup

python3.11 -m venv .venv
. .venv/bin/activate
python -m pip install -e ".[dev]"

Run

interview-prep-mcp

By default the server uses stdio transport and stores data in data/interview_prep.sqlite3.

Useful environment variables:

Multi-User Architecture

The public-ready data model scopes all studies by owner_subject, and all topic, subtopic, attempt, and review-state access is validated through that owning study. MCP tools do not accept a user_id; hosted requests derive the subject from the OAuth or bearer token so clients cannot select another account by passing an id.

For public deployments, configure OIDC_ISSUER_URL and related OIDC settings so access tokens are issued by a real identity provider and each user gets a stable owner_subject.

The included OAuth approval-secret flow remains best suited to private or invite-only deployments.

Remote HTTP transports refuse to start without OAuth or bearer auth unless MCP_ALLOW_UNAUTHENTICATED_HTTP=true is explicitly set for non-public development.

Tools

The server exposes the PRD tool surface:

Prompts

The server also exposes MCP prompts for common workflows:

Test

python -m unittest discover -s tests

Before packaging or submitting a public release, run the combined local gate:

python3 scripts/release_check.py

To produce a shareable plugin archive for review or manual distribution:

python3 scripts/package_plugin.py

To produce a machine-readable OpenAI app submission packet:

python3 scripts/build_submission_packet.py

To produce a machine-readable MCP contract snapshot:

python3 scripts/build_mcp_contract_snapshot.py

To compare a previous reviewed snapshot against a new build:

python3 scripts/diff_mcp_contract.py previous-mcp-contract-snapshot.json dist/mcp-contract-snapshot.json

To update plugin distribution metadata when moving to a custom domain:

python3 scripts/manage_public_urls.py --base-url https://interview-prep.example.com --write --check

The same release gate runs in GitHub Actions on pull requests, pushes to main and public-facing-version, and manual workflow dispatch. The workflow uploads the plugin archive, OpenAI submission packet, MCP contract snapshot, and public launch docs as CI artifacts.

Deployment Notes

The PRD calls for one hosted remote MCP server reachable by Claude and ChatGPT. This repo supports that path through FastMCP and uses Postgres when DATABASE_URL is configured.

The included Dockerfile runs the server with MCP_TRANSPORT=streamable-http and binds to 0.0.0.0. SQLite remains available for local development or small single-volume deployments.

railway.json pins Railway deployment settings for the Dockerfile builder, /healthz platform healthcheck, and restart policy.

See docs/deployment.md for remote MCP URLs, OAuth, bearer-token auth, and client connection examples.

See docs/public-launch.md for the recommended public hosting, database, auth, OpenAI app submission, Claude connector, and Codex plugin plan.

See docs/public-auth.md, docs/oidc-provider-setup.md, and docs/production-env.example for the external OIDC provider contract, setup runbook, and production environment template.

The hosted service also serves public review/support pages:

• / for a product overview and MCP endpoint.

• /privacy for privacy disclosures.

• /terms for service terms.

• /support for contact and troubleshooting.

• /healthz for non-secret service health metadata.

See docs/openai-submission.md for app review metadata and test prompts.

After deploying, run the public endpoint verifier:

python3 scripts/release_check.py
python3 scripts/check_production_config.py
python3 scripts/verify_public_deployment.py https://your-app.example.com
MCP_AUTH_TOKEN=... python3 scripts/verify_authenticated_mcp.py https://your-app.example.com/mcp

To seed reviewer-safe demo data:

DATABASE_URL=... python3 scripts/seed_demo_data.py --subject reviewer-demo --with-attempts

Codex Plugin

This repo includes a Codex plugin bundle at plugins/interview-prep-mcp and a repo marketplace at .agents/plugins/marketplace.json. The plugin points Codex at the hosted Railway MCP endpoint and bundles a skill that guides study-review workflows.

If Codex does not discover the repo marketplace automatically, add it from the repo root:

codex plugin marketplace add .

For a shareable archive, run python3 scripts/package_plugin.py. The generated dist/interview-prep-mcp-<version>.plugin.zip contains the plugin manifest, MCP server config, skill, assets folder, and folder indexes.