Clevra

npx add-mcp 'https://app.clevra.ai/api/mcp'

Clevra MCP server

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 details

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.

What you need

• A Clevra account with the Org Admin, Manager or Dispatcher role.
• A Clevra plan that includes the AI assistant: Pro, Business or Custom (or an active trial).
• An AI assistant or MCP client that supports remote MCP servers with OAuth sign-in.

Connect your assistant

1. In your assistant's settings, add a custom connector. Depending on the assistant it may be called a connector, an app, an integration or an MCP server.
2. Paste the server URL:
   https://app.clevra.ai/api/mcp No API key is needed. If the assistant asks for an authentication type, choose OAuth.
3. Sign in with your usual Clevra login and approve access on the consent screen.
4. That's it. Ask your first question.

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.

Tools

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.

Conventions

• Lists take an optional limit (25 by default, 50 at most) and cursor, and return items, hasMore and, when there is more, nextCursor.
• Dates are 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.
• Money is in your company's currency, and each figure carries currency.
• Records carry an id and a url that opens the record in Clevra. Jobs, invoices and estimates can also be looked up by number (JOB-…, INV-…, EST-…).
• Team members are named by the id from list_team_members, or me for yourself.
• Company and identity come from the sign-in. An assistant cannot name another company or act as another person.

Clients

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.

Jobs

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.

Invoices and estimates

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.

Requests

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.

Schedule

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.

Activities and team

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.

Reports

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

Actions

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_client Write	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_note Write	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_activity Write	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_task Write	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_draft Write	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_visit Sensitive 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:

• sends emails or texts on its own
• takes or refunds payments
• deletes anything
• converts estimates into jobs
• imports data
• changes billing, payroll, team membership or company settings.

Do those in Clevra.

Results, errors and repeats

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.

Try asking

• "What's on the schedule tomorrow, and who is assigned to each visit?"
• "Which invoices are overdue, and how much is outstanding in total?"
• "Show me everything we've done for Acme Property Management this year."
• "Find a two-hour slot for Maria next week and book the follow-up visit for the Oak Street job."
• "Draft an estimate for Jane Smith: annual furnace service plus one filter replacement."
• "Run the aged receivables report and tell me which clients owe the most."

Permissions and privacy

• Your role, nothing more. The assistant sees and does only what your Clevra role allows. Pay rates and costing are hidden from roles that can't see them in the app, and a role change takes effect on the next request.
• Clevra doesn't receive your conversations. Clevra sees only the requests the assistant makes on your behalf. For each request it keeps an access record (which connection, which tool, the outcome and how long it took), never the content. Access records are deleted after 90 days.
• What the assistant receives is handled by its provider. Data returned to your assistant is processed under your agreement with that assistant's provider. See our Privacy Policy.
• Your password stays with Clevra. You sign in through Clevra's own sign-in page, and the assistant receives a revocable access token.

Controls for admins

In Clevra, under Settings → Connected apps, admins can:

• see every connection in the company, and disconnect any of them;
• turn Allow AI assistant connections off to pause every connection at once;
• turn Allow actions through AI assistants off to keep every assistant read-only for the whole company.

Limits

• Up to five active connections per person.
• 120 requests per minute per connection, and 3,000 requests per 10 minutes per company.
• 2,000 tool calls per connection and 10,000 per company each day, counted in your company's time zone.
• Using the server doesn't count against your in-app AI assistant's monthly message allowance.

Disconnect or reconnect

• Disconnect: in Clevra, go to Settings → Connected apps and select Disconnect. The assistant's next request is refused. You can also remove the connector in your assistant's settings.
• Reconnect after disconnecting: in Settings → Connected apps, select Connect, then reconnect Clevra in your assistant within an hour.

Troubleshooting

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.

Support

Questions or problems: hi@clevra.ai.