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, spend their own coaching credits, 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:

• 27 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). 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

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.
4. 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.
5. 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 /oauth/consent; and that consent page hosted on the app.

Because the OpenAPI spec is fetched live at startup, each redeploy picks up the latest JobMojito API automatically.

Keeping documentation single-source

Docs are not duplicated here. search_documentation builds a live index and get_documentation fetches a page on demand, both reading the source platforms directly. Edit docs there and the MCP reflects changes within the cache TTL (DOCS_CACHE_TTL_MINUTES, default 60).

Why this server and Mintlify

Mintlify imports the OpenAPI, but its MCP is read-only documentation — it lets an agent search and read the API reference. It cannot call the API. This server turns the same OpenAPI into authenticated, callable tools (acting as the signed-in Supabase user). So: Mintlify answers "how does it work?"; this server "does the thing." The federation mounts Mintlify's doc-search tools alongside the action tools so end users get both from one connector.

Developer docs: Mintlify federation

developer.jobmojito.com is a Mintlify site whose MCP exposes search + query_docs_filesystem tools (including the imported OpenAPI). This server mounts it as a proxy. When federated, the built-in developer-llms.txt source is disabled to avoid duplication.

Public by default (no credentials). Mintlify serves a public MCP at /mcp. Because the developer docs are public, DEVELOPER_DOCS_MCP_URL defaults to https://developer.jobmojito.com/mcp and is mounted with no auth — it works out of the box.

Authenticated endpoint (optional). Mintlify also offers an /authed/mcp endpoint with OAuth client-credentials, for group-restricted content. It is not enabled by default — the site's /.well-known/mcp only advertises a public server until you enable it. To use it:

1. Mintlify dashboard → MCP server page → Enable MCP Server (otherwise /authed/mcp/oauth/token returns 404).
2. Create a client credential there (MCP client credentials, not Mintlify API keys) → set DEVELOPER_DOCS_MCP_CLIENT_ID / _CLIENT_SECRET.
3. Set DEVELOPER_DOCS_MCP_URL=https://developer.jobmojito.com/authed/mcp.

Auth is attached only when the URL contains /authed and both credentials are set; the server then exchanges them at {url}/oauth/token and caches/refreshes the token.

Featurebase: which credential is which

Featurebase exposes docs three ways — the credential shape tells you which:

• REST API → a single API key (sent as Authorization: Bearer <key> and X-API-Key), base https://do.featurebase.app. Create it in the Featurebase dashboard: log in via auth.featurebase.app/choose-org → Settings → Advanced → API → copy the key. (The direct /settings/api URL 404s — you must enter through your org first.) This is what this server uses for the help center (set FEATUREBASE_API_KEY).
• Hosted MCP (mcp-read.featurebase.app, the Reader connector) → interactive OAuth (authorization code + PKCE, no client secret). Designed for a human to click "Connect" in Claude/ChatGPT. Best added directly as a connector in your AI client, not proxied from this server (there's no machine token / client-credentials grant).
• Public web → llms.txt / .md (developer docs), no auth.

A Client ID + Client secret pair is not a Featurebase docs credential — neither the REST API (API key) nor the MCP (PKCE, no secret) uses that shape. If you have one, it's likely a Featurebase SSO/identity OAuth app or from a different system. For docs, use the REST API key above.

Featurebase Reader MCP (not federated)

Unlike Mintlify, Featurebase's Reader MCP (mcp-read.featurebase.app) only supports interactive OAuth (no client-credentials), so it isn't mounted here. If you want its native search, add it directly as a connector in your AI client. HELP_DOCS_MCP_URL is kept in config for reference only.

Directory listings & discoverability

The server is built to satisfy the Anthropic connector directory, the OpenAI plugin directory (ChatGPT + Codex) and the official MCP Registry without further code changes. What that means in practice:

Generate the annotation justifications OpenAI asks for at submission:

python -c "import naming,json;print(json.dumps(naming.annotation_justifications(),indent=2))"

Verify the public identity after any deploy or hostname change — this is the single most common way an otherwise-healthy server 401s every client:

curl -s https://mcp.jobmojito.com/.well-known/oauth-protected-resource/mcp
# "resource" MUST equal "https://mcp.jobmojito.com/mcp"
curl -s https://mcp.jobmojito.com/healthz

Where it's listed

Still to do outside this repo

The code is ready; these are not code problems:

1. Allowlist Anthropic's egress range 160.79.104.0/21 on the MCP host and anything in front of Supabase. A blocking WAF is Anthropic's most common documented failure mode.
2. Cache-bypass at the CDN for /.well-known/*, llms.txt and *.md, and confirm nothing in front of the server buffers SSE.
3. Keep the reviewer test account usable. Both directories may re-test after listing; an account that runs out of credits fails in a way that looks like a broken server.