Use AI to manage your job board with Cavuno MCP

Connect Claude, Cursor, Codex, and other MCP clients to your Cavuno job board.

The Cavuno MCP server is a hosted Cloudflare Worker at mcp.cavuno.com. It lets AI agents like Claude, Cursor, and Codex drive the Cavuno API without any per-endpoint MCP tool registration — there is no npm package to install, just an HTTPS URL. The public Cavuno MCP repository contains connection examples and issue tracker details, plus registry metadata; the hosted server implementation is not published there.

Using Claude on the web, desktop or mobile? See Claude.

Connect Claude to your job board

In your Cavuno dashboard, open Settings → Integrations → MCP. This page has the server URL, a copy button, and an Open the MCP setup guide link.

Choose the steps for the Claude app you use:

Claude Desktop or Claude on the web, as a custom connector: Add https://mcp.cavuno.com/mcp as a custom connector. See Add the full MCP to Claude for the steps.
Claude Code: Run claude mcp add --transport http cavuno https://mcp.cavuno.com/mcp in your terminal. In Claude Code, run /mcp, select Cavuno, and follow the authentication steps to sign in and approve access.

You do not need to create an API key for this sign-in flow. If you use another AI client, see Connect a client.

How Cavuno MCP works

The authenticated Operator MCP endpoint at mcp.cavuno.com/mcp reaches the whole Cavuno API through two tools, regardless of how many REST endpoints exist:

search — runs JavaScript against the Cavuno OpenAPI spec for endpoint and schema discovery.
execute — runs JavaScript that calls the Cavuno API via a sandboxed loopback binding. Multiple calls can be chained in one execution; the final return value and captured console output flow back to the model.

This follows Cloudflare's “code mode” pattern. In Cloudflare's implementation, code-based discovery and execution reduced the tool context needed for a large API. Cavuno applies the same pattern with a two-tool surface; results still depend on the client, model, and task.

A few helper tools sit alongside them, such as search_docs, which searches Cavuno's documentation.

Choose a job board resource

Use the resource references when you need exact discovery prompts, write patterns, and safety boundaries:

Jobs — create, update, publish, pause, expire, duplicate, delete, and review job listings.
Companies — find, create, update, and delete company records.
Blog posts — audit, draft, update, and publish job board articles.
Blog authors and tags — manage article ownership and organization.
Taxonomies — manage categories, skills, and markets, and read canonical remote permits and timezones.
Settings — inspect and change supported job board configuration.
Domains — inspect domain state and verification data.
Google Search Console — query finalized search performance and inspect Google's indexed version of Board URLs.
Media — understand media metadata and the upload boundary.
Operations — follow asynchronous work to completion.
API keys — choose key permissions, including Builder access, and keep secrets out of MCP.
Audit logs — verify who changed what and when.
Usage and limits — inspect quotas before bulk work.
Authentication and security — choose OAuth or API keys and protect credentials.
Limitations — understand outbound network, files, and execution constraints.

See what you can do with it

The MCP cookbook starts with the outcome rather than API paths. Use it to post a job, publish or refresh blog content, research a content strategy, sync jobs from a careers page, or build a custom job scraper. The agent discovers the relevant endpoints and record IDs from Cavuno for you.

When a task also needs a browser, scraper, spreadsheet, or an unsupported third-party platform, that access comes from your AI client or another connector. Google Search Console is the exception documented above: after it is connected in Cavuno, MCP can use its native Board-bound performance and URL Inspection reads.

Connect a client

Add Cavuno to your MCP-aware editor. Clients that support remote MCP OAuth can open a browser so you can sign into Cavuno and approve access. Cavuno currently grants the single full_access scope. Configuration, token storage, and refresh behavior vary by client.

Claude Desktop

Remote MCP servers cannot be added directly through claude_desktop_config.json. See Claude to add Cavuno from Claude's connector directory, or add the full MCP as a custom connector.

Cursor

Edit ~/.cursor/mcp.json:

json

1{
2  "mcpServers": {
3    "cavuno": {
4      "url": "https://mcp.cavuno.com/mcp"
5    }
6  }
7}

