Guides
MCP V2 tools
Search MCP V2 lets a connected assistant search, read, analyze, and act in SeekOut through tools at the /v2/mcp resource. Use this guide to choose a tool; your connected client shows its current input schema.
Connect and check access
Follow the recruiter integration guide for the setup path for your assistant or automation. Connect to the MCP V2 resource URL configured for your environment, rather than the REST /v1 URL. A Developer API key can authenticate the MCP V2 Developer lane when that lane is enabled, but REST requests are not MCP tool calls.
Add Claude as a custom connector with the URL https://mcp.seekout.io/v2/claude. Every other MCP client connects to the Streamable HTTP URL https://mcp.seekout.io/v2/mcp. The REST API is a different address: https://developer-api.seekout.io/v1.
Choose an authentication method
MCP V2 supports five caller credential types. The available tools still depend on the caller's grants, Recruit entitlements, configured sources, and the operation. Use discover to check a specific operation.
Dynamic Client Registration (DCR) OAuth
A Recruit user signs in through a public client registered by the assistant, using browser OAuth with PKCE. The user can run authorized Recruit-backed search, profile, workspace, contact, and export operations. Recruit accounting applies.
Partner OAuth
A Recruit user signs in through an administrator-provisioned partner client. The user and client can access permitted Recruit-backed operations. Recruit accounting applies.
User-delegated M2M
Headless automation uses an administrator-provisioned client bound to one Recruit user and organization. It can run Recruit-backed operations permitted for that user, without browser sign-in. Recruit accounting applies.
Developer workspace API key
A Developer application/workspace can use granted public candidate search, profile, and matching operations. It has no Recruit user authority. Billable work uses Developer credits.
Personal API key
A person and Recruit organization associated with a Developer application/workspace can use granted public and entitled private candidate reads, user/workspace operations, contacts, and exports. Billable work uses Developer credits.
people.matchis unavailable for this key.
OAuth clients receive an MCP V2 audience-bound access token. Developer keys are opaque and are classified from the trusted whoami verdict, not their spelling. Internal service credentials are transport identity, not a sixth customer authentication method.
Connect your MCP client
Connect to the Search MCP V2 resource, then let the client list tools and their input schemas. The server checks the credential on each call.
Check what this credential can do
Call
get_account_capabilitiesfor source access, credits, or destinations. Calldiscoverfor a specific operation or read/write effect. It reports a binding or a reason the operation is unavailable.Run the operation and show its result
For an available discovered operation, use
execute_readorexecute_writewith that operation's direct-tool arguments. Other tools are called directly. When a result includes apresentation_id, pass it topresent_resultsbefore summarizing the displayed result.
Discovery and presentation
| Tool | Use it for |
|---|---|
get_account_capabilities | Check current source access, optional balances, and destinations. |
discover | Find the seven catalog operations and their credential-specific bindings. |
execute_read | Run an available catalog read with the direct tool's arguments. |
execute_write | Run an available catalog write with the direct tool's arguments. |
present_results | Display a producer's result using its single-use presentation ID. |
The catalog covers candidates.search, candidates.profile.get, candidates.contacts.retrieve, candidates.contacts.status, people.match, workspaces.state.read, and workspaces.manage. A listed tool may still refuse an operation your credential cannot use. discover returns current availability; it does not grant access. Tools outside this catalog use their direct names below.
Find and understand candidates
| Tool | Use it for |
|---|---|
search_candidates | Create, refine, page, or show a search; shown results supply candidate references. |
get_candidate_profile | Read full detail for candidates from an earlier search; contacts are separate. |
match_person | Match one person from known signals; available first for Developer workspace credentials. |
analyze_talent_market | Measure external talent supply, compare markets, or study company talent flow. |
analyze_internal_talent | Analyze entitled internal talent; check that access first. |
get_resources | List or read search workflow guides; it does not run a search. |
Workspaces, contacts, and exports
| Tool | Use it for |
|---|---|
get_workspace_state | List workspaces, optionally filtered by name, or read one workspace. Saved searches are not served yet. |
manage_workspace | Create or rename a workspace, or add a saved search or candidates to one; replace_base overwrites its base search. |
retrieve_contacts | Start a credit-spending email or phone retrieval for selected candidates. |
get_contact_status | Poll the contact job using its returned ID and revision; polling spends no credits. |
export_candidates | Export selected candidates to a file or connected ATS; ATS export sends data outside SeekOut. |
manage_playbook | Save or review reusable search playbooks; organization review actions need admin access. |
report_issue | Send feedback or a bug report when the user asks; a state snapshot is included by default. |
Before a write or paid action
- Check account capabilities and the current result before retrieving contacts or exporting candidates. Contact retrieval may spend credits; an ATS export may send data to a third party.
- Use a fresh
mutation_keyfor a new write and reuse that key only to retry the same request. A different request with the same key is refused. - Confirm the chosen workspace and operation before
replace_base, playbook deletion, or a large batch.report_issuerecords the report and cannot withdraw it after capture. - Keep a contact job's
contact_job_idandsubject_revision; useget_contact_statusto check progress instead of starting another retrieval.
tools/list schema and the discover result before building a call. This guide describes the MCP V2 surface; the API reference documents REST operations.