JobMojito MCP Server

Welcome

JobMojito is an AI interview platform for hiring teams: let AI interview every candidate — you make the call. Lifelike avatar and voice agents run structured, multilingual interviews at any scale, score them in real time, and hand recruiters the transcripts, summaries and reports they need to make the actual decision. Everything the platform produces is decision support for a qualified human reviewer — never the hiring decision itself.

What the platform offers:

• AI avatar & voice interviews — real-time conversational interviews with configurable avatars, generated from a job description or built from your own question set, with a fully branded candidate experience.
• Scoring, transcripts & reports — consistent structured assessment with real-time scoring, plus shareable interview reports for the hiring team.
• Candidate management & invitations — register candidates in bulk, send each one a personal interview link, grant extra attempts, track results.
• Role-play & coaching personas — avatars that play a defined role, for screening scenarios or candidate practice on the coaching portal.
• Knowledge base — upload company documents so interviews and evaluations reflect your organisation's context.
• Workspaces & analytics — merchants and sub-merchants, credit usage, and hiring analytics across positions.

Around the product: the admin console at app.jobmojito.com, developer/API docs at developer.jobmojito.com, the help center at help.jobmojito.com, and the hosted MCP endpoint this repo powers at https://mcp.jobmojito.com/mcp.

This repository is the MCP server that puts all of that into AI assistants like Claude and ChatGPT.

An MCP server for the JobMojito API, built with FastMCP and designed to deploy on Prefect Horizon (the MCP platform from the FastMCP team — app.prefect.cloud → Horizon).

It exposes:

• 25 API tools auto-generated from JobMojito's live OpenAPI spec (interviews and role-play personas, the coaching catalogue, candidates and results, knowledge base, merchant lists/analytics). All endpoints — including the GET lists — are surfaced as tools with clean, curated names, each with a title and read-only/destructive annotations.
• 2 documentation tools (search_documentation, get_documentation) that read the developer docs and help center live — docs stay single-source on their existing platforms; nothing is copied into this repo.
• Supabase OAuth so end users can log in directly from Claude, ChatGPT, etc. The signed-in user's Supabase JWT is forwarded to the JobMojito API on every call.

How it fits together

MCP client (Claude / ChatGPT)
        │  OAuth login (Supabase OAuth Server, DCR)
        ▼
JobMojito MCP server (this repo, on Horizon)
        │  forwards the user's Supabase JWT
        ▼
JobMojito API  (https://cool.jobmojito.com/functions/v1)

Files

Local development & testing (macOS)

# 1. Set up a virtualenv and install deps
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# 2. Configure secrets in .env (auto-loaded; gitignored)
cp .env.example .env        # then fill in your keys/credentials

# 3. Static check — see exactly what Horizon will deploy
fastmcp inspect server.py:mcp

# 4. Run the unit tests (offline; uses the snapshot fallback)
ENABLE_AUTH=false pytest -q --asyncio-mode=auto

# 5. Smoke-test the docs tools live (Featurebase + Mintlify federation)
ENABLE_AUTH=false python scripts/try_docs.py "how do I create an interview"

# 6. Run the server and connect a client
ENABLE_AUTH=false python server.py        # → http://localhost:8000/mcp
#   then, in another terminal, open the MCP Inspector:
npx @modelcontextprotocol/inspector
#   transport: "Streamable HTTP", URL: http://localhost:8000/mcp

Testing notes:

• Docs tools (search_documentation, and the mounted Mintlify search_*_developer_* / query_docs_filesystem_*) work with ENABLE_AUTH=false — no Supabase login needed. scripts/try_docs.py is the fastest check.
• API tools (create_interview, list_candidates, …) call the real JobMojito API and need a Supabase user token. For local testing, set JOBMOJITO_DEV_BEARER_TOKEN in .env to a valid Supabase access token; it's forwarded when ENABLE_AUTH=false. (Never set this in production — there the token comes from the user's OAuth session.)
• Full OAuth locally is rarely needed; if you want it, run with ENABLE_AUTH=true, set BASE_URL=http://localhost:8000, and connect a client that supports OAuth (it will bounce you through Supabase).

Refresh the fallback snapshot from a network that can reach the API: python scripts/update_snapshot.py (the committed snapshot in this repo is a thin structural fallback; this replaces it with the full live spec).

Supabase OAuth setup

This server uses Supabase's OAuth Server feature (which supports Dynamic Client Registration, so MCP clients self-register). The MCP server is the OAuth resource server — it validates tokens; Supabase issues them.

Project: https://momsbvnltsydezmoesqt.supabase.co SupabaseProvider derives every endpoint from this project URL:

Steps:

1. Supabase Dashboard → Authentication → OAuth Server
   • Enable the OAuth Server and Allow Dynamic OAuth Apps
   • Site URL: https://app.jobmojito.com
   • Authorization Path: /oauth/consent
2. Env: SUPABASE_PROJECT_URL=https://momsbvnltsydezmoesqt.supabase.co, BASE_URL=https://mcp.jobmojito.com (public base, no /mcp), SUPABASE_JWT_ALGORITHM=ES256 (switch to RS256 if your JWKS shows RSA keys).
3. If the JobMojito Edge Functions require an apikey header, set SUPABASE_ANON_KEY.

Consent is handled by Supabase / your app, not this server. Because the Site URL is app.jobmojito.com, Supabase serves the approve/deny screen at https://app.jobmojito.com/oauth/consent, where the user already has a Supabase session. This MCP server is only the OAuth resource server — it does not serve a consent page. SITE_URL and OAUTH_CONSENT_PATH are informational and should match your Supabase OAuth Server settings.

Token note: SupabaseProvider cannot validate token audience (Supabase Auth doesn't implement RFC 8707 resource indicators yet). This is expected and logged at startup.

Authentication model

Every tool call requires the user to be signed in via Supabase OAuth — including search_documentation and get_documentation. Keep ENABLE_AUTH=true; the signed-in user's token is forwarded to the JobMojito API so calls respect that user's permissions.

The one deliberate exception is capability discovery: with ENABLE_LAZY_AUTH (default true), initialize, ping and the */list methods answer without a token so directory crawlers can render the tool list. No data is reachable that way — every tools/call, resource read and prompt still needs a verified JWT.

Deploy to Prefect Horizon