Integrations

Connect AI Assistants (MCP)

Connect any MCP-compatible AI assistant — Claude, Claude Code, ChatGPT, Cursor, VS Code, and more — to your Flowmingo hiring data, and work your pipeline in plain language.

Integration Hub
API IntegrationWebhook IntegrationAI assistants (MCP)
Our team is online
Need help integrating?

Stuck on a step or need technical support? Our team is happy to help — reach out any time and we'll get you connected.

Email uscontact@flowmingo.aiWhatsAppChat with our team

Overview

Connect any MCP-compatible AI assistant to your Flowmingo hiring data — read your jobs and candidates and take guarded actions (invite, move, reject, remove from a project), securely, with your permission. With two extra permissions that you switch on yourself, an assistant can also create hiring projects and assessments and publish, close or boost a job post (see What you can do). New to MCP? It's the open standard that lets AI assistants talk to tools like Flowmingo. Learn what MCP is.

Transport: Streamable HTTP (the modern remote transport). There is no legacy SSE — always point your client at /mcp, never /sse.

Treat your API key like a password. Prefer OAuth, a prompted input, or an environment variable over pasting a raw fl_... key into a file you might commit to git (e.g. .vscode/mcp.json, ~/.cursor/mcp.json, your Continue config).

Authentication — two options

A — Sign in with Flowmingo (OAuth, recommended). Your browser opens a Flowmingo consent page; you paste your API key there. The assistant never receives your raw key. It receives an access token and a refresh token, which it can use to get a new access token. The sign-in does not last for ever. The refresh token lives about 30 days by default, counted from when it was issued, at sign-in or at the latest refresh, so a sign-in that goes unused for about that long lapses, and a Flowmingo release that changes how sign-ins are stored may also require you to sign in again. The assistant then asks you to sign in again, and you paste your key again. To cut it off sooner, delete that API key. There is no client ID or secret to create (Flowmingo uses Dynamic Client Registration). On clients that show "Advanced" OAuth settings (e.g. Claude.ai), leave the Client ID and Secret blank.

B — Static API key (header). Send your key as either header:

x-api-key: fl_YOUR_KEY

Authorization: Bearer fl_YOUR_KEY

Get your key in Flowmingo → Settings → Integrations → API Keys. Tick Read hiring data and Read candidates — the first covers jobs, pipeline and results, the second is what lets an assistant look someone up. Add Manage pipeline / Invite candidates for the guarded write actions. To let an assistant create projects and assessments and publish or boost a job post, also tick Create hiring projects and Create assessments. Read Create and publish under What you can do first: these two permissions are opt-in, and the key's creator must be an Owner or an Admin.

What a complete key looks like. One long value: fl_live_, the key's public name, a dot, then a long secret. The secret half is shown once, right after you create the key; later the API Keys list shows only the start of it. A value with no dot is only the key's name, and it will be refused. Wherever this guide writes fl_YOUR_KEY, replace all of it with your complete key, with no quotes and no spaces.

If it won't connect. A bad or empty key comes back as Missing credential or The Flowmingo API key was rejected; both can mean the value never reached us in full, so check the value first. A setting such as ${env:FLOWMINGO_API_KEY} only works if the program can see that variable, and an editor opened from the dock or the Start menu often does not read your terminal profile. Either start it from a terminal where the variable is set, or put your complete key in the file (and keep that file out of git).

Which to pick? Most clients support both; a few (e.g. ChatGPT) are OAuth-only — each tab notes what that client supports. In general, OAuth suits interactive assistants (Claude.ai, ChatGPT, VS Code); the API-key header suits CLIs, headless/CI, and editors where you'd rather drop in a key.

What you can do

