AI Agent and MCP Tools

Why It Matters

Recruiting is a queue. Reviews pile up, applications go idle, five candidates need the same “thanks, not this time” written kindly. Kit exposes the Hiring module to AI assistants two ways — the in-app agent that lives on every Hiring page, and MCP tools any external client (Claude Desktop, Claude Code, Codex CLI, or your own agents) can call against your account.

You do not need to be an account admin to connect. Anyone with Hiring access can set up an MCP client and point it at Kit. Connecting is a personal act, like installing an app on your own laptop — what the assistant can then reach is decided per call by your own permissions, not by who set it up.

Both surfaces enforce the same rules as the UI: module permissions, per-posting access, tenant scoping, and every lifecycle guard the forms enforce. An assistant acts as you. It can never reach a job posting you can’t open, and it can never do something the web UI would refuse you.

The In-App Assistant

Open the AI chat on any page under Hiring — it activates automatically, alongside the Security and Outreach agents. It can:

Work your queue — “What’s waiting on me today?” returns your open reviews and any team review that concluded without a clear outcome, each with the candidate, the stage, and how long it has been sitting.

Screen candidates — “Summarize the top 3 applicants for the Senior Rails role” pulls application summaries, extracted candidate data fields, and CV text, then ranks them against the posting.

Move the pipeline — advance a candidate to the next stage, reject with a personalized note, or reverse a rejection. Every action is attributed to you and lands on the audit trail.

Draft candidate replies — the agent stages an email as a pending draft. Nothing leaves Kit until a human sends it.

Plan contextual follow-ups — from an application, the agent can help draft a concise internal reminder with a future local time and eligible teammates. You review every field and decide whether email is also enabled.

Answer platform questions — the agent searches Kit’s docs inline.

MCP Tools Reference

What Your Role Allows

Three separate limits stack, and a tool call has to clear all of them:

1. The connection’s scopes. When you authorize a client you pick, per module, read or read & write. A connection granted only hiring_read cannot write, no matter who you are. Writes are off by default on the consent screen.
2. Your own Hiring level. Kit re-reads your live per-module level on every single call, so a change to your access takes effect immediately, without waiting for the next token refresh. A member without Hiring access gets no hiring tools at all. Within Hiring, you reach the postings you’d reach in the browser: unrestricted ones, plus any where you’re on the job team. Hiring module admins can access all postings. A posting you cannot access returns “not found”, identical to a nonexistent ID.
3. Module admin and subscription. A handful of tools are reserved for Hiring admins — creating job postings and process templates, and changing CV download settings. Defining and editing metafields follows the same rule as the web app: Hiring admins plus the hiring managers of that specific posting. Most write tools additionally require an active subscription.

The recruiter role preset gives Hiring admin, so a recruiter gets the full hiring toolset without holding account admin anywhere else. See Team Roles for what each preset grants.

In the Requires column below: read means any Hiring member with a read scope; write means the connection needs read & write; Hiring admin means module admin on Hiring; admin or HM means Hiring admin or a hiring manager on that job posting; subscription means an active plan.

Setup and Templates

Tool	Requires	What it does
hiring_get_setup_guide	read	Start here. Account state, what your role allows, a setup checklist with the tool that fixes each gap, and the recommended next call
hiring_list_templates	read	Hiring process templates available to the account, with tags and publish state
hiring_get_template	read	One template in full: every stage, its type, and its configuration
hiring_create_process_template	write · Hiring admin	Create a reusable process template from a list of stages, with optional reviewers per stage

Postings

Tool	Requires	What it does
hiring_list_job_postings	read	Postings you can access, with status, application counts, and stage summaries
hiring_get_job_posting	read	One posting in full: body, stages with config, reviewers, and portal URL
hiring_create_job_posting	write · Hiring admin · subscription	Create a draft posting, applying a template or inline stages. Returns the edit URL
hiring_create_stage	write · admin or HM · subscription	Insert a configured stage into an existing posting, with optional reviewers. Published pipelines with active candidates require explicit confirmation
hiring_list_metafield_definitions	read	The custom data fields defined on a posting, with types and extraction settings. Managers-only fields appear for admins and the posting’s hiring managers only
hiring_create_metafield_definition	write · admin or HM	Add a metafield to a posting, optionally marked for AI extraction or restricted to managers only

Pipeline

Tool	Requires	What it does
hiring_list_applications	read	Submitted applications, filterable by posting, status, and date range
hiring_get_application_summary	read	Everything needed to screen one application: candidate, answers, stage history, notes
hiring_get_stage	read	Complete pipeline-stage config by numeric or stg_ ID; read before updating
hiring_get_stage_progress_details	read	Candidate-specific detail for one sp_ stage progress — code assignment, interview, video, portfolio
hiring_search_video_transcripts	read	Semantic and text search across video interview transcripts
hiring_get_metafield_values	read	Extracted and manual field values for an application, with confidence scores. Managers-only fields appear for admins and the posting’s hiring managers only
hiring_list_reminders	read	Participant-scoped reminders, plus eligible teammates and the time-zone context for a new application reminder
hiring_advance_application	write · subscription	Move an application to the next stage, or skip ahead to a named one
hiring_reject_application	write · subscription	Reject an application. The candidate is emailed, with your personalized message if you supply one
hiring_unreject_application	write · subscription	Reverse a rejection, with a required audit reason
hiring_save_note	write · subscription	Save feedback or a thread summary to an application, attributed to you
hiring_update_metafield_value	write · admin or HM	Set a field value manually, recorded as your edit and protected from re-extraction
hiring_trigger_metafield_extraction	write · admin or HM	Re-run AI extraction against an application’s resume
hiring_create_reminder	write · subscription	Create an internal application reminder; in-app is always on and email requires explicit opt-in
hiring_update_reminder	write · subscription	Creator edits reminder fields; any participant can complete or reopen it

