JobMojito

JobMojito MCP Server

Welcome

JobMojito runs AI-led conversational sessions in three shapes. The difference between them matters, because one tool builds two of them:

• Interviews — a scored Q&A for hiring. Generate the questions from a job description or supply your own; run them with a voice-only interviewer, a live video avatar or a pre-recorded one, in 30+ languages, with a fully branded candidate experience.
• Simulated personas — instead of a question list, the avatar plays a defined character in free-form conversation — a sceptical buyer, an angry customer, a difficult stakeholder — and the person is scored on how they handle it. Same invitation, billing and result flow as an interview, so these land in the recruiter's result list alongside everything else.
• Coaching — the same persona engine pointed at practice rather than assessment. Learners start sessions themselves from a browsable catalogue, pay per second from their own coaching minutes, and their results stay private from recruiters. Organise it with directories, tag filters and Markdown pages.

The one trap. create_persona builds both the second and the third product,

selected by its portal argument — and it defaults to `coaching`. For

anything used to assess or screen, pass portal="interview" explicitly, or you

silently get the wrong product: billed to the wrong credits and invisible to the

recruiter.

Across all three: register candidates in bulk and give each a personal link, upload documents to a knowledge base the AI draws on, read back transcripts, structured analysis and shareable HTML or PDF reports, and manage workspaces, credits and analytics across merchants and sub-merchants.

Everything the platform produces is decision support for a qualified human reviewer — never the hiring decision itself, and candidates are told AI is part of the process.

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:

• 39 API tools auto-generated from JobMojito's live OpenAPI spec (interviews, simulated personas and the coaching catalogue, candidates and results, knowledge base, merchant lists/analytics, custom reports, portal configuration). 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

1. 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).
2. 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

1. Push this repo to GitHub.
2. At horizon.prefect.io, sign in with GitHub and select this repo.
3. Configure:

• Entrypoint: server.py:mcp
• Dependencies: auto-detected from requirements.txt
• Horizon Authentication: off — this server provides its own Supabase OAuth, so let it be the auth layer.

1. Set environment variables / secrets:

• ENABLE_AUTH=true
• BASE_URL=https://mcp.jobmojito.com — critical. This must be the server's public base URL, with no `/mcp` and no trailing slash. It's what SupabaseProvider advertises as the OAuth resource; if it's left at the http://localhost:8000 default, clients get 401 invalid_token. The startup log prints base_url=… and warns if it's localhost.
• SUPABASE_PROJECT_URL=https://momsbvnltsydezmoesqt.supabase.co
• SUPABASE_ANON_KEY if the Edge Functions need the apikey header.
• FEATUREBASE_API_KEY for help-center docs.

1. Deploy. Your MCP endpoint is https://mcp.jobmojito.com/mcp. Horizon redeploys on every push to main.

Testing the login

A 401 on initialize is the normal first step of MCP OAuth — the client is meant to read the discovery metadata and run the Supabase login. Horizon's Inspector / ChatMCP do not perform that login, so they'll show a bare 401. Test by adding https://mcp.jobmojito.com/mcp as a custom connector in Claude.ai, which runs the full OAuth flow and prompts the Supabase login.

Make sure the Supabase side is configured (or the flow 401s regardless): OAuth Server enabled + Dynamic Client Registration on; Site URL https://app.jobmojito.com

• Authorization Path `/