Developers & AI agents

What agents can do

• Evaluate candidates against a role - Score and rank the candidates on a configured job across hard skills, soft skills, culture fit, and team fit, and return an explainable shortlist with per-dimension scores and fit reasons.
• Reactivate the ATS talent pool - Search an organization indexed ATS pool for a newly opened role and surface previously-applied candidates who match, then run them through the same in-depth evaluation as fresh applicants.
• Build and save job scorecards - Turn a job description into a weighted, adjustable scorecard (criteria, skills, thresholds), review the AI-generated draft, and publish it so candidates are scored against objective criteria.
• Create and decide on candidates - Create jobs and candidates from documents, add CV attachments, assign candidates to jobs, and accept or reject applications with feedback that syncs back to the ATS.
• Inspect credits and usage - Read an organization credit balance, transaction ledger, and AI usage totals by task and model.

Connect over MCP

The MCP server uses the Streamable HTTP transport and requires an OAuth 2.1 access token. A human recruiter authorizes access; scopes are least-privilege.

1. Discover the protected-resource metadata (RFC 9728) to find the authorization server and MCP resource.
2. Dynamically register an OAuth client (RFC 7591).
3. Send the recruiter through the authorization-code flow with PKCE; they approve the consent screen.
4. Exchange the code for an access token at the token endpoint.
5. Call MCP tools with the bearer token; every call is scoped to the recruiter organization.

Endpoints

• MCP server (Streamable HTTP): https://app.peetchr.com/api/mcp
• Protected-resource metadata (RFC 9728): https://app.peetchr.com/.well-known/oauth-protected-resource/api/mcp
• Authorization server (RFC 8414): https://app.peetchr.com/.well-known/oauth-authorization-server
• Register a client (RFC 7591): https://app.peetchr.com/api/auth/mcp/register
• Authorize: https://app.peetchr.com/api/auth/mcp/authorize
• Token: https://app.peetchr.com/api/auth/mcp/token

Quickstart

Credentials are self-serve: a client registers itself and a recruiter approves the consent screen - no sales call is required to start.

1. Discover the auth requirements (an unauthenticated call returns 401 with the metadata URL)

   curl -i https://app.peetchr.com/api/mcp
   # HTTP/1.1 401 Unauthorized
   # WWW-Authenticate: Bearer resource_metadata="https://app.peetchr.com/.well-known/oauth-protected-resource/api/mcp"

2. Register a client (RFC 7591); the response includes a client_id and client_secret

   curl -X POST https://app.peetchr.com/api/auth/mcp/register \
     -H 'Content-Type: application/json' \
     -d '{"client_name":"my-agent","redirect_uris":["https://my-agent.example/callback"]}'

3. Send the recruiter through the authorization-code + PKCE flow; after they approve the consent screen, exchange the returned code for an access token (authenticating the client)

   curl -X POST https://app.peetchr.com/api/auth/mcp/token \
     -u '<CLIENT_ID>:<CLIENT_SECRET>' \
     -H 'Content-Type: application/x-www-form-urlencoded' \
     -d 'grant_type=authorization_code&code=<CODE>&code_verifier=<VERIFIER>&redirect_uri=<REDIRECT_URI>'

4. List and call tools (JSON-RPC 2.0)

   curl -X POST https://app.peetchr.com/api/mcp \
     -H 'Authorization: Bearer <ACCESS_TOKEN>' \
     -H 'Content-Type: application/json' \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

OAuth scopes

• openid - Authenticate the recruiter granting access (OpenID Connect).
• profile - Read the granting recruiter profile.
• email - Read the granting recruiter email.
• offline_access - Obtain a refresh token for long-running sessions.
• peetchr:recruiter - Read-only recruiter access: jobs, candidates, scorecards, credits.
• peetchr:recruiter:write - Write recruiter access: create jobs/candidates, generate and save scorecards, accept/reject candidates.
• peetchr:admin:recruiter - Peetchr-admin cross-organization recruiter actions (e.g. invite recruiters).
• peetchr:admin:sql - Peetchr-admin read-only SQL access. Highly privileged; rarely granted.

Tools

The live MCP server publishes the full, schema-typed catalog via tools/list. Key tools:

Machine-readable resources

• Agent guide (agents.md) - When to use Peetchr and how an agent connects, in prose.
• Agent auth walkthrough (auth.md) - Step-by-step OAuth credential flow for agents.
• OpenAPI specification - Machine-readable description of the OAuth + MCP entry points.
• MCP server card - Preview of the MCP server, transport, and tools.
• Agent Skills index - Machine-readable list of Peetchr agent capabilities.
• Agent card - Agent capability descriptor naming the MCP interface.
• MCP server endpoint - Streamable HTTP MCP transport (OAuth-protected).
• Developer & agent docs - Human-readable overview of the agent surface.

Constraints

• Peetchr is business software: every tool is OAuth-scoped to the recruiter organization that grants access and to its active ATS-linked accounts. There is no anonymous access.
• Peetchr evaluates and ranks candidates and syncs decisions to the ATS; it is not a job board and does not itself send offers or contracts.
• Write actions that change data or contact people (save scorecard, accept/reject a candidate, invite a recruiter) require explicit user confirmation.
• It is not a general web-search or chat assistant: tools act only on the granting organization jobs, candidates, and talent pool.
• Candidate scoring is asynchronous - creating or reconfiguring work enqueues evaluation rather than returning a score synchronously.