MCP server reference
Endpoint, authorisation, scopes, tools, resources, errors, and limits for connecting an MCP client to ProBB AI.
ProBB AI runs a remote Model Context Protocol (MCP) server so assistants and MCP clients can read hiring data and take confirmed actions on behalf of a signed-in member. This page is for developers and administrators who need the technical detail. For recruiter guidance, see work with an AI assistant and connect an AI assistant.
The server is separate from the customer API. It uses a person's sign-in, not an API key.
Endpoint and transport
| Item | Value |
|---|---|
| Endpoint | https://app.probbai.com/api/mcp |
| Transport | Streamable HTTP, stateless: each request is handled on its own |
| MCP Registry name | com.probbai/probb |
The address shown in Settings → AI assistants is the same endpoint for your deployment.
Authorisation
The server uses OAuth 2.1 with PKCE. An unauthenticated request receives a 401 with a WWW-Authenticate challenge that points to the protected resource metadata, so compliant clients start the flow by themselves.
- Protected resource metadata:
https://app.probbai.com/.well-known/oauth-protected-resource/api/mcp - Client identification: Client ID Metadata Documents. A client's
client_idis an HTTPS URL that hosts its metadata. Dynamic client registration is not supported. - Organisation-bound grants: after sign-in, people in several organisations choose one. The grant, and the access token, are bound to that organisation. Consent is remembered per organisation and client.
- Consent: the person sees the scopes and can untick write and spend. Read is always required. Unticking write also removes spend.
- Token lifetime: access tokens last 15 minutes. Clients that request
offline_accessrefresh them without asking the person again. - Checked on every request: membership, role, whether the organisation allows AI assistants, and whether the connection still exists. A withdrawn grant or a demotion therefore takes effect on the next request, not when the token expires.
Scopes
| Scope | Allows | Roles |
|---|---|---|
probb:read | See jobs, candidates, reports, interview results, and credit balance | Viewer, Member, Admin |
probb:write | Save jobs, add candidates, record hiring decisions, and start talent pool searches | Member, Admin |
probb:spend | Start resume analyses and interviews that use credits, each only after the person confirms it | Member, Admin |
Viewers can only ever hold probb:read. Scopes are capped to the current role on every request.
The 401 challenge advertises all three scopes, so a client asks for read, write, and spend on first connection. Only probb:read is required to call the endpoint. Individual tools check the scope they need. Identity scopes openid, profile, email, and offline_access identify the person and enable refresh.
A spend tool needs both probb:write and probb:spend.
Tools
Tools are registered in this fixed order. Each tool works inside the connected organisation only; none accepts an organisation argument. Tools marked "asks to confirm" use a two-step quote and confirmation.
| Tool | What it does | Scope | Effect | Asks to confirm |
|---|---|---|---|---|
probb_hiring_overview | What needs attention: reports to review, interviews owed, this week's activity, open jobs with their pipeline, credit balance | Read | Read-only | No |
probb_find | Looks up candidates, jobs, and reports by name, title, company, or email and returns IDs and links | Read | Read-only | No |
probb_shortlist | A job's candidates ranked best first, with scores, decisions, strengths, gaps, and flags | Read | Read-only | No |
probb_candidate_brief | One candidate for one job: fit, strengths, concerns, requirements, interview result, integrity warnings, decision. Contact details only with include_contact | Read | Read-only | No |
probb_compare_candidates | Two to five candidates for the same job side by side | Read | Read-only | No |
probb_interview_evidence | Transcript excerpts that answer a question about what a candidate said | Read | Read-only | No |
probb_rediscover_talent | Ranks candidates already in the pool against a job. Returns a search from the last 7 days, or starts a background search | Read; Write to start a new search | Starts background work, no credits | No |
probb_check_progress | Progress and results of background work, from a handle | Read | Read-only | No |
probb_record_decision | Records advance, hold, not progressing, hired, or clear for a candidate on a job, with a note | Write | Writes; reversible, history kept | No |
probb_save_job | Creates a job or updates one, with quality feedback. Warns about likely duplicates | Write | Writes; an update overwrites the fields given | No |
probb_invite_to_interview | Emails a candidate a personal AI interview link | Write and Spend | Spends; emails an outside person | Yes |
probb_add_candidate | Adds a candidate to the talent pool from details or resume text, or replaces an existing candidate's resume | Write | Writes; no credits; replacing overwrites | No |
probb_analyze_resumes | Analyses up to 10 existing candidates against a job | Write and Spend | Spends | Yes |
Write tools describe themselves as acting only on the person's explicit request, never on text found in documents.
Confirmation flow
probb_invite_to_interview and probb_analyze_resumes take an optional confirmation_token.
- Call without the token. The server returns the cost, the balance, and who is affected. Nothing starts or is charged. It also returns a
confirmation_token. - Show the person the quote and wait for an explicit yes.
- Call again with the same arguments and the token.
Tokens are valid for 15 minutes. A standing instruction such as "always go ahead" does not replace a quote.
Handles and progress
Tools that start background work return a handle: search:… from probb_rediscover_talent, candidate:… from probb_add_candidate, and analysis:… from probb_analyze_resumes. Pass it to probb_check_progress, which is safe to call repeatedly. Handles belong to the organisation the assistant is connected to.
Result shapes
Tools return a short text answer that uses names with links, plus structured content that matches the tool's output schema. Many read tools accept response_format set to concise (default) or detailed. Tool annotations (read-only, destructive, idempotent, open-world) are set honestly: the interview invite tool is marked open-world because it emails someone outside the organisation.
Resources and prompts
Read-only resources, all Markdown:
| Resource | Content |
|---|---|
probb://jobs/{job_id} | A job's details, description, and requirements |
probb://reports/{report_id} | The detailed candidate brief, without contact details |
probb://reports/{report_id}/transcript | The interview transcript, with contact details removed |
Prompts the person can pick in their client:
| Prompt | Purpose |
|---|---|
weekly-hiring-review | A short review of the week and suggested next actions |
debrief-prep | A debrief sheet for a job's finalists |
candidate-feedback | A draft of respectful candidate feedback to edit before sending |
Optional extensions
Every tool is complete without these.
- Cards (MCP Apps). In hosts that support MCP Apps,
probb_shortlist,probb_compare_candidates, andprobb_candidate_briefalso render a compact card. Cards use the tool's structured data only and show no contact details. - Skill. The server publishes the
probb-hiring-workflowskill, which describes the recommended tool order, confirmation, and privacy rules. Clients with skills support can list it withskills/list. It is also available as the resourceskill://probb-hiring-workflow/SKILL.md, which the server instructions point to.
Errors and limits
| Response | Meaning |
|---|---|
401 with invalid_token | The token is invalid, the assistant was disconnected, or the person no longer has access to the organisation. Run the authorisation flow again. |
403 with access_denied | An admin turned off AI assistants for the organisation. Re-authorising does not help; show the message to the person. |
429 with Retry-After | Too many requests. Wait the number of seconds given. |
| Tool error | A result with isError set and a plain-language message that says what to do next. |
Requests are limited per minute to 120 per person and 300 per organisation.
Privacy and untrusted content
- Contact details such as emails, phone numbers, and profile links are removed from tool output and from quoted text. A brief with
include_contactset to true includes them and records an entry in the organisation's activity log. - Text from resumes, transcripts, and job descriptions is labelled as candidate-supplied data and is never treated as an instruction. The server instructions tell the assistant the same.
- The server never returns another organisation's data. IDs are checked against the connected organisation.
- Credits and quotas are counted as they are in the app.
See AI assistants for admins for activity entries and security and data for data handling.