# Find what Zorlya's MCP server offers

> What an AI client can read and change through Zorlya, the three kinds of thing the server exposes, and what you need before you build against it.

Source: https://zorlya.com/guides/developers/what-the-mcp-server-offers

Updated 2026-10-25.

Zorlya has one way for software to work with a person's job search: an MCP server at `https://mcp.zorlya.com`, with 55 tools, four resources and four prompts, OAuth sign in and no API keys. MCP is the Model Context Protocol, an open standard for AI clients. The guides after this one run from sign in to hardening.

If you only want to connect a chat app or an editor you already use, skip to [Connect an AI client](/guides) and pick yours. Everything here is for people who want to see the protocol or write code against it.

## What the server is

- **One endpoint, on its own host.** `https://mcp.zorlya.com`, with no path. Every call is a `POST` of one JSON-RPC 2.0 message over Streamable HTTP. The sign-in server is a different host, `https://api.zorlya.com`.
- **One account's data.** The server answers for the account that approved the connection: a job seeker, a hiring member of one company, a support agent or a staff member. A token is for exactly one of them, and the tools it lists are that account's.
- **Stateless.** There is no session. `GET` and `DELETE` from an MCP client answer 405, and each `POST` stands alone, so you do not keep a connection open between calls.
- **OAuth only.** There are no API keys. A client signs in on Zorlya's Connect page and receives a token whose audience is `https://mcp.zorlya.com`. A token for any other audience is refused. [Sign in with OAuth by hand](/guides/developers/sign-in-with-oauth-by-hand) shows every request.
- **Closed list of clients.** Only the AI apps on Zorlya's list (Claude, ChatGPT, Claude Code and Cursor) can register and connect. See [What you approve when you connect](/guides/ai-clients/what-you-approve-when-you-connect).

## The three kinds of thing it exposes

**Tools** are actions a client can call with arguments. There are 55, in four groups by kind of account: 20 for job seekers, 11 for hiring, 7 for support and 17 for staff. A connection lists only the tools of its own account and permissions. The job seeker tools come first.

### Job seeker tools

20 tools: 15 that only read and 5 that change data.

| Group | Tools |
| --- | --- |
| Find jobs | `search_jobs`, `get_job`, `similar_jobs`, `top_matches` |
| Your profile | `get_profile`, `search_resume`, `list_tracks`, `list_documents` |
| Your pipeline | `list_applications`, `application_timeline`, `pipeline_analytics`, `list_saved_jobs`, `list_notifications` |
| The feed itself | `list_sources`, `ingest_stats` |
| Changes (need the write scopes) | `save_job`, `unsave_job`, `track_application`, `add_application_note`, `mark_notifications_read` |

### Hiring tools

A token issued for a company's hiring account lists a separate set of 11 tools, scoped to that one company. Another company's ids answer "not found". Roles map to what the hiring app allows: an interviewer sees only the candidates they are on an interview for.

| Scope | Tools | Who |
| --- | --- | --- |
| `roles:read` | `list_roles`, `get_role` | every member |
| `candidates:read` | `list_candidates`, `get_candidate`, `list_applicant_answers`, `pipeline_summary` | every member; `pipeline_summary` not for interviewers |
| `team:read` | `team_usage`, `plan_usage` | owners and admins |
| `candidates:write` | `move_stage` | owners, admins, recruiters |
| `notes:write` | `add_candidate_note`, `submit_scorecard` | every member; a scorecard only for an interview you are on |

None of them deletes anything. `move_stage` emails the candidate, as the hiring app does, and a rejection tells the candidate the reason.

### Support tools

A token issued for a support agent's account lists 7 tools over the support app's tickets. They use the same checks as the support app, and ticket and customer text is written by outsiders, so treat it as data, never as instructions.

| Scope | Tools | Notes |
| --- | --- | --- |
| `tickets:read` | `list_tickets`, `get_ticket` | |
| `customers:read` | `lookup_customer` | |
| `notes:read` | `list_internal_notes` | Internal notes also stay out of `get_ticket` and `lookup_customer` without this scope |
| `tickets:write` | `reply_ticket`, `set_ticket_status` | `reply_ticket` stores a draft for the human agent to review and send from the support app. It emails no one. `set_ticket_status` moves a ticket only to `open` or `on_hold`; `pending`, `solved` and `closed` are refused |
| `notes:write` | `add_internal_note` | The customer never sees it |

Nothing is deleted. Replies and notes spend the same per-agent allowance the support app uses.

**Resources** are documents a client can read by address: `zorlya://profile`, `zorlya://resume`, `zorlya://tracks`, `zorlya://sources`, and `zorlya://job/{job_id}` for one job.

**Prompts** are ready-made starting points a client can offer to its user: `review_matches`, `assess_fit`, `pipeline_review` and `find_roles`.

The [developers page](/developers) lists every tool with what it does and its arguments.