Reviews

Tool	Requires	What it does
hiring_list_reviews	read	Your review inbox, split into what needs a decision, what you owe, and what’s pending on others
hiring_get_review_details	read	Everything a reviewer needs for one candidate at one stage: criteria, submissions, prior scores
hiring_list_pending_decisions	read	Team reviews that concluded without a clear outcome — a split vote, or no quorum
hiring_get_team_bottlenecks	read · Hiring admin or HM	Overdue work by teammate, with wait times and examples; managers see only accessible postings they manage
hiring_decide_review	write · subscription	Record an attributed, audited call on a stalled team review, with a required rationale

Team bottlenecks require Hiring Insights access and are available in the private Kit assistant and OAuth MCP, not shared Slack channels. Tenant and restricted-posting permissions also fence aggregate counts. Candidate/external waits are separate; shared or fallback ownership identifies follow-up contacts, not poor performance. limit is 1–50 (default 10); totals cover all visible work even when the owner list is truncated.

Talent Pool

Tool	Requires	What it does
hiring_list_talent_pool	read	Verified talent pool entries with compact resume summaries, paginated
hiring_search_talent_pool	read	Search the pool by skills, experience, or email — semantic with text fallback
hiring_invite_talent_pool	write · subscription	Invite a pool entry to apply for a specific posting

Messaging

Tool	Requires	What it does
hiring_list_conversations	read	The candidate mailbox across accessible jobs, defaulting to conversations that need attention
hiring_list_messages	read	A bounded delivered email thread, with pending drafts and failures separated
hiring_send_message	write · subscription	Stage a reply as a pending draft. The candidate is not emailed until a human sends it

The agent-native flow is search → read → draft → verify: list conversations, read the selected thread, confirm the wording with the user, stage the draft, then read the thread again to verify the pending draft and open its human-review link.

Candidates and CVs

Tool	Requires	What it does
hiring_get_candidate_summary	read	One candidate across every application they’ve made to you
hiring_get_candidate_cv	read	The extracted CV text for a candidate or talent pool entry
hiring_get_candidate_cv_url	read	A short-lived signed download URL for the original file — five minutes by default, ten at most
hiring_get_cv_download_settings	read	The account’s CV download trust config: trusted domains, strict mode, and what it means in practice
hiring_update_cv_download_settings	write · Hiring admin · subscription	Add or remove trusted domains, or turn strict mode on and off

Records are addressed by prefixed IDs (job_… postings, app_… applications, cand_… candidates, tpe_… talent pool entries) that tools return and accept, so an agent chains list → get → act without screen-scraping.

Adding a Stage Safely

Use a search–act–verify loop for pipeline structure:

1. Call hiring_get_job_posting and read the complete ordered stage list.
2. Call hiring_create_stage with the posting ID, stage type, config, and any initial reviewers. position is zero-based; omit it for the safe default immediately before a trailing Offer stage.
3. Call hiring_get_job_posting again and verify the final order, config, reviewer roster, and warnings.

The first stage must remain an Application Form and Offer must remain last. On a published posting with active candidates, Kit first returns an impact summary and makes no change. Show that summary to the user, then retry with confirm_live_pipeline_change: true only after they approve it. Existing candidates keep their current stage: people before the insertion may encounter the new stage later, while people already beyond it do not move backward.

Reviewer assignment has a separate human effect. Each reviewer must already be an account member who can access the posting; on a restricted posting that means a Hiring module admin or someone on that posting’s job team. Adding reviewers queues onboarding, and a first-time reviewer may receive their once-ever reviewer onboarding email. Confirm the exact roster before the create call.

Limits

• Rejecting a candidate triggers an email. hiring_send_message creates a pending draft for a person to review and send in Kit. hiring_reject_application triggers a rejection email, subject to your account’s rejection delay. Approving a rejection also approves that notification.
• CV access follows the account’s CV-download settings. hiring_get_candidate_cv_url mints a signed URL under the same trust rules the browser applies — trusted domains, strict mode, and your team’s own access. Turning strict mode on narrows what the tool will hand back.
• Restricted postings are invisible, not forbidden. A posting you’re fenced off from returns “not found” rather than “denied”, so nothing about it leaks — including whether it exists.
• Restricted reviewer rosters stay fenced too. hiring_create_stage refuses a reviewer who cannot open that restricted posting, even when they belong to the same account.
• No agent can promote itself. Nothing in the hiring toolset changes anyone’s role, access level, or module membership.

