# Connect your own AI client to Zorlya.

> Connect Claude, ChatGPT, Claude Code or Cursor to your Zorlya account over OAuth 2.1 and MCP, with the permissions you choose. Endpoints, scopes and tools.

Source: https://zorlya.com/developers

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

POST 55 tools 5 resources 4 prompts

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

How a connection works

## Discover, connect, call, refresh.

1

### 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.

2

### 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.

3

### Call

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

4

### 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.

| 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 |

### Resources

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

profile resume tracks sources job/{job_id}

### Prompts

4 prompts your client can offer as starting points

review_matches assess_fit pipeline_review find_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](https://zorlya.com/privacy#ai-requests). [Security page](https://zorlya.com/security)

Endpoints

## Where a client goes.

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

| 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.

| 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.

| 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.

Terminal

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

Then run /mcp inside Claude Code to sign in. [Full guide](https://zorlya.com/guides/ai-clients/claude-code)

### 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](https://zorlya.com/guides/ai-clients/n8n).

Client guides

## Set it up in your client.

### Start here, then go deeper

1. [Find what Zorlya's MCP server offers](https://zorlya.com/guides/developers/what-the-mcp-server-offers)
2. [Sign in with OAuth by hand](https://zorlya.com/guides/developers/sign-in-with-oauth-by-hand)
3. [Make your first calls](https://zorlya.com/guides/developers/make-your-first-calls)
4. [Page results and handle errors](https://zorlya.com/guides/developers/page-results-and-handle-errors)
5. [Build a client in TypeScript](https://zorlya.com/guides/developers/build-a-client-in-typescript)
6. [Build a client in Python](https://zorlya.com/guides/developers/build-a-client-in-python)
7. [Test with the MCP Inspector](https://zorlya.com/guides/developers/test-with-the-mcp-inspector)
8. [Refresh tokens, narrow scopes and end a connection](https://zorlya.com/guides/developers/tokens-scopes-and-revocation)
9. [Secure a client that talks to Zorlya](https://zorlya.com/guides/developers/security-checklist-for-clients)

### Connect the tool you already use

1. [Connect Claude on the web and Claude Desktop](https://zorlya.com/guides/ai-clients/claude-ai-and-desktop)
2. [Connect Claude Code](https://zorlya.com/guides/ai-clients/claude-code)
3. [Connect ChatGPT](https://zorlya.com/guides/ai-clients/chatgpt)
4. [Connect Cursor to Zorlya](https://zorlya.com/guides/ai-clients/cursor)
5. [Connect VS Code with GitHub Copilot to Zorlya](https://zorlya.com/guides/ai-clients/vscode-copilot)
6. [Connect Windsurf to Zorlya](https://zorlya.com/guides/ai-clients/windsurf)
7. [Connect Zed to Zorlya](https://zorlya.com/guides/ai-clients/zed)
8. [Connect Gemini CLI to Zorlya](https://zorlya.com/guides/ai-clients/gemini-cli)
9. [Connect OpenAI Codex CLI to Zorlya](https://zorlya.com/guides/ai-clients/codex-cli)
10. [Connect stdio-only clients to Zorlya with mcp-remote](https://zorlya.com/guides/ai-clients/stdio-clients-with-mcp-remote)
11. [Connect n8n to Zorlya](https://zorlya.com/guides/ai-clients/n8n)
12. [Connect Zapier to Zorlya](https://zorlya.com/guides/ai-clients/zapier)
13. [Connect Make to Zorlya](https://zorlya.com/guides/ai-clients/make)
14. [Approve an AI app on the Connect page](https://zorlya.com/guides/ai-clients/what-you-approve-when-you-connect)