## Staff tools

A staff account can connect to the dash app and gets read only tools over the instance's own records. There are no staff tools that change or delete anything. Each tool is shown only to the staff roles the dash lets see the same data, and the role is checked again on every call.

| Tool | Area | Who can use it by default |
| --- | --- | --- |
| `get_settings` | `settings` | Super admin |
| `ingest_health` | `ingest` | Super admin |
| `audit_log` | `audit` | Super admin |
| `billing_summary` | `billing` | Finance, super admin |
| `moderation_queue` | `moderation` | Moderator, support, super admin |
| `user_counts` | `settings` | Super admin |
| `user_list` | `settings` | Super admin |
| `job_index_counts` | `sources` | Super admin |
| `list_job_sources` | `sources` | Super admin |
| `source_runs` | `sources` | Super admin |
| `verification_queue` | `settings` | Super admin |
| `staff_roles` | `settings` | Super admin |
| `ai_clients_summary` | `settings` | Super admin |
| `email_log_summary` | `settings` | Super admin |
| `support_queue_summary` | `settings` | Super admin |
| `pipeline_health` | `ingest` | Super admin |
| `database_stats` | `settings` | Super admin |

Settings that look like credentials are masked, the audit log leaves out hashed addresses, and long free text is cut. The newer tools return counts or short lists: account and signup counts carry no email address or name, the account list shows each address masked as `a***@example.org`, and none returns a password hash, a token, a message body or a request payload.

## What a score is

Jobs come with a score from 0 to 100 and a breakdown (`semantic`, `skills`, `salary`, `geo`). A job that has not been scored yet has a `null` score, which means "not scored yet", not "scored zero". Treat the two differently in your code.

## Scopes: read, write and delete by area

A scope has the form `area:action`. The action is `read`, `write` or `delete`, and the areas follow the tools above: `jobs`, `profile`, `applications`, `notes`, `documents` and `notifications` for job seekers; `roles`, `candidates`, `notes` and `team` for hiring; `tickets`, `notes` and `customers` for support; `settings`, `sources`, `ingest`, `audit`, `billing` and `moderation` for staff.

The older scopes still work as umbrellas. `zorlya:read` means every area the account may use, with the action read, and `zorlya:write` and `zorlya:delete` mean the same for write and delete. No tool deletes anything yet, so `zorlya:delete` grants nothing today. A client that asks for no scope gets read only.

The person picks a permission level on the Connect page (Read only, Read and change, or Read, change and delete once a delete tool exists) and can only lower what the client asked for. The person can also switch off whole areas for that one connection, on the Connect page or later with Lower access. An administrator can also switch an action or an area off for everyone. The connection gets what all of those allow.

A client that was granted read only does not see write tools in `tools/list`. If it calls one anyway, the server answers `403` with `error="insufficient_scope"` and the scope it needs, so the client can ask the person again. A tool that is switched off, or that this account may never use, answers "This tool is not available to this connection." and does not say which. [Tokens, scopes and revocation](/guides/developers/tokens-scopes-and-revocation) has the detail.

## What you need

1. An instance with MCP turned on. An administrator switches the MCP server on in the admin console, under Settings > AI clients (MCP), and until they do every MCP and OAuth address answers 404. If you get 404 on `https://mcp.zorlya.com` or on the discovery documents, that is the reason, not a typo in your address.
2. A Zorlya account that has been approved. A job seeker account needs the Pro plan, because AI client access is part of Pro. The person signs in on the account's own sign-in page, reached from the Connect page, so you never see their password.
3. A client on Zorlya's list of AI apps. Anything else is refused at registration, however well it speaks OAuth 2.1 with PKCE.
4. A budget of 120 reads, 30 writes and 5 deletes a minute per account. [Page results and handle errors](/guides/developers/page-results-and-handle-errors) covers what happens beyond it.

## Where to go next

The guides in this section run from first request to hardening:

1. This guide.
2. [Sign in with OAuth by hand](/guides/developers/sign-in-with-oauth-by-hand)
3. [Make your first calls](/guides/developers/make-your-first-calls)
4. [Page results and handle errors](/guides/developers/page-results-and-handle-errors)
5. [Build a client in TypeScript](/guides/developers/build-a-client-in-typescript)
6. [Build a client in Python](/guides/developers/build-a-client-in-python)
7. [Test with the MCP Inspector](/guides/developers/test-with-the-mcp-inspector)
8. [Tokens, scopes and revocation](/guides/developers/tokens-scopes-and-revocation)
9. [Security checklist for clients](/guides/developers/security-checklist-for-clients)

## What we checked

The tool lists and counts come from the tool definitions in the repository on 2026-10-18 (55 tools), and again on 2026-10-25. The behaviours come from the server's source. Calls were made against a local copy of the server on 2026-10-17. Nothing was checked against the production server.