Overview
The connector gives Claude access to your Valoon projects through the Model Context Protocol. Claude only sees what your own Valoon account can see, and every change it makes is made with your account.
Typical uses are summarising what happened on a site this week, turning site notes into tickets, drafting the daily report from site photos and notes, and checking logged hours before payroll.
Before you start
- A Valoon account with access to the projects you want to work on.
- A Valoon API key. You find its Client ID and Secret under Valoon → Settings → API keys.
- A Claude plan that supports custom connectors.
- On Team and Enterprise plans, an owner may need to allow custom connectors under Organization settings → Connectors.
Connect Valoon to Claude
Claude.ai and Claude Desktop
- Open Settings → Connectors and choose Add custom connector.
- Enter
Valoonas the name and paste the connector URL:https://dev.mcp.valoon.crucerlabs.com/mcp - Select Connect. The Valoon authorization page opens.
- Enter the Client ID and Secret of your Valoon API key and select Authorize access.
- Back in Claude, enable the Valoon tools you want for the conversation from the tools menu.
Claude Code
Add the server from your terminal:
claude mcp add --transport http valoon https://dev.mcp.valoon.crucerlabs.com/mcp
Then run /mcp inside Claude Code, select Valoon and authenticate. Your browser opens the same authorization page. Once you have authorized access, Valoon is listed as connected.
Permissions and data
Every tool carries one of three labels, and the server reports it to Claude with each tool, so Claude can tell reads from changes. Depending on your Claude settings, Claude asks you to confirm before it runs a tool.
| Label | What the tool does | Example |
|---|---|---|
| Read | Reads data. Nothing changes in Valoon. | list_tickets |
| Write | Creates, updates or moves data in Valoon. | create_report |
| Sends messages | Starts a Valoon conversation with the participants of a ticket. | send_ticket |
Messages reach real people
Tools labelled Sends messages message the participants of the ticket on your behalf, and a sent message cannot be undone. Check which tickets Claude wants to send before you confirm. Creating or updating projects and tickets also sends the same notifications as the Valoon app.
You sign in with your Valoon API key. The Client ID and Secret are verified against the Valoon API and are never stored on the server. Claude receives an access token that is valid for one hour and is renewed with a refresh token that is valid for 30 days and replaced on every use.
Claude receives only the results of the tools it calls. For operations, the server logs the tool name, your Client ID, the Claude app, the duration and the result status of each call, but not its arguments or its response.
Example prompts
- “Summarise all open defects on Schillerstraße 12 and group them by trade.”
- “Create tickets from these site notes and add the Hoffmann Elektro team as participants.”
- “Draft today’s daily report for JACTESP from the photos uploaded this morning.”
- “Which crew members logged more than 10 hours on any day last week?”
A routine that works well: ask Claude every Friday for a site summary per project. It reads the week’s tickets and reports and gives the project lead a one-page status.
Tools
Tools are grouped by area. Groups are collapsed to keep the list short; open one to see its tools. Tool names and descriptions are in English, and the names are the ones Claude uses when it calls a tool.
Core1 toolYour signed-in account
- Who Am I
whoamiReturns the currently authenticated user. Use this to identify who is making the request.
Read
Projects7 toolsProjects, their history and statistics
- Create Project
create_projectCreate a new Project.
Write - Get All Project Statistics
get_all_project_statisticsGet statistics across all projects.
Read - Get Project
get_projectGet a Project by id.
Read - Get Project History
get_project_historyGet the full event history of a project.
Read - Get Project Statistics
get_project_statisticsGet statistics for a specific project.
Read - List Projects
list_projectsList Projects.
Read - Update Project
update_projectUpdate an existing Project by id.
Write
Tickets23 toolsTickets, labels, scopes and workflow settings
- Add Ticket Labels
add_ticket_labelsAdd labels to a ticket.
Write - Add Ticket Participants
add_ticket_participantsAdd users to a ticket as participants.
Write - Create Label
create_labelCreate a new Label.
Write - Create Scope
create_scopeCreate a new Scope.
Write - Create Ticket
create_ticketCreate a new Ticket.
Write - Dispatch Ticket
dispatch_ticketStart the ticket conversation with every participant of one ticket.
Sends messages - Duplicate Ticket
duplicate_ticketCopy a ticket, optionally into another project or under a new title.
Write - Get Label
get_labelGet a Label by id.
Read - Get Scope
get_scopeGet a Scope by id.
Read - Get Ticket
get_ticketGet a Ticket by id.
Read - Get Ticket History
get_ticket_historyGet the full event history of a ticket.
Read - Get Ticket Flow Setting
get_ticketflowsettingGet a TicketFlowSetting by id.
Read - List Labels
list_labelsList Labels.
Read - List Scopes
list_scopesList Scopes.
Read - List Tickets
list_ticketsList Tickets.
Read - Move Ticket
move_ticketMove a ticket to a different project.
Write - Remove Ticket Labels
remove_ticket_labelsRemove labels from a ticket.
Write - Remove Ticket Participants
remove_ticket_participantsRemove users from a ticket's participants.
Write - Send Ticket
send_ticketStart the ticket-list conversation with every participant of the listed tickets.
Sends messages - Update Label
update_labelUpdate an existing Label by id.
Write - Update Scope
update_scopeUpdate an existing Scope by id.
Write - Update Ticket
update_ticketUpdate an existing Ticket by id.
Write - Update Ticket Flow Setting
update_ticketflowsettingUpdate an existing TicketFlowSetting by id.
Write
Reports14 toolsReports, templates and PDF exports
- Create Report
create_reportCreate a new report from a template, either in a project (projectId) or linked to a ticket (ticketId, which places it in the ticket's project). Pass exactly one of the two.
Write - Duplicate Report
duplicate_reportDuplicate an existing report. Returns the new copy.
Write - Get Report
get_reportGet a report by id, including its form data and state.
Read - Get Report PDF
get_report_pdfGenerate and download the PDF of a report.
Read - Get Report Template
get_report_templateGet a report template by id, optionally a specific version. Includes the form structure.
Read - Get Reports by Ticket
get_reports_by_ticketList all reports linked to a specific ticket.
Read - List Export Templates
list_exporttemplatesList ExportTemplates.
Read - List Report Labels
list_report_labelsList the tenant's report labels (such as Open, In Progress, Approved and Invoiced), ordered by their sort order.
Read - List Report Templates
list_report_templatesList all report templates of the tenant.
Read - List Reports
list_reportsList reports, filtered and sorted on the server; newest report date first by default.
Read - Move Report
move_reportMove a report to another project.
Write - Set Report Label
set_report_labelSet a report's label, or clear it with labelId none. Works in every report state, finalized reports included: the label is workflow metadata, not report content.
Write - Set Report Ticket
set_report_ticketLink a report to a ticket, or unlink it from its ticket with ticketId none.
Write - Update Report
update_reportUpdate a report's title, date, state or form data.
Write
Files & media21 toolsFolders, files, photos and scans
- Copy Files
copy_filesCopy files and/or folders into a target folder.
Write - Create Folder
create_folderCreate a new Folder.
Write - Create Scan Type
create_scantypeCreate a new ScanType.
Write - Get Attachment
get_attachmentGet a Attachment by id.
Read - Get File
get_fileGet a File by id.
Read - Get Folder
get_folderGet a Folder by id.
Read - Get Folder Children
get_folder_childrenList the contents (subfolders and files) of a folder.
Read - Get Folder Parents
get_folder_parentsGet the parent folders (ancestor chain) of a folder.
Read - Get Media
get_mediaDownload the media (photo, document) attached to an entity, returned inline so images are directly visible.
Read - Get Scan
get_scanGet a Scan by id.
Read - Get Scan Type
get_scantypeGet a ScanType by id.
Read - List Attachments
list_attachmentsList Attachments.
Read - List Files
list_filesList Files.
Read - List Folders
list_foldersList Folders.
Read - List Photo Gallery
list_photogalleryList PhotoGallery.
Read - List Scans
list_scansList Scans.
Read - List Scan Types
list_scantypesList ScanTypes.
Read - Move Files
move_filesMove files and/or folders into a target folder.
Write - Update Folder
update_folderUpdate an existing Folder by id.
Write - Update Scan
update_scanUpdate an existing Scan by id.
Write - Update Scan Type
update_scantypeUpdate an existing ScanType by id.
Write
Time8 toolsTime entries and time types
- Create Time Entry
create_timeentryCreate a new TimeEntry.
Write - Get Time Entry
get_timeentryGet a TimeEntry by id.
Read - Get Time Entry History
get_timeentry_historyGet the full event history of a time entry.
Read - Get Time Type
get_timetypeGet a TimeType by id.
Read - List Time Entries
list_timeentriesList TimeEntries.
Read - List Time Types
list_timetypesList TimeTypes.
Read - Update Time Entry
update_timeentryUpdate an existing TimeEntry by id.
Write - Update Time Type
update_timetypeUpdate an existing TimeType by id.
Write
Administration10 toolsUsers, groups and organization settings
- Create Group
create_groupCreate a new Group.
Write - Get Group
get_groupGet a Group by id.
Read - Get Tenant
get_tenantGet a Tenant by id.
Read - Get User
get_userGet a User by id.
Read - List Groups
list_groupsList Groups.
Read - List Tenants
list_tenantsList Tenants.
Read - List Users
list_usersList Users.
Read - Update Group
update_groupUpdate an existing Group by id.
Write - Update Tenant
update_tenantUpdate an existing Tenant by id.
Write - Update User
update_userUpdate an existing User by id.
Write
Troubleshooting
The authorization page closes without connecting
Your browser may block the pop-up. Allow pop-ups for claude.ai, then select Connect again.
“We couldn’t verify your credentials”
The Client ID or Secret is wrong, or the API key no longer exists. Copy both again from Valoon → Settings → API keys and try again.
Claude says a project does not exist
Claude only sees the projects your Valoon account can access. Ask Claude to call list_projects to see them. If the project is missing, ask a project owner to add you.
A write tool returns “forbidden”
Your Valoon role does not allow that action on the project. Ask a project owner to change your role, or run the read-only version of the request.
Privacy and support
To disconnect, remove the connector in Claude settings. To revoke access completely, delete the API key in Valoon under Valoon → Settings → API keys; every call made with it fails from then on.
Read the privacy policy and terms. For help, write to support@valoon.chat and include the time of the failed request.