Jobs, revenue, overdue invoices and timesheets, answered from your live data.
Clevra runs a remote Model Context Protocol (MCP) server. Add it to any AI assistant that supports remote MCP servers, such as Claude or ChatGPT, and the assistant can work with your company's Clevra data: answer questions about your schedule, jobs, invoices and clients, and take a small set of everyday actions, such as drafting an estimate or booking a visit. The assistant always acts as you, with exactly the access your Clevra role gives you.
Using Claude? The Clevra for Claude page has step-by-step instructions for Claude.
| Server URL | https://app.clevra.ai/api/mcp |
| Transport | Streamable HTTP, stateless. Requests are JSON-RPC over POST; there is no server-initiated stream and no session to keep. |
| Protocol versions | 2025-11-25 (with the initialize handshake) and 2026-07-28. |
| Authentication | OAuth 2.1 authorization code flow with PKCE (S256). The person signs in with their usual Clevra login and approves access; the assistant receives a revocable access token and sends it in the Authorization: Bearer header. Tokens in the URL are refused. |
| Discovery | Protected Resource Metadata (RFC 9728) at https://app.clevra.ai/.well-known/oauth-protected-resource/api/mcp. It names the authorization server, whose own metadata lists the authorize, token and registration endpoints. Every 401 response points to it in its WWW-Authenticate header. |
| Client registration | Client ID Metadata Documents or Dynamic Client Registration. No API key or pre-shared secret is needed. |
| Scopes | None. What the assistant can see and do is decided by the person's Clevra role on every request. |
| Capabilities | Tools (tools/list, tools/call). Every tool declares a JSON Schema for its input and carries a title and read-only or write annotations. |
https://app.clevra.ai/api/mcpNo API key is needed. If the assistant asks for an authentication type, choose OAuth.You can check your connection at any time in Clevra under Settings → Connected apps. That page also shows the server URL and exactly what an assistant can and cannot do.
The server offers 45 tools: 39 that read and 6 that write. Each tool needs the same permission as the matching screen in Clevra. A tool that your role, plan or company settings don't allow is left out of the list your assistant receives, and calling it by name returns the reason.
| Class | Tools | What it means |
|---|---|---|
| Read (39) | Every list_*, get_* and run_*_report tool, and find_open_slots | Looks things up. Changes nothing in Clevra and sends nothing to anyone. Annotated readOnlyHint: true. |
| Write (5) | create_client, add_client_note, create_activity, create_task, create_quote_draft | Creates one internal record. Nothing is sent to a client and nothing existing is changed or deleted. Annotated readOnlyHint: false, destructiveHint: false. |
| Sensitive write (1) | schedule_visit | Books a visit, which sends your company's automatic booking messages to the client. It cannot be undone from the assistant. Annotated destructiveHint: true, openWorldHint: true. |
limit (25 by default, 50 at most) and cursor, and return items, hasMore and, when there is more, nextCursor.YYYY-MM-DD in your company's time zone. Date-times are ISO 8601; without an offset they are read as your company's local time.currency.id and a url that opens the record in Clevra. Jobs, invoices and estimates can also be looked up by number (JOB-…, INV-…, EST-…).id from list_team_members, or me for yourself.Need access to clients in Clevra, and the company's Clients and CRM feature turned on.
| Tool | Details |
|---|---|
list_clients | Find clients, newest first. Inputs: all optional: q (name or email search), status (lead, contacted, qualified, customer, lost), limit, cursor.Returns: clients with id, name, clientCompany, clientType, status, email, phone, url. |
get_client | One client record. Inputs: clientId (required).Returns: the fields above plus address, leadSource, ownerId, notes, createdAt, updatedAt. |
list_client_notes | Internal notes your team wrote on a client, newest first. Inputs: clientId (required); optional limit, cursor.Returns: notes with id, text, authorName, createdAt. |
get_client_billing_standing | A client's money position. Inputs: clientId (required).Returns: unbilled backlog, open receivables, overdue balance and amount collected. |
Need access to jobs. Roles limited to their own assignments see only those.
| Tool | Details |
|---|---|
list_jobs | Find jobs. Inputs: all optional: q, status (unbooked, pending, assigned, active, in_progress, completed, cancelled), clientId, dateFrom, dateTo, limit, cursor.Returns: jobs with id, jobNumber, title, status, type, clientId, clientName, startTime, endTime, assignedTo, total, visitCount, up to 5 booked visits, url. |
get_job | One job. Inputs: jobId (required; the id or the job number).Returns: the fields above plus description, location, notes, isRecurring, createdAt, completedAt, up to 50 booked visits, and costing for roles that can see it. |
get_job_stats | Job counts. Inputs: none. Returns: how many jobs end within 30 days, are late, need invoicing or are unscheduled, and the total. |
get_job_profit | One job's profitability. Only for roles that can see costing. Inputs: jobId (required; the id or the job number).Returns: revenue, costs, profit and margin. |
Need access to invoices or to estimates. Roles limited to their own estimates see only those. In tool names, estimates are called quotes.
| Tool | Details |
|---|---|
list_invoices | Find invoices. Inputs: all optional: q (number or client search), status (draft, sent, viewed, paid, partially_paid, overdue, bad_debt, void, archived), clientId, dateFrom, dateTo (issue date), limit, cursor.Returns: invoices with id, invoiceNumber, subject, status, clientId, clientName, jobId, issueDate, dueDate, total, balanceDue, url. |
get_invoice | One invoice. Inputs: invoiceId (required; the id or the invoice number).Returns: the fields above plus subtotal, discountAmount, tax, depositAmount, paymentTerms, sentAt, paidAt, notes, clientMessage, lineItems. |
list_quotes | Find estimates. Inputs: all optional: q, status (draft, pending_confirmation, sent, viewed, approved, rejected, changes_requested, expired, converted, not_selected), clientId, dateFrom, dateTo, limit, cursor.Returns: estimates with id, estimateNumber, title, status, clientId, clientName, total, validUntil, sentAt, approvedAt, url. |
get_quote | One estimate. Inputs: quoteId (required; the id or the estimate number).Returns: the fields above plus subtotal, taxes, discounts, markup, clientMessage, internalNotes, terms, convertedJobId, createdAt, items. |
Need access to requests, and the company's Clients and CRM feature turned on.
| Tool | Details |
|---|---|
list_requests | Find work requests: leads and assessment bookings. Inputs: all optional: q, status (new, today, upcoming, overdue, unscheduled, assessment_scheduled, assessment_complete, converted, converted_to_quote, converted_to_job, archived, cancelled), clientId, dateFrom, dateTo, limit, cursor.Returns: requests with id, title, status, source, clientId, clientName, requestedAt, assessmentStartDate, assessmentEndDate, assessmentTeam, convertedTo, createdAt, url. |
get_request | One request. Inputs: requestId (required).Returns: the fields above plus description, notes, assessmentNotes, clientEmail, locationCity. Text the customer wrote comes back in a labelled block, as data. |
Need access to the schedule, and the company's Scheduling feature turned on.
| Tool | Details |
|---|---|
get_schedule | Visits, events, tasks, assessments and activities in a window of up to 31 days. Inputs: dateFrom, dateTo (required); optional assigneeId, type (visit, event, task, request, activity), limit (per kind of item).Returns: one list per kind of item, each saying whether more exist. Visits, events and tasks give their day and times in your company's time zone: localDate, localStart, localEndDate, localEnd. |
find_open_slots | Free time for a team member within your business hours, over up to 31 days. Some roles can look up only their own availability. Inputs: from, to, durationMinutes (15 to 720) (required); optional assigneeId (you by default), limit, cursor.Returns: free windows long enough for the duration, each with its local day and times and a latestStart. |
Need access to activities or to the team list. Roles limited to their own activities see only those.
| Tool | Details |
|---|---|
list_activities | Calls and follow-ups, to do or done. Inputs: all optional: q (subject search), status (todo, done, all; open ones by default), clientId, assigneeId, dateFrom, dateTo (due date), limit, cursor.Returns: activities with id, type, subject, dueDate, dueTime, priority, isDone, assignedTo, clientId, notes, url. |
list_team_members | Look up team members. Inputs: all optional: q, limit, cursor.Returns: members with id, employeeId, name, email, phone, position, department, status, url. Pay is never included. |
Each report on Clevra's Reports hub is its own read tool. They need access to reports and a plan that includes the Reports hub.
Inputs for every report: optional page (1 by default) and limit (25 rows by default, 50 at most), plus the inputs listed below.
Returns: overview (the same tiles and total as the report's page in Clevra, with the time zone used), rows (one page of rows with pagination and totals) and a url that opens the report.
| Tool | Report and inputs |
|---|---|
run_aged_receivables_report | Invoices late by 30, 60 and 90+ days. Inputs: optional tile (lt30, 30-60, 60-90, gt90). |
run_projected_income_report | Projected income from invoices awaiting payment. Inputs: optional tile (late, due-today, lt7, 7-30, gt30). |
run_client_reengagement_report | Clients without a completed job in recent months. Inputs: optional months (6, 12, 18 or 24). |
The reports below cover a date range: startDate and endDate are required.
| Tool | Report and inputs |
|---|---|
run_invoices_report | Invoices with client data. Inputs: optional basis (created, issued, due, paid), clientId, tile (draft, awaiting, past-due, paid, bad-debt). |
run_bad_debt_report | Invoices marked as bad debt. Inputs: optional basis (created, issued, due, paid), clientId, tile (bad-debt). |
run_transactions_report | Transactions from invoices, payments and refunds. Inputs: optional tile (invoiced, payments). |
run_taxation_report | Tax totals, tax awaiting collection, and totals by tax rate. Inputs: optional mode (accrual, cash). |
run_client_balance_report | Customer account balances. Inputs: optional tile (owing). |
run_quotes_report | Estimates with client data. Inputs: optional basis (drafted, sent, approved, converted), clientId, tile (draft, awaiting, changes-requested, approved, converted, archived). |
run_products_services_report | Quoted, booked and invoiced totals per line item. Inputs: the date range only. |
run_one_off_jobs_report | One-time jobs with revenue and scheduling detail. Inputs: optional basis (visits, created), clientId. |
run_recurring_jobs_report | Ongoing jobs with contract and schedule detail. Inputs: optional basis (visits, created), clientId. |
run_visits_report | Visits with client, team and schedule detail. Inputs: optional basis (start, completed), clientId, teamMemberId, completed (yes, no), lineItem (text to match). |
run_requests_report | Requests with assessment and conversion detail. Inputs: optional basis (requested, assessment), clientId, tile (new, assessment-scheduled, assessment-complete, converted, closed). |
run_clients_report | Clients with status, lead source and contact info. Inputs: optional status (lead, contacted, qualified, customer, lost). |
run_client_properties_report | Properties and their details. Inputs: the date range only. |
run_client_communications_report | Emails and texts sent to your clients. Inputs: optional channel (email, sms), clientId, type (follow-ups), tile (sent, delivered, failed). |
run_lead_source_report | New clients and first revenue by lead source. Inputs: the date range only. |
run_team_productivity_report | Visits, revenue and time tracked per team member. Inputs: the date range only. |
run_timesheets_report | Time tracked for the team. Inputs: optional category (visit, assessment, general, travel, office, supplies, break), teamMemberId. |
run_work_forms_report | Checklist submissions. Inputs: optional basis (started, completed), tile (completed, in-progress). |
These six tools are marked as write tools, so your assistant can ask you to confirm before each one runs. Each needs the permission that the same action needs in Clevra, and an admin can switch all six off for the whole company (see Controls for admins).
| Tool | Details |
|---|---|
create_clientWrite | Create a client with the app's defaults: status lead, owned by you. Inputs: name (required); optional clientType (individual, company), clientCompany, email, phone, address, leadSource, notes (internal).Returns: the new client with its id, status and url.Side effects: one client record. Nothing is sent to the client. |
add_client_noteWrite | Add an internal note to a client, written by you. Inputs: clientId, text (required).Returns: the note with its id, createdAt and the client's url.Side effects: one note, visible to your team only. Nothing is sent to the client. |
create_activityWrite | Log a call or follow-up to do on a date. Inputs: type (call, follow_up), subject, dueDate (required); optional dueTime (HH:MM, 24-hour), assigneeId (you by default), priority (high, medium, low), clientId, notes (internal).Returns: the activity with its id and url.Side effects: one activity on your team's list. Nothing is sent to the client. |
create_taskWrite | Create a task on the schedule. Needs the company's Scheduling feature. Without the team-wide task permission it can only be assigned to you. Inputs: title (required); optional date, startTime, endTime, assigneeId (you by default), clientId, description, priority (low, normal, high).Returns: the task with its id, local day and times, and url.Side effects: one task on the schedule. Nothing is sent to the client. |
create_quote_draftWrite | Draft an estimate for a client from line items. Inputs: clientId, title, items (required; each item has description, quantity and price, the unit price); optional notes (internal).Returns: the draft with its id, estimateNumber, status (draft), totals and url.Side effects: one draft estimate with its number allocated. It is never sent: sending it, and writing its message to the client, happen in Clevra. |
schedule_visitSensitive write | Book a visit on a job for a time slot. Needs the company's Scheduling feature. Call find_open_slots first: a clash with an existing booking is refused.Inputs: jobId (the id or the job number), startTime, endTime (required); optional assigneeId (otherwise the job's crew, otherwise you), notes (internal).Returns: the visit with its id, jobId, visitNumber, status, startTime, endTime and url.Side effects: one booked visit, and your company's automatic messages to the client, such as the booking confirmation and reminders by text and email, exactly as booking it in Clevra does. A sent message cannot be taken back. |
Every action runs through the same rules as the Clevra app and is recorded in Clevra's audit trail as done through an AI assistant.
What the server can't do. It never:
Do those in Clevra.
A successful call returns its result as JSON, both as text in content and as an object in structuredContent.
| Situation | What the server answers |
|---|---|
| The access token is missing, expired or disconnected | HTTP 401 with a WWW-Authenticate: Bearer header that points to the discovery document. The assistant should send the person to sign in again. |
| The person's Clevra account is deactivated or suspended | HTTP 403. |
| The person's role, plan or company settings don't allow the tool, or connections or actions are paused | An ordinary tool result with isError: true and a plain-language reason the assistant can pass on, for example: "Not permitted to use List invoices: your role does not include it." |
| An input is missing or invalid | isError: true, naming the input and the problem, for example: "dateTo must be on or after dateFrom." |
| The record doesn't exist or the person can't see it | isError: true with the reason. |
| A visit would clash with an existing booking | isError: true with the same message the Clevra app shows. Nothing is booked. |
| The tool name is unknown | A JSON-RPC error with code -32602. |
| A per-minute limit is exceeded | HTTP 429 with retryAfterSeconds in the response body. |
| The daily tool-call allowance is used up | isError: true saying so. Calls work again the next day. |
| Sign-in can't be checked because of an outage | HTTP 503. Try again shortly. |
Repeated actions don't create duplicates. If an assistant sends the same action with the same inputs again shortly after it ran, the server returns the first result marked replayed: true and creates nothing new. This covers 10 minutes for create_client, create_quote_draft and schedule_visit, and 2 minutes for add_client_note, create_activity and create_task.
In Clevra, under Settings → Connected apps, admins can:
| What your assistant says | What to do |
|---|---|
| "Your role does not include the AI assistant connector" | Ask your admin to give you the Org Admin, Manager or Dispatcher role. No reconnect is needed. |
| "The AI assistant is not included in your company's plan" | An admin can change the plan in Settings → Billing. No reconnect is needed. |
| "AI assistant connections are paused" | An admin turned off Allow AI assistant connections in Settings → Connected apps. |
| "Actions through AI assistants are paused" | An admin turned off Allow actions through AI assistants in Settings → Connected apps. Read tools still work. |
| "This connection was disconnected…" | In Clevra, press Connect in Settings → Connected apps, then connect Clevra again in your assistant. |
| "Connect Clevra to continue" | Sign in with your staff Clevra account. If you just pressed Connect in Clevra, press it again; each Connect request is valid for an hour. |
Questions or problems: hi@clevra.ai.

You run a crew, not a tech company. Clevra handles the office stuff so you can stay on the tools.