Developers and agents

TalentPrism Developer API and MCP

Integrate with TalentPrism through a typed OpenAPI surface, the tp CLI, or MCP Streamable HTTP. All recruiting data stays authenticated and team-scoped. Public discovery endpoints reveal schemas and safety contracts without exposing candidate or customer records.

OpenAPI and REST

Start with the public OpenAPI 3.1 description or agent API overview. The predictable schema documents public discovery, tool manifests, JSON errors, authentication, and the MCP transport.

Model Context Protocol

Connect to /mcp/ using MCP Streamable HTTP. Initialization and tool discovery are public. Tool calls require a team-scoped credential. MCP v1 is read-only by default. The only writes it can perform are candidate text and email sends, offered to an OAuth connection granted mcp:tools:write on a team that turned sending on. Every other change stays on the first-party CLI and product paths with their existing confirmation policies.

Connect Claude with OAuth

Add /mcp/ as a custom connector. Sign in with an existing approved TalentPrism account, choose the authorized team, and approve read-only access (sending is a separate, unticked box, shown only when the app asks for it). Public signup remains disabled; if your company is not yet provisioned, use the Book a Demo path below. No API key is copied into Claude.

CLI and agent guidance

Read the TalentPrism CLI guide for commands and structured errors, and llms.txt for when agents should use TalentPrism, how they should call it, and which actions are unsupported.

Disconnect and CLI compatibility

Disconnect TalentPrism from Claude's connector settings to revoke its OAuth grant. People sign in to the tp CLI with tp login, and tp logout revokes that sign-in. The CLI sign-in is a separate grant from the Claude connector: a token for one does not work for the other. Automation, agents and existing integrations still use Authorization: Api-Key <key>; OAuth does not create, migrate, or invalidate those team-scoped keys. See auth.md for the complete protocol and error contract.

Scopes, sending and approval

mcp:tools:read (required): every Read tool below.
mcp:tools:write (optional, request it together with mcp:tools:read): adds the candidate text and email send tools, their previews, and the text delivery check. The person connecting must tick the Sending box on the consent screen; it is unticked by default, and an unticked box grants read-only.
Sending also needs the team setting "MCP connector sending", which a TalentPrism admin turns on. It is off by default. API keys used on /mcp/ stay read-only.
There is no TalentPrism approval round trip on MCP. The client must call the ..._preview tool, show the person the candidate and the exact message, and get their approval before each send. Sends are audited as approved_by_mcp_client.
Every send needs an idempotency_key. Repeating a call with the same key returns the first receipt (idempotent_replay: true) and sends nothing. Sends go only to the phone or email on the candidate's record; contact details in results are masked as [restricted].
Candidates who replied STOP or are marked do-not-contact are always refused.

MCP tool reference

Read tools change nothing. Sensitive writes reach a real person and cannot be undone. There are no other writes on MCP. This list is generated from the same registry that answers tools/list.

Tool	Class	What it does and side effects	Inputs (* required)	Output fields	Scope and limit
`agent_capability_connection_context`	Read	Show the signed-in TalentPrism user and currently authorized team. None. Each call writes an audit row.	none	`actor`, `team`	mcp:tools:read 300 calls/min per connection (read bucket)
`agent_capability_sequences_list`	Read	List current-team job sequences with optional status filtering. None. Each call writes an audit row.	`status`, `include_duty_containers`	`count`, `results`	mcp:tools:read 300 calls/min per connection (read bucket)
`agent_capability_sequences_show`	Read	Show current-team sequence metadata. None. Each call writes an audit row.	`sequence_id`*	JSON object	mcp:tools:read 300 calls/min per connection (read bucket)
`agent_capability_candidates_search`	Read	Search candidates in the current team. Use `query` alone to look someone up by name; the other inputs are narrowing filters that do not search names. None. Each call writes an audit row.	`query`*, `role`, `target_role`, `skills`, `keywords`, `location`, `status`	`count`, `results`	mcp:tools:read 300 calls/min per connection (read bucket)
`agent_capability_jobs_search`	Read	Search configured team job feeds for recruiter lead-to-job matching and campaign planning. None. Each call writes an audit row.	`query`, `role`, `target_role`, `job_title`, `skills`, `keywords`, `location`, `lead_context`, `candidate_context`, `must_haves`, `exclusions`, `max_results`, `limit`	JSON object	mcp:tools:read 300 calls/min per connection (read bucket)
`agent_capability_candidates_show`	Read	Show a team-scoped candidate profile with optional reminders and conversation context. None. Each call writes an audit row.	`candidate_id`*, `reminders`, `conversations`	JSON object	mcp:tools:read 300 calls/min per connection (read bucket)
`agent_capability_reminders_list`	Read	List the team's human follow-up reminders. status: active (aliases open/pending), completed, cancelled, paused; kind=machine or all reaches scheduler rows. None. Each call writes an audit row.	`owner`, `due`, `status`, `kind`	`count`, `results`	mcp:tools:read 300 calls/min per connection (read bucket)
`agent_capability_campaigns_summary`	Read	Summarize a current-team campaign. None. Each call writes an audit row.	`sequence_id`*	JSON object	mcp:tools:read 300 calls/min per connection (read bucket)
`agent_capability_campaigns_next_actions`	Read	Return recommended next actions for a current-team campaign. None. Each call writes an audit row.	`sequence_id`*	JSON object	mcp:tools:read 300 calls/min per connection (read bucket)
`agent_capability_campaigns_test_runs`	Read	Report the latest Campaign Studio test run for a current-team campaign, and whether it is stale. None. Each call writes an audit row.	`sequence_id`*	JSON object	mcp:tools:read 300 calls/min per connection (read bucket)
`agent_capability_campaigns_deliverability`	Read	Summarize current-team campaign delivery issues by outreach channel and touchpoint status. None. Each call writes an audit row.	`sequence_id`*	JSON object	mcp:tools:read 300 calls/min per connection (read bucket)
`agent_capability_interviews_list`	Read	List interviews for a current-team campaign. None. Each call writes an audit row.	`sequence_id`*	`count`, `results`	mcp:tools:read 300 calls/min per connection (read bucket)
`agent_capability_interviews_show`	Read	Show a current-team interview with transcript, status, and a protected recording link when available. None. Each call writes an audit row.	`interview_id`*	JSON object	mcp:tools:read 300 calls/min per connection (read bucket)
`agent_capability_metrics_read`	Read	Read team or campaign metrics for the current team. None. Each call writes an audit row.	`sequence_id`	JSON object	mcp:tools:read 300 calls/min per connection (read bucket)
`agent_capability_activity_summary`	Read	Count chats, chat messages, interviews, Vapi calls, applications, and referrals over the past N days. None. Each call writes an audit row.	`days`, `sequence_id`, `group_by`	`scope`, `range`, `totals`, `by_day`	mcp:tools:read 300 calls/min per connection (read bucket)
`agent_capability_chats_summary`	Read	List team-scoped chats with candidate context, message counts, last activity, and short summaries. None. Each call writes an audit row.	`days`, `sequence_id`, `candidate_id`, `limit`	`count`, `results`	mcp:tools:read 300 calls/min per connection (read bucket)
`agent_capability_outreach_drafts`	Read	List draft outreach messages for a current-team campaign. None. Each call writes an audit row.	`sequence_id`*	`count`, `results`	mcp:tools:read 300 calls/min per connection (read bucket)
`agent_capability_integrations_summary`	Read	Summarize configured current-team integrations without exposing webhook URLs, secrets, or phone numbers. None. Each call writes an audit row.	none	JSON object	mcp:tools:read 300 calls/min per connection (read bucket)
`agent_capability_resumes_read`	Read	Read a candidate's structured resume (the draft in progress for this chat when there is one, edits included), available sources and saved client presets. Never changes the profile. None. Each call writes an audit row.	`candidate_id`*, `source_resume_id`, `source_artifact_id`, `template_id`	JSON object	mcp:tools:read 300 calls/min per connection (read bucket)
`agent_capability_resumes_preview`	Read	Propose a resume edit: pass only the changed sections; they are merged onto the draft in progress (or the source) server-side, which becomes the new draft. Returns the before/after of those sections and a preview fingerprint. No file is saved. None. Each call writes an audit row.	`candidate_id`, `source_resume_id`, `source_artifact_id`, `template_id`, `policy`, `template_config`, `expected_preview`, `sections`	JSON object	mcp:tools:read 300 calls/min per connection (read bucket)
`agent_capability_resumes_templates`	Read	List saved agency/client submission presets for this team. None. Each call writes an audit row.	none	JSON object	mcp:tools:read 300 calls/min per connection (read bucket)
`agent_capability_candidate_outreach_send_sms`	Sensitive write	Sends one SMS text message to a real person: the candidate's phone number on file in TalentPrism. A sent text cannot be undone or recalled. Before calling this, call agent_capability_candidate_outreach_send_sms_preview with the same arguments, show the user the candidate and the exact message, and get their approval. idempotency_key is required: repeating a call with the same key returns the original receipt and does not send again. Refused for candidates who replied STOP or are marked do-not-contact, and unless a TalentPrism admin turned on MCP sending for the team. Contact details in the result are masked. Use agent_capability_candidate_outreach_send_sms_verify to check whether it was delivered. Queues a real text message to the candidate's contact details on file. Cannot be undone. Audit row marked approved_by_mcp_client; the idempotency receipt is kept so a repeat returns it instead of sending again.	`candidate_id`, `message`, `sequence_id`, `idempotency_key`*	`status`, `candidate_id`, `channel`, `recipient`, `queued_count`, `message_preview`, `messaging_service_configured`, `receipt`, `evidence`, `idempotent_replay`	mcp:tools:read + mcp:tools:write, team setting on 60 sends/min per connection (write bucket)
`agent_capability_candidate_outreach_send_sms_preview`	Read	Read-only. Shows exactly what agent_capability_candidate_outreach_send_sms would send with these arguments: the candidate, the final message text, and any reason the send would be refused (STOP, do-not-contact, missing contact details, duplicate). Sends nothing. Contact details are masked. None. Shows the exact send without sending. Each call writes an audit row.	`candidate_id`, `message`, `sequence_id`, `idempotency_key`	JSON object	mcp:tools:read + mcp:tools:write, team setting on 300 calls/min per connection (read bucket)
`agent_capability_candidate_outreach_send_sms_verify`	Read	Read-only. Reports whether texts to this candidate in the last `days` days (default 7) were accepted by the carrier, failed, or are still queued. Pass the idempotency_key used for a send to narrow the report to that send. Sends nothing. None. Reports delivery. Each call writes an audit row.	`candidate_id`*, `idempotency_key`, `days`	JSON object	mcp:tools:read + mcp:tools:write, team setting on 300 calls/min per connection (read bucket)
`agent_capability_candidate_outreach_send_email`	Sensitive write	Sends one email to a real person: the candidate's email address on file in TalentPrism. The body is Markdown, rendered to HTML with a plain-text fallback. A sent email cannot be undone or recalled. Before calling this, call agent_capability_candidate_outreach_send_email_preview with the same arguments, show the user the candidate and the exact message, and get their approval. idempotency_key is required: repeating a call with the same key returns the original receipt and does not send again. Refused for candidates who replied STOP or are marked do-not-contact, and unless a TalentPrism admin turned on MCP sending for the team. Contact details in the result are masked. Queues a real email to the candidate's contact details on file. Cannot be undone. Audit row marked approved_by_mcp_client; the idempotency receipt is kept so a repeat returns it instead of sending again.	`candidate_id`, `subject`, `body`, `idempotency_key`	JSON object	mcp:tools:read + mcp:tools:write, team setting on 60 sends/min per connection (write bucket)
`agent_capability_candidate_outreach_send_email_preview`	Read	Read-only. Shows exactly what agent_capability_candidate_outreach_send_email would send with these arguments: the candidate, the final message text, and any reason the send would be refused (STOP, do-not-contact, missing contact details, duplicate). Sends nothing. Contact details are masked. None. Shows the exact send without sending. Each call writes an audit row.	`candidate_id`, `subject`, `body`*, `idempotency_key`	JSON object	mcp:tools:read + mcp:tools:write, team setting on 300 calls/min per connection (read bucket)

Rate limits and errors

Limits apply to tools/call per connection (OAuth grant or API key): 300 reads per minute and 60 sends per minute. initialize, ping and tools/list are not limited.

Code	HTTP	Meaning
`-32700` / `-32600`	200	Unparseable JSON / not a JSON-RPC 2.0 request.
`-32601`	200	Unknown method.
`-32602`	200	Unknown tool (including a send tool called without `mcp:tools:write`), or arguments that fail the tool's input schema, such as a missing `idempotency_key`.
`-32001`	401	Missing, invalid, expired or revoked credential. Carries a Bearer challenge.
`-32003`	403	`insufficient_scope` (no `mcp:tools:read`) or not allowed for this team.
`-32029`	429	Rate limit hit; wait `data.retry_after_seconds`.
`-32603`	200	Internal error.
`isError: true`	200	The tool ran and refused. `structuredContent.code` says why: `mcp_sends_disabled` (team setting off), `recipient_suppressed` (STOP / do-not-contact), `idempotency_key_required`, `capability_execution_failed`, `duplicate_write_in_flight` (same key still running), or a plain `message` such as an unknown candidate or missing phone number. Nothing was sent.