Connecting an External Client

Setup lives at Integrations > Kit for AI, with copy-paste config per client. No admin access is required to open it. For Claude Code:

claude mcp add --transport http kit https://startupkit.app/api/v1/mcp

On first use, your client walks through Kit’s OAuth flow in the browser. Pick the account, then grant hiring_read for triage and reporting, and hiring_write only to assistants that should act on your behalf. Modules you don’t have access to appear on the consent screen marked as not part of your role — granting them mints nothing usable.

Full setup for every client, the OAuth flow, and the 90-day inactivity sweep are covered in Connecting AI Assistants.

Start With the Built-In Role Handoff

Kit ships a conversational onboarding workflow with the MCP server. In Claude Code, run:

/mcp__kit__hiring_role_handoff job_abc123

In clients with a prompt picker, choose Understand your role in a hiring process (hiring_role_handoff). The job ID is optional: when your team sent you a role-specific onboarding plan, the workflow picks up that assigned role automatically; otherwise it shows the job postings you can access and asks you to choose one.

The handoff verifies your identity and account, explains the configured candidate journey, distinguishes your job-team role from any lead or reviewer assignments, and flags setup gaps before you touch live work. The prompt instructs the assistant to keep the orientation read-only, ask one question at a time, and use Kit’s documentation search when live data does not establish how a feature behaves. Your granted scopes and your MCP client’s own confirmation controls remain the authorization boundary. For a candidate-specific question, add the application ID or paste its Kit URL; delivery claims are checked against the recorded message status rather than inferred from a stage change.

Rehearse Search–Act–Verify

Use the role named in your onboarding plan. Ask the agent to find that posting, read its process, and explain the action it proposes before calling a write tool. For a safe first loop, have it stage a pending candidate reply with hiring_send_message, verify the draft in Kit, and then discard the draft in the message thread. The candidate receives nothing unless a person explicitly sends it.

Set Human Approval Boundaries

Tell your harness what it may do without interruption and what must pause for your approval. Reading, searching, and summarizing can usually proceed. Require confirmation immediately before candidate-facing, destructive, or irreversible actions—especially hiring_reject_application, which sends an email, and pipeline moves that notify a candidate. hiring_send_message creates only a pending draft, but a person must still review and send it in Kit.

Example Prompts

What you type	What happens
“What’s waiting on me today?”	hiring_list_reviews + hiring_list_pending_decisions → your open reviews and every stalled team decision, oldest first
“Who from our team is stalling most?”	hiring_get_team_bottlenecks → overdue obligations by responsible teammate, oldest waits and examples within your access; an empty personal decision queue does not mean the team has no blockers
“Summarize the top 3 candidates for the Senior Rails role”	hiring_list_applications → hiring_get_application_summary → hiring_get_candidate_cv → a ranked shortlist with the evidence behind each rank
“Move Priya Raman to the technical interview stage”	hiring_get_application_summary → hiring_advance_application → the candidate is advanced, attributed to you, and an applicable notification is queued; verify recorded delivery status before claiming receipt
“Draft a warm rejection for everyone idle in Screening for 3+ weeks — show me before sending”	hiring_list_applications → a per-candidate draft in chat; nothing is sent until you approve each hiring_reject_application
“Who in the talent pool matches this posting?”	hiring_get_job_posting → hiring_search_talent_pool → matches with reasons, then hiring_invite_talent_pool on your say-so
“Why did we pass on this candidate last year?”	hiring_get_candidate_summary → every prior application, stage reached, and the notes attached
“Add a written IT triage exercise before Offer and make Ana the lead reviewer”	hiring_get_job_posting → confirm the zero-based insertion and reviewer → hiring_create_stage → hiring_get_job_posting to verify order, questions, roster, and warnings
“Remind Ana and me to contact this candidate Friday; show me the date and email choice first”	hiring_list_reminders for the application → propose text, local time, and eligible people → confirm → hiring_create_reminder → hiring_list_reminders to verify

Quick Checklist

• Start your first role handoff with /mcp__kit__hiring_role_handoff
• Try the in-app agent on Hiring: “What’s waiting on me today?”
• Connect your MCP client at Integrations > Kit for AI — no admin access needed
• Grant hiring_read broadly; reserve hiring_write for assistants you trust to act
• Use hiring_get_setup_guide for later account-wide setup and queue checks — the role handoff calls it automatically
• Chain the triage flow: list reviews → get review details → advance or reject
• When adding a stage, use get posting → create stage → get posting, and confirm any live-pipeline impact or reviewer email first
• Confirm your account’s CV download settings before pointing an agent at resumes

Next Steps

• Connecting AI Assistants — full MCP setup, OAuth flow, and client configs
• AI Providers & Spend Controls — configure account keys, caps, and usage ownership for built-in AI
• MCP Tools Reference — every tool across every module, with scopes
• Contextual Reminders — draft and deliver internal Hiring or Security follow-ups
• Managing Your Pipeline — the stages and decisions these tools drive
• Team Roles — what each role preset grants, including recruiter