Reads do not need approval. Most writes are guarded. An invite, a reject made with the Reject action, a removal of candidates from a project, a deletion of a project, or, normally, a move to a stage that is set to email the candidate waits for a person to approve it at a link, signed in to Flowmingo. The assistant cannot approve it, and a yes typed into the chat does not count. The stage's email setting is checked when the move is requested. For a note, a rating, a shortlist, a tag, or a move to a stage that is not set to email the candidate, the assistant is told to show you a preview first and to go ahead only when you agree, which is an instruction to it, not a lock. A prompt that your AI client shows before it runs a tool is the client's own and is not Flowmingo's approval: an invite, a reject made with the Reject action and a move to an emailing stage still wait for the approval link, whatever the client asked. An approval link lapses after 15 minutes, and one request for several candidates or applications (at most 50) is one approval that lists everyone. Once a change is staged, the assistant can check where it stands, withdraw it while it still waits, and undo a reversible change (a note, a rating, a shortlist mark, a tag, or a move that emailed nobody) within 24 hours. An undo is not always available: the change has to come back with an undo reference, recording one is best effort, and a move for a candidate with no earlier stage has none, so the assistant should check and say so when there is no way back. An email that has been sent cannot be undone. The tools listed under Create and publish are the exception to all of this, except delete_project: they act at once and are not staged for approval. A removal and a project deletion cannot be undone. Everything is scoped to your organisation.

Read

Capability What it does
Ask a question about your data (ask_data) Answers a question in plain words, for example "How many AI interviews were completed last week?", from your own hiring data, with a working that says how the answer was reached. Needs Read hiring data, and answers as the key's creator, from what they can open in Flowmingo (the API guide, section 5.11, says how a key behaves after its creator leaves). When Flowmingo cannot check, it says unavailable and never reports zero. An answer labelled exploratory comes from a query Flowmingo has not reviewed. Your company can ask 20 questions a minute and 1,000 a day. When it is offered, six capabilities below are normally hidden: Hiring overview, Top candidates, Compare candidates, Upcoming interviews, the list of your pipeline and the list of results (a read-only connection can find it hard to open the detail of one result, for example one that belongs to no project). The pipeline list stays for a session that can use a tool that moves, rejects or removes applications, and the results list for one that can use a tool that adds a note, a rating or a shortlist mark, because those actions need an id the lists carry. Which tools an assistant has is decided when it connects (switching asking off can change them during a session).
List job posts Browse your organisation's open and closed roles.
List interview sets & projects See your assessments (interview sets) of every kind (AI interviews, role-plays, Skill Tests, Technical Tests, CV evaluations, Showcases and recordings; questionnaires when you ask for them) and your hiring projects.
List your candidate pipeline View applications by stage across a project.
Read assessment results & scores Pull results of every kind: AI interviews, role-plays, Skill Tests, Technical Tests, CV evaluations, Showcases, recordings and questionnaires. Each result is labelled with its kind. Only some kinds carry an AI score: a Showcase and a questionnaire are never scored, and a Skill Test is a percentage.
Look up a candidate Fetch one candidate's name, email, and CV.
Search candidates Find candidates by name or email.
Compare candidates Line up 2 to 10 candidates side by side. Needs the Read candidates permission as well as Read hiring data.
Hiring overview The funnel for everything your connection can reach (the whole company, unless the key was made by someone limited to some projects), or narrowed when you ask: applications per stage, active vs rejected, and, for each kind of assessment that has results, completed vs in-progress results and the average score. A project narrows every count, but its result counts cover the results on the assessments linked to that project, so a candidate of another project that shares one of those assessments can be counted too. An assessment narrows only the result counts: the stage and application counts stay at everything your connection can reach. The kinds are never added together.
Top candidates The highest-ranked results, ordered by overall score. Every kind of assessment is ranked together unless you ask for one kind or for one assessment (interview set).
Assessment result detail One result's per-competency scores plus the AI summary, for the kinds that have them. A Skill Test, a Technical Test, a Showcase and a questionnaire have little or none.
Job post detail The full detail of a single job post.
Is a job post open to the public? (get_job_post_publication) Whether anyone can open a job post's public page: live, still waiting for the AI content check, refused by it, flagged, switched off, or its project is not open. Also its public address and its boost (off, flowmingo or extended). Needs Read hiring data.
Upcoming interviews Invitations to any kind of assessment that were sent or are scheduled and are not yet completed. It is not a count of everyone still outstanding: an invitation whose candidate has been reminded, or has opened or clicked the link, is left out until the candidate starts, and so is one that failed to deliver.

