MCP server / OAuth 2.1

Connect your own AI client to Zorlya.

Zorlya runs an MCP server at mcp.zorlya.com. Your AI client signs in with OAuth and works with your jobs, applications and profile, with only the permissions you approve. Hiring, support and staff accounts have their own tools. For a job seeker account, AI client connections are part of the Pro plan.

Quick start See the tools Read the guides

MCP address

https://mcp.zorlya.com

POST55 tools5 resources4 prompts

Transport: streamable HTTP. Every call is a POST to the endpoint.

How a connection works

Discover, connect, call, refresh.

Discover

The MCP server answers 401 and names its resource metadata at /.well-known/oauth-protected-resource. That names the authorization server, api.zorlya.com, whose metadata is at /.well-known/oauth-authorization-server.

Connect

A Connect page names the client. You choose the account and the permission level, then sign in to that account. Changing data asks for your password again. PKCE with S256 is required, and there is no implicit grant.

Call

Each request to mcp.zorlya.com carries an access token for that audience, so every call runs as you.

Refresh or revoke

Refresh tokens rotate on every use. You can disconnect any client; the connection email links to your connections.

Protocol versions accepted: 2026-07-28, 2025-06-18, 2025-03-26, 2024-11-05 and 2024-10-07. Access tokens last 1 hour, refresh tokens 30 days and rotate on use.

Tools

What a client can do.

A connection lists only the tools of the account it was approved for. Tools that change data need a write scope, and no tool deletes anything. An asterisk marks a required argument.

Tools
Tool	Account	Arguments	What it does	Scope
`search_jobs`	Job seeker	query, location, remote_only, min_score, limit, cursor	Search jobs by title, company or description	jobs:read
`get_job`	Job seeker	job_id*	One job in full, with its description and match breakdown	jobs:read
`similar_jobs`	Job seeker	job_id*, limit	The jobs closest in meaning to a given one	jobs:read
`get_profile`	Job seeker	none	A summary of your profile	profile:read
`top_matches`	Job seeker	limit, min_score, cursor	Your highest-scoring jobs, best first	jobs:read
`list_applications`	Job seeker	stage, limit, cursor	Your application pipeline	applications:read
`list_tracks`	Job seeker	none	The role tracks used to score jobs, with their weights	applications:read
`list_saved_jobs`	Job seeker	limit, cursor	Jobs you bookmarked	jobs:read
`list_notifications`	Job seeker	unread_only, limit, cursor	Recent notifications, newest first	notifications:read
`search_resume`	Job seeker	query*, limit, cursor	Search your embedded resume by text	documents:read
`application_timeline`	Job seeker	application_id*	The history of one application: stage moves, notes, emails	applications:read
`pipeline_analytics`	Job seeker	none	Funnel numbers for your pipeline	applications:read
`list_documents`	Job seeker	limit	Generated cover letters and stored resume versions	documents:read
`list_sources`	Job seeker	none	Every job source, grouped by tier	jobs:read
`ingest_stats`	Job seeker	none	How many jobs are stored, and where they came from	jobs:read
`save_job`	Job seeker	job_id*	Bookmark a job	jobs:write
`unsave_job`	Job seeker	job_id*	Remove a job from your saved list	jobs:write
`track_application`	Job seeker	job_id*, stage, notes	Start tracking a job, or move it to another stage	applications:write
`add_application_note`	Job seeker	application_id, note	Add a note to an application's timeline	notes:write
`mark_notifications_read`	Job seeker	none	Mark every notification as read	notifications:write
`list_roles`	Hiring	status, limit, cursor	The company's roles, newest first	roles:read
`get_role`	Hiring	role_id*	One role in full: description, requirements, pay range, openings	roles:read
`list_candidates`	Hiring	role_id, stage, limit, cursor	Applications for the company's roles, newest first	candidates:read
`get_candidate`	Hiring	application_id*	One application in full: profile, resume excerpt, timeline	candidates:read
`list_applicant_answers`	Hiring	application_id*	What the applicant wrote when applying	candidates:read
`pipeline_summary`	Hiring	days, role_id	Totals and the funnel from applied to hired	candidates:read
`team_usage`	Hiring	limit, cursor	Who is on the team and how many seats are used	team:read
`plan_usage`	Hiring	none	The company's plan and what it has used against its limits	team:read
`move_stage`	Hiring	application_id, stage, reason, note	Move a candidate to another stage. The candidate is emailed	candidates:write
`add_candidate_note`	Hiring	application_id, text	Add an internal note to a candidate. The candidate never sees it	notes:write
`submit_scorecard`	Hiring	interview_id, ratings, recommendation*, notes	Submit your own scorecard for an interview you are on	notes:write
`list_tickets`	Support	view, status, assignee, priority, who, category, tag, q, sort, limit, cursor	The support queue, as the support app shows it	tickets:read
`get_ticket`	Support	ticket*, max_messages	One ticket in full, with its thread and timeline	tickets:read
`lookup_customer`	Support	query, customer_id, limit	Who has written to support, by exact email or company domain	customers:read
`list_internal_notes`	Support	ticket*, limit, cursor	The internal notes on a ticket	notes:read
`reply_ticket`	Support	ticket, body, status_after	Save a draft reply for the human agent to review and send from the support app. Nothing is emailed	tickets:write
`set_ticket_status`	Support	ticket, status	Move a ticket to open or on_hold. Other statuses are refused over MCP	tickets:write
`add_internal_note`	Support	ticket, body	Add an internal note the customer never sees	notes:write
`get_settings`	Staff	none	Every setting group, with values that look like credentials masked	settings:read
`ingest_health`	Staff	only_failing	How each job source is doing, worst first	ingest:read
`audit_log`	Staff	actor, action, limit, cursor	Who did what in the dash and the apps, newest first (super admins)	audit:read
`billing_summary`	Staff	none	The billing picture the dash shows: provider, customers and plans	billing:read
`moderation_queue`	Staff	status, kind, limit, cursor	Reports filed against roles, companies, threads and people	moderation:read
`user_counts`	Staff	days	Accounts and signups by day, kind, sign-in method and source, as counts with no person in them	settings:read
`user_list`	Staff	kind, state, limit, cursor	A page of accounts with minimal fields and the address masked	settings:read
`job_index_counts`	Staff	none	Companies and live jobs in the index, by source and by country	sources:read
`list_job_sources`	Staff	tier	Every registered job source with its interval, job counts and latest run	sources:read
`source_runs`	Staff	source_id, status, limit, cursor	The run history of one job source, or of all of them	sources:read
`verification_queue`	Staff	status, limit, cursor	Employer verification requests, without who asked	settings:read
`staff_roles`	Staff	none	The staff team with masked addresses, and what each role may do (super admins)	settings:read
`ai_clients_summary`	Staff	days	AI clients, live connections and a summary of recent requests, with no payloads	settings:read
`email_log_summary`	Staff	days	Emails sent, skipped and failed, by day and template, as counts (super admins)	settings:read
`support_queue_summary`	Staff	none	Support tickets by status, and what is waiting, as counts (super admins)	settings:read
`pipeline_health`	Staff	none	Whether the background work is running, and failures in the last day	ingest:read
`database_stats`	Staff	none	Database size and row counts of the main tables	settings:read