Codex

Add the server to ~/.codex/config.toml (or the project-level .codex/config.toml for a trusted project):

toml

1[mcp_servers.cavuno]
2url = "https://mcp.cavuno.com/mcp"

ChatGPT Developer mode

Turn on Developer mode in ChatGPT, then add https://mcp.cavuno.com/mcp as a custom MCP app. ChatGPT uses a Client ID Metadata Document as its client_id when Cavuno advertises client_id_metadata_document_supported. Cavuno fetches that HTTPS document and treats ChatGPT as a public PKCE client. You do not paste a client ID or secret.

Claude Code

bash

1claude mcp add --transport http cavuno https://mcp.cavuno.com/mcp

Run /mcp in Claude Code, select Cavuno, and follow the authentication steps. See Claude Code's MCP guide for details.

Authentication

Two paths are supported. OAuth is the right choice for interactive use; an API key is the right choice for CI / automation that doesn't have a browser.

OAuth 2.1 (default)

The MCP spec runs the standard OAuth authorization-code flow with PKCE. On first connect, the client:

Fetches https://mcp.cavuno.com/.well-known/oauth-protected-resource/mcp and discovers the authorization server (api.cavuno.com/v1/oauth).
Reads authorization-server metadata. Clients that support Client ID Metadata Documents send an HTTPS metadata URL as client_id when client_id_metadata_document_supported is true. Other clients use dynamic registration at /v1/oauth/register.
Opens a browser to /v1/oauth/authorize for user consent. The minted JWT is bound to the Cavuno MCP resource (aud=https://mcp.cavuno.com/mcp).
Sends every subsequent request with Authorization: Bearer <jwt>.

The worker verifies the JWT’s issuer, audience, and signature through the authorization server’s JWKS before invoking a tool.

Cavuno treats CIMD clients as public PKCE clients (token_endpoint_auth_method: none). Dynamic registration also accepts client_secret_basic, client_secret_post, and public clients using none. Cavuno does not implement private_key_jwt. If a metadata document offers both none and private_key_jwt, Cavuno uses none.

API key (CI / scripts)

Mint a key in the Cavuno dashboard at Settings → Developer → API keys. Pass it as the bearer token — MCP clients that support custom request headers can attach it directly:

json

1{
2  "mcpServers": {
3    "cavuno": {
4      "url": "https://mcp.cavuno.com/mcp",
5      "headers": {
6        "Authorization": "Bearer cavuno_live_xxxxxxxxxxxxxxxx_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
7      }
8    }
9  }
10}

API keys beginning with cavuno_live_ skip the OAuth flow entirely—the worker passes them through unchanged.

The two tools

Both tools take a single argument: code, the source of an async () => … arrow function. The function runs in a fresh Cloudflare Dynamic Worker isolate per call — there is no shared state across invocations.

`search`

javascript

1// Tool: search
2// Args: { code: string }   // an async arrow function as a string
3//
4// Globals available inside the sandbox:
5//   spec — the full Cavuno OpenAPI document with $refs pre-resolved
6//
7// Network access: blocked. Use `spec` for everything.
8
9async () => Object.keys(spec.paths).slice(0, 10)

`execute`

javascript

1// Tool: execute
2// Args: { code: string }   // an async arrow function as a string
3//
4// Globals available inside the sandbox:
5//   cavuno.request({ method, path, body?, query?, headers? })
6//     -> { status: number, ok: boolean, data: unknown }
7//
8// Network access: only the loopback binding above. The agent's bearer
9// token is held by the parent worker and injected on every call —
10// never include an Authorization header in the code you write.
11
12async () => {
13  const r = await cavuno.request({ method: 'GET', path: '/usage' });
14  return r.data;
15}

The spec object that search sees is the same OpenAPI document published at api.cavuno.com/v1/openapi.json — also visible in the interactive API reference. execute can call authenticated Operator API endpoints that accept JSON or multipart form data. Endpoints that require a different authentication context remain outside this MCP surface.

Sandbox & limits

Outbound network from inside the sandbox is blocked (globalOutbound: null). The only way out is cavuno.request(…); calling fetch(…) throws.
No access to environment variables, file system, or persistent storage. Each invocation starts in a fresh isolate.
console.log/warn/error is captured and returned alongside the function's return value, so multi-step scripts can print intermediate state for debugging.
CPU and wall-clock budgets are bounded by the underlying Cloudflare Workers limits — keep individual execute calls under a few seconds.
cavuno.request accepts FormData for multipart endpoints such as POST /v1/media/upload. File bytes must already be available inside the invocation because the sandbox cannot read the local filesystem. Do not set Content-Type; Cavuno generates the multipart boundary.

Errors

When user code throws (or returns a rejected promise), the response is a structured error envelope rather than a tool failure. The captured console output is included so the agent can self-diagnose without re-running:

json

1{
2  "ok": false,
3  "error": "TypeError: Cannot read properties of null (reading 'id')",
4  "stack": "TypeError: Cannot read properties of null...",
5  "logs": [
6    { "level": "log", "args": ["company:", null] }
7  ]
8}

API-level errors (4xx / 5xx) come back from cavuno.request as { status, ok: false, data: { error: { code, message, requestId, details?, upgrade? } } } — the agent can branch on data.error.code rather than parsing strings.

Plan upgrade hints

When a request is refused because of your board's Cavuno plan (for example the active job limit, team seats, removing Cavuno branding or webhooks), the error carries an upgrade object. It names the capability that blocked the request, the cheapest self-serve plan that unlocks it, and the billing endpoints that start the upgrade:

json

1{
2  "error": {
3    "code": "jobs_quota_exceeded",
4    "message": "Active job limit reached. Upgrade your plan to publish more jobs.",
5    "requestId": "req_...",
6    "upgrade": {
7      "capability": "activeJobsLimit",
8      "requiredPlan": "basic",
9      "checkout": { "method": "POST", "path": "/v1/billing/checkout" },
10      "changePlan": { "method": "POST", "path": "/v1/billing/upgrade" }
11    }
12  }
13}

To act on it, the agent:

Calls GET /v1/billing/subscription. With no active subscription (for example during a trial), it uses checkout; with one, it uses changePlan.
Sends { "planKey": "<requiredPlan>" } to that endpoint.
Gives the returned url to you. Nothing is charged until a person confirms on that hosted page.

requiredPlan is left out when the cheapest plan can't be told from the error alone; the agent then picks a higher plan from the subscription response. Errors on your public job board (the Board API) never include upgrade hints. The CLI prints the hint as an upgrade: line under the error.

Reporting problems

Every Cavuno MCP endpoint (/mcp, /dev and /builder) has a submit_feedback tool. Agents call it when something prevented or complicated a task, even with a workaround: a missing capability, unclear or wrong documentation, a surprising response, an unhelpful error, a bug or slow performance. It is safe to call at any time and needs no confirmation from the user. Reports go to the engineers who build Cavuno.

The tool takes an Agent Feedback Protocol v0.1 report. type, goal and message are required; type is one of missing_capability, bug, unclear_documentation, unexpected_response, unhelpful_error, performance or other. Fill outcome, expected, suggestion, agent.name and agent.model when you know them.

json

1{
2  "type": "unhelpful_error",
3  "goal": "What you were trying to do",
4  "message": "What got in the way",
5  "endpoint": "execute",
6  "outcome": "degraded",
7  "agent": { "name": "my-agent", "model": "model-name" }
8}

Outside MCP, send the same JSON to the API:

bash

1curl https://api.cavuno.com/v1/feedback \
2  -X POST \
3  -H "Content-Type: application/json" \
4  -d '{ "type": "bug", "goal": "What you were trying to do", "message": "What got in the way" }'

Each account or visitor can send 20 reports every 5 minutes. Never include credentials, personal data or your user's private content. Send the report, then continue with the task; a failed report never blocks it.

Cookbook

Outcome-led recipes for completing common job board tasks with Cavuno MCP.

Reference

Resource-by-resource reference for the Cavuno Operator API capabilities available through MCP.