Write (guarded)

Capability What it does
Invite candidates to an assessment Prepares the invitations for an AI interview, a role-play, a Skill Test or a Technical Test, and waits for a person to approve them at a link. Nothing is sent before then. One assessment and at most 50 candidates per request; a Skill Test or a Technical Test needs a project and an email for every candidate, and a sponsored one can debit your organisation's wallet when a candidate starts it.
Move a candidate to another stage A move to a stage that is set to email the candidate normally waits for a person to approve it at a link (the stage's email setting is read once, just before the move, so a setting switched on at that moment can still let a move email without approval). Any other move: the assistant is told to preview it and wait for your yes, and it can usually be undone for 24 hours, when it came back with an undo reference. At most 50 applications per request.
Reject an application Requests approval at a link. If a person approves it, Flowmingo attempts to move the application to the project's Rejected stage; check the result afterwards. At most 50 applications per request.
Remove candidates from a project (remove_application) Needs Manage pipeline. Requests approval at a link. If a person approves it, Flowmingo deletes the applications from the project; the candidate's profile stays in your talent pool and in other projects. It is not a reject, and there is no undo. At most 50 applications per request.
Add a note to a result The assistant is told to preview the proposed note and wait for your yes before saving it. A note belongs to one assessment result (of any kind), not to the candidate as a whole.
Rate a result The assistant is told to preview the rating and wait for your yes. The rating applies to one assessment result.
Shortlist a result The assistant is told to preview the shortlist change and wait for your yes. It applies to one assessment result.
Tag / add to talent collection The assistant is told to preview the tag or talent-collection change and wait for your yes.
Check, withdraw or undo a change Check where a staged change stands (waiting, carried out, failed, expired or replaced by a newer request), withdraw one that still waits for approval, or undo a reversible change within 24 hours, when it came back with an undo reference.

Create and publish (acts at once, except deleting a project)

These tools create things and open them to the public. They behave differently from the guarded writes above:

  • They act at once, except delete_project. Nothing is staged for a person to approve at a link, and none of them emails a candidate. delete_project waits for an Owner or an Admin to approve it at a link.
  • The key's creator must be an Owner or an Admin, for every tool here except the cancel, which needs only Invite candidates. The tools act with the permissions of the person who created the API key. If that person is a Member, the call is refused.
  • Two permissions are opt-in. Create hiring projects and Create assessments are not given by default. With sign-in (option A), the assistant gets them only if both are true: the client lists them by name when it connects, and the API key you paste on the consent page holds them. A client that sends no list of permissions gets the four standard permissions (Read hiring data, Read candidates, Manage pipeline, Invite candidates) that the key holds, and neither of these two, so the assistant does not see the tools that need them. With a static key (option B), the assistant is shown these tools whatever permissions the key holds, and Flowmingo refuses any call the key does not allow.
  • Some calls take a while. Publishing waits for the AI content check, up to about 90 seconds. Creating a project or an assessment uses AI generation and can take longer (a Technical Test takes 3 to 9 minutes). When the answer says the work is still pending, the assistant calls again with the same idempotency key to read where it has got to. A retry never makes a second project or assessment.
Capability What it does
Create a hiring project (create_project) Needs Create hiring projects (opt-in). Makes a project with its four default stages and a job post written by the same AI as the dashboard, from a title, the position and an optional description. By default it also makes a CV Evaluation and an AI Interview; the assistant can name other assessments, or none. The job post is switched on and goes public once the AI content check approves it, normally within a minute. Limited to 10 projects a minute and 300 a day for your company. The idempotency key is optional: when it is left out, one is made from the arguments, so a retry never makes a second project.
Create an assessment (create_assessment) Needs Create assessments (opt-in). Makes one assessment with the AI: an AI Interview, a CV Evaluation, a Skill Test, a Showcase, a Technical Test or a Role-play, from a job title and an optional job description, name, project and language (a tag such as en or vi-VN; a Skill Test and a Technical Test ignore the language). Attach it to a project so that candidates can be invited to a Skill Test, a Technical Test or a Showcase. The idempotency key is optional, as above.
Publish a job post (publish_job_post) Needs Create hiring projects. Switches the job post on and makes sure the AI content check has run. The answer says whether the page is live now, still waiting for the check, or refused by it. The hiring project must be active.
Unpublish a job post (unpublish_job_post) Needs Create hiring projects. Switches the job post off, so its public link stops opening. By default the boost is switched off too (withdraw_boost is true).
Boost a job post (boost_job_post) Needs Create hiring projects. Sets the boost to off, flowmingo or extended. Boosting is free. Raising it needs the job post switched on, its project active, a company logo and description, and the AI content check; a company may raise 50 boosts a day.
Open, draft or archive a project (set_project_state) Needs Create hiring projects. Moves a hiring project between active, draft and archived. Draft and archived close the job link. Candidate data is kept.
Cancel a scheduled invitation (cancel_scheduled_invite) Needs Invite candidates. Cancels an invitation that was scheduled for later and has not been sent yet, using the invitation id from the invite result. Nobody is emailed. The person stays in your account and on the project board.
Delete a hiring project (delete_project) Needs Create hiring projects (opt-in). It only asks: it does not delete at once, it requests approval at a link, and nothing is deleted until an Owner or an Admin approves it. Only an active project can be deleted. If a person approves it, Flowmingo deletes the project and its job posts; its candidate applications are not deleted one by one, and candidate profiles and contacts, your assessments and invitation links are kept. There is no undo.

Security & trust

  • Your data is org-scoped — the assistant can never see another company's data.
  • With OAuth, the assistant never receives your API key. It gets an access token that expires after an hour, refreshed quietly while it stays connected. The sign-in itself lasts as long as its refresh token, about 30 days by default from when it was issued or last refreshed, so it lapses after about 30 days without use, and you then sign in again. With a static header (option B) your assistant's client holds your key and sends it with every request, so keep it out of files you might share or commit.
  • Cutting an assistant off: delete the API key you authorised it with, in Settings → Integrations → API Keys. Access stops immediately. There is no per-assistant disconnect yet, so if you want to revoke them one at a time, give each assistant its own key.
  • Requests to the /mcp endpoint are checked for their Origin: an opaque null origin is always refused, and the check can be locked to an allowlist, but by default every real origin is accepted, so the protection is your credential, not the origin. Each session is bound to the credential that opened it.

For how to authenticate, see Authentication — two options; for the exact reads, guarded writes and actions that happen at once, see What you can do. When you're ready, jump to Connect your assistant and pick your client.

MCP server URL

MCP server URLhttps://mcp.flowmingo.ai/mcp

Connect your assistant

Which assistant are you using?

Claude Code (CLI)

One command adds Flowmingo over native Streamable HTTP. Lead with OAuth; the static --header is the alternative.

Steps: 1) add the server, 2) log in (browser → paste key), 3) claude mcp list to verify.

# OAuth (recommended) — flags BEFORE the name:
claude mcp add --transport http flowmingo https://mcp.flowmingo.ai/mcp
claude mcp login flowmingo          # browser opens; paste your fl_ key on the consent page

# Static API key instead (pick ONE header):
claude mcp add --transport http flowmingo https://mcp.flowmingo.ai/mcp \
  --header "x-api-key: fl_YOUR_KEY"
# or: --header "Authorization: Bearer fl_YOUR_KEY"

# Share with a repo team (writes a git-committable .mcp.json):
claude mcp add --transport http --scope project flowmingo https://mcp.flowmingo.ai/mcp

claude mcp list && claude mcp get flowmingo

Gotcha: flags must come before the name, and always use --transport http (never sse). Replace fl_YOUR_KEY with your complete key (see What a complete key looks like in the Authentication section above).

Verify it works — ask: "list my open jobs."