Resources

5 read-only resources under zorlya://, which describe a job seeker's data

profileresumetrackssourcesjob/{job_id}

Prompts

4 prompts your client can offer as starting points

review_matchesassess_fitpipeline_reviewfind_roles

Security of access

Tokens are stored only as SHA-256 digests, last an hour, work only on mcp.zorlya.com and stop working the moment you revoke the client. Requests made through AI apps are logged; see the privacy policy. Security page

Endpoints

Where a client goes.

The MCP server is on mcp.zorlya.com; sign-in and tokens are on api.zorlya.com.

Endpoints
Host	Path	Method	What it does
mcp.zorlya.com	`/.well-known/oauth-protected-resource`	GET	Names the MCP resource and its authorization server (RFC 9728). /.well-known/oauth-protected-resource/mcp is an alias of the same document
api.zorlya.com	`/.well-known/oauth-authorization-server`	GET	Lists the endpoints, scopes and the S256 challenge method (RFC 8414). The issuer is https://api.zorlya.com
api.zorlya.com	`/oauth/register`	POST	Registers a client (RFC 7591). Only the return addresses of AI apps on the list are accepted
api.zorlya.com	`/oauth/authorize`	GET	Starts the Connect page and the sign-in. PKCE with S256 is required. The optional resource parameter (RFC 8707) must be the MCP address
api.zorlya.com	`/oauth/token`	POST	Trades a code for tokens, or a refresh token for a new pair
api.zorlya.com	`/oauth/revoke`	POST	Ends a grant. A refresh token ends the whole grant
mcp.zorlya.com	`/`	POST	The MCP endpoint: one JSON-RPC message per request. GET and DELETE from an MCP client answer 405

Scopes

Only what you approve.

Scopes
Scope	Grants
`area:read`	Read in one area, such as jobs:read, candidates:read or tickets:read
`area:write`	Change data in one area, such as applications:write or notes:write
`area:delete`	Delete in one area. No tool deletes yet, so this grants nothing today
`zorlya:read`	Umbrella: every area of the account, read
`zorlya:write`	Umbrella: every area of the account, write
`zorlya:delete`	Umbrella: every area of the account, delete

A client that asks for nothing in particular gets read only. You choose the permission level on the Connect page, and administrators can switch actions and areas off. A read-only connection that calls a write tool gets 403 with insufficient_scope.

Per account, a minute.

Limits
Limit	Value
Reads on mcp.zorlya.com	120 a minute per account
Writes	30 a minute per account
Deletes	5 a minute per account
Sign-in and refresh	10 a minute per address

A request over the read limit, or sign-in over its limit, answers 429. A write or delete over its limit returns a tool error that says how long to wait.

Quick start

Add the server to your client.

Settings, then Connectors, then Add custom connector (Claude on the web and Claude Desktop)

https://mcp.zorlya.com

Paste the address, then sign in to Zorlya when Claude asks. Full guide

Terminal

claude mcp add --transport http zorlya https://mcp.zorlya.com

Then run /mcp inside Claude Code to sign in. Full guide

Custom MCP server in ChatGPT

https://mcp.zorlya.com

ChatGPT supports dynamic client registration. Where the setting lives has changed, so follow the guide, which says what could not be confirmed. Full guide

.cursor/mcp.json or ~/.cursor/mcp.json

{
  "mcpServers": {
    "zorlya": {
      "url": "https://mcp.zorlya.com"
    }
  }
}

Then open Cursor settings and sign in to Zorlya when it asks. Full guide

.vscode/mcp.json

{
  "servers": {
    "zorlya": {
      "type": "http",
      "url": "https://mcp.zorlya.com"
    }
  }
}

Not on Zorlya's list of AI apps yet. Zorlya registers only listed apps, so this connection is refused until the app is added or it uses a listed app's return address.Then start the server from the editor and sign in when it asks. Full guide

mcp_config.json

{
  "mcpServers": {
    "zorlya": {
      "serverUrl": "https://mcp.zorlya.com"
    }
  }
}

Not on Zorlya's list of AI apps yet. Zorlya registers only listed apps, so this connection is refused until the app is added or it uses a listed app's return address.The file location differs by install; the guide says what its documentation covers. Full guide

Zed settings.json

{
  "context_servers": {
    "zorlya": {
      "url": "https://mcp.zorlya.com"
    }
  }
}

Not on Zorlya's list of AI apps yet. Zorlya registers only listed apps, so this connection is refused until the app is added or it uses a listed app's return address.Zed starts the sign-in when no Authorization header is set. Full guide

Terminal

gemini mcp add --transport http zorlya https://mcp.zorlya.com

Not on Zorlya's list of AI apps yet. Zorlya registers only listed apps, so this connection is refused until the app is added or it uses a listed app's return address.Then run /mcp auth zorlya inside Gemini CLI to sign in. Full guide

~/.codex/config.toml

[mcp_servers.zorlya]
url = "https://mcp.zorlya.com"

Not on Zorlya's list of AI apps yet. Zorlya registers only listed apps, so this connection is refused until the app is added or it uses a listed app's return address.Then run: codex mcp login zorlya Full guide

Your client's MCP config file, for a client that only runs local servers

{
  "mcpServers": {
    "zorlya": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.zorlya.com"
      ]
    }
  }
}

Not on Zorlya's list of AI apps yet. Zorlya registers only listed apps, so this connection is refused until the app is added or it uses a listed app's return address.mcp-remote opens the sign-in in your browser and keeps the tokens in ~/.mcp-auth. Full guide

Server URL

https://mcp.zorlya.com

Not on Zorlya's list of AI apps yet. Zorlya registers only listed apps, so this connection is refused until the app is added or it uses a listed app's return address.The client discovers the OAuth server from the resource metadata. Only apps on Zorlya's list can register.

Transport

Streamable HTTP. Every call is a POST to the endpoint.

Read before you rely on it

Each block is what the client's own documentation shows, read on 2026-10-17. None was tried against Zorlya. Automation tools (n8n, Zapier, Make) have no config block: see their guides.