Skip to content
← Back to features
Model Context Protocol

The Peatch MCP server

Peatch exposes an MCP server. Any client that speaks the Model Context Protocol can connect to it, read the workspace a human approved (open roles, candidates, interviews, scoring and role briefs) and propose changes that only apply once that person confirms them in Peatch.

What it is

An MCP server is a standard way for an AI client to call a set of documented tools. Peatch implements the server half. Your client implements the other half, and the two agree on the protocol rather than on a bespoke integration.

Any compliant client works. Nothing on this page is specific to one vendor.

Endpoint

Address
https://peatch.ai/api/mcp
Protocol revision
2025-06-18
Transport
JSON-RPC 2.0 over HTTP POST, one object per request. No SSE, no streaming, no session header, and batch arrays are refused.
Methods
initialize, ping, tools/list, tools/call
Capabilities
Tools only. Resources and prompts are not implemented and are answered with method not found.
Maximum request body
64 KiB

Authorization

OAuth 2.1. There is no API key to paste and no client secret to store.

Discovery
Both metadata documents are served, so a client can find the authorization server from the resource alone. A rejected token comes back as 401 with a WWW-Authenticate challenge naming the metadata URL.
Client registration and PKCE
Dynamic client registration is open and unauthenticated, and issues public clients only. PKCE is mandatory and S256 only: a missing method or plain is refused, at the authorize endpoint and again at the token endpoint.
Lifetimes
The authorization code lives 60 seconds and is single use. The access token lives one hour. Refresh tokens rotate on every use but inherit the original expiry, so 30 days is an absolute ceiling from first consent, after which a human consents again. Reusing a consumed refresh token revokes the whole family.
One token, one workspace
The workspace is chosen by the human at consent and frozen into the token. It can never be influenced by a later request. Membership is re-checked on every call, so removing someone from the workspace stops their tokens at once, with no revocation step.
Revocation
There is no RFC 7009 endpoint. Revocation is a product action: a workspace admin removes the connection in the Peatch settings, which revokes the whole grant, access and refresh alike.

What is served

Twenty read tools and twenty-one write tools. The endpoint lists a tool only when its name is on a server-side allowlist and its declared class is read or write. A read runs at once. A write never runs on the call: it returns a pending action with a confirmation link, and runs only if the person who connected the client approves it in Peatch within 24 hours. The read tool get_pending_action then tells the client whether it was approved and what it returned.

  • Positions and their invite pipeline

    list_batches, get_batch_details, get_batch_candidates, analyze_batch, send_batch_invites, create_batch, update_batch, add_invite_to_batch

  • Pipeline and rejection analytics

    analyze_pipeline_health, analyze_rejection_patterns

  • Candidates and their dossiers

    get_candidate_details, compare_candidates, get_personality_profile, generate_candidate_brief, update_hiring_status, update_invite_hiring_status, create_job_requirement, add_to_shortlist, remove_from_shortlist, update_shortlist_status

  • Interview templates and scoring configuration

    list_scenarios, list_topics, get_scoring_agent, analyze_score_calibration, create_scenario, create_scenario_from_onboarding, update_scenario, delete_scenario, create_topic, update_topic, delete_topic, create_scoring_agent, update_scoring_agent

  • Scheduling

    check_calendar_status, list_scheduled_interviews, schedule_interview

  • Role briefs

    get_role_brief, get_role_brief_gaps, create_role_brief, update_role_brief

  • Follow-up on proposed changes

    get_pending_action

That count is what the door serves today, not a fixed contract. Tool names are stable identifiers and are not translated.

Rate limits

Four limits apply, and the first one is the one you will meet.

  • 60 requests per minute per client IP, before authentication. This is the binding limit for a single client.
  • 300 requests per minute per token, after authentication.
  • 60 tool calls per minute per token.
  • 240 tool calls per minute per workspace, shared across its tokens.

Windows are fixed and aligned to the clock, not sliding. A refused call returns 429; the machine-readable code is the field to key on, never the message, which is localized.

What it cannot do on its own

Every change waits for a person, enforced server side rather than left to the client.

  • It never sends an email, and adds no candidate until you confirm it.
  • It cannot change a score, a rubric or a role without your confirmation.
  • It cannot reject anyone without your confirmation, and never while that candidate is still in the interview.

A confirmation link expires after 24 hours, and the change applies only inside the workspace chosen at consent. Some tools call a language model to compose their answer, so a call is not free even when it changes nothing.

Connecting

  1. 1

    Register the server in your client

    Point your MCP client at the address above. Clients that support dynamic registration need nothing else.

  2. 2

    A human approves it

    Peatch shows which client is asking and which workspace it will reach. A workspace admin approves, and only then is a token issued.

  3. 3

    Call tools

    Run tools/list to see what this workspace exposes, then tools/call.

What it answers in practice

  • Which roles am I hiring for right now?
  • Who are the five strongest candidates on this role?
  • Where is my pipeline stalling, and since when?
  • What is missing from my role brief?

Answers come from the approved workspace, and every figure traces back to an interview a human can open.

Included in every plan

No add-on and no separate license. If you have a Peatch workspace, you can connect a client to it.

Try now