MCP tools reference

search-entity-information

Search for an entity in Simplicate and return its details, including its recent timeline messages. This is the default lookup tool for projects, sales, organizations, persons, employees and invoices, and needs no employee_id. Pass a Simplicate id as search_term to look the record up by id instead of by name. These six entity types are the only records this tool can reach. If an id carries any other prefix, do not call this tool with a related type; say the record type is not supported.

Parameter	Type	Required	Description
search_term	string	Yes	Name to search for. Each entity searches its own fields: organization and person search the relation name, employee the employee name, sales the subject, project the name, project number, project manager and relation, invoice the invoice number, subject, reference and relation. Pass a Simplicate id to return exactly that one record. The id prefix is the entity_type itself: "organization:...", "person:...", "employee:...", "sales:...", "project:...", "invoice:...". An id with any other prefix, for example "projectservice:...", "document:..." or "hours:...", is a different kind of record. This tool cannot look it up. Do not substitute a related entity_type such as project.
entity_type	enum	Yes	Type of the entity to search information for. "sales" is a sale or opportunity (Dutch "verkoop"), never a company; use "organization" for a company. "myorganizationprofile" is your own company's business profile and ignores search_term. One of: project, sales, organization, person, employee, invoice, myorganizationprofile.

create-sale

Create a new sale in Simplicate.

Parameter	Type	Required	Description
subject	string	Yes	Subject/title of the sale
organization_id	string	No	Organization. Either organization_id or person_id must be provided.
person_id	string	No	Person. Either organization_id or person_id must be provided.
my_organization_profile_id	string	Yes	My organization profile id - must be one of your own company's business profiles (myorganizationprofile), NOT a regular organization. Search with entity_type 'myorganizationprofile' to find available profiles
confirmed	boolean	Yes	Must be true to create the sale. Always show the sale details to the user and ask for confirmation BEFORE setting this to true.

update-sale

Update an existing sale in Simplicate. Only provided fields will be updated.

Parameter	Type	Required	Description
sale_id	string	Yes	The ID of the sale to update
subject	string	No	Subject/title of the sale
organization_id	string	No	Organization linked to the sale
person_id	string	No	Person linked to the sale
my_organization_profile_id	string	No	My organization profile id - must be one of your own company's business profiles (myorganizationprofile), NOT a regular organization. Search with entity_type 'myorganizationprofile' to find available profiles
start_date	string	No	Start date of the sale (YYYY-MM-DD format)
expected_closing_date	string	No	Expected closing date of the sale (YYYY-MM-DD format)
expected_revenue	number	No	Expected revenue from the sale
chance_to_score	number	No	Chance to score/win the sale (0-100 percentage)
progress_id	string	No	Sales progress/stage ID
reason_id	string	No	Sales reason/source ID
contact_id	string	No	Contact person ID linked to the sale
responsible_employee_id	string	No	Employee ID of the person responsible for this sale
source_id	string	No	Source ID indicating where the sale/lead originated from
status_id	string	No	Status ID representing the current status of the sale (e.g., open, won, lost)
note	string	No	Note or description for the sale
divergent_payment_term_id	string	No	Divergent payment term ID. Use null to unset. Search with 'search-payment-terms' to find available payment terms
confirmed	boolean	Yes	Must be true to update the sale. Always show the changes to the user and ask for confirmation BEFORE setting this to true.

search-sales-options

Search for available sales options from Simplicate. Use this to find IDs for status, progress, reason, or source when updating sales.

Parameter	Type	Required	Description
option_type	enum	Yes	Type of sales option to retrieve: status (sales statuses), progress (sales progress stages), reason (sales reasons), source (sales sources). One of: status, progress, reason, source.

search-payment-terms

Search all available payment terms from Simplicate. Use this to find payment term IDs when asked to update divergent payment term.

identify-current-employee

Identify the current employee based on the provided credentials. Call this to obtain the employee_id that the other tools require, instead of asking the user for it.

search-registration-project

Search for a project in Simplicate by name and return its external id. Only returns projects the given employee may register on, so use search-entity-information instead for general project lookups such as finding a project number. At most 5 search terms per call, and the API returns at most 100 projects per term.

Parameter	Type	Required	Description
employee_id	string	No	Employee id of a Simplicate employee. Leave this out to act as the employee behind the current credentials, which is what the user means unless they say otherwise. Never ask the user for this value. Only pass it when the user explicitly acts on behalf of a colleague, and look that colleague up with list-employees-for-registration first.
search_terms	array	No	The names, project_numbers, relation names or relation numbers of the projects to search for, at most 5. Every term is searched separately and the results are merged, if none are provided the first 100 records are returned
registration_date	string	No	The date to register the hour or the mileage for, as YYYY-MM-DD or 'today'. Used to filter registrable projects for that date if defined
for_mileage	boolean	No	Set this to true to limit results to projects that support mileage registration

search-project-service-for-registration

Search a project service in Simplicate for a project by name and return its external id. At most 5 search terms per call. This endpoint returns every project service of the project, however many there are.

Parameter	Type	Required	Description
employee_id	string	No	Employee id of a Simplicate employee. Leave this out to act as the employee behind the current credentials, which is what the user means unless they say otherwise. Never ask the user for this value. Only pass it when the user explicitly acts on behalf of a colleague, and look that colleague up with list-employees-for-registration first.
project_id	string	Yes	Project id of a Simplicate project, projects contain project services
search_terms	array	No	The names or numbers of the project services to search for, at most 5. A project service matching any of them is returned
registration_date	string	No	The date to register the hour for, as YYYY-MM-DD or 'today'. Used to filter registrable project services for that date if defined

search-bookable-hour-type

Search the Simplicate hour types (in Dutch 'urensoorten') this employee may book on this project service, so the answer to what someone can write hours on, and return their external ids. Use this while preparing an hour registration. Use search-hour-type-catalog to look up an hour type that is not tied to a project service. At most 5 labels per call. Asks the API once and returns at most 100 hour types over all labels together, because the labels filter that one answer.

Parameter	Type	Required	Description
employee_id	string	No	Employee id of a Simplicate employee. Leave this out to act as the employee behind the current credentials, which is what the user means unless they say otherwise. Never ask the user for this value. Only pass it when the user explicitly acts on behalf of a colleague, and look that colleague up with list-employees-for-registration first.
project_id	string	Yes	Project id of a Simplicate project, projects contain project services. Look one up with search-registration-project
project_service_id	string	Yes	Project service id of a Simplicate project service, a project service belongs to a project and contains hourtypes. In dutch this is called 'Project dienst'. Look one up with search-project-service-for-registration
hour_type_labels	array	No	Labels to filter hour types by, at most 5. An hour type matching any of them is returned. If none are provided the first 100 records are returned

search-hour-type-catalog

Search every Simplicate hour type (in Dutch 'urensoorten') in the administration, bookable or not, with its kind and default tariff, and return their external ids. Use search-bookable-hour-type instead while preparing an hour registration, because this tool also returns hour types the employee may not book. At most 5 labels per call. Asks the API per label and returns at most 100 hour types per label.

Parameter	Type	Required	Description
hour_type_labels	array	No	Labels to filter hour types by, at most 5. An hour type matching any of them is returned. If none are provided the first 100 records are returned

register-hour-time-aware

Register hours in Simplicate by defining a registration date, a start time and duration in minutes or end time. The hour is registered with a specific start- and end time.

Parameter	Type	Required	Description
employee_id	string	No	Employee id of a Simplicate employee. Leave this out to act as the employee behind the current credentials, which is what the user means unless they say otherwise. Never ask the user for this value. Only pass it when the user explicitly acts on behalf of a colleague, and look that colleague up with list-employees-for-registration first.
project_id	string	Yes	Project id of a Simplicate project, projects contain project services
project_service_id	string	Yes	Project service id of a Simplicate project service, a project service belongs to a project and contains hourtypes. In dutch this is called 'Project dienst'
type_id	string	Yes	Hourtype id of a Simplicate hourtype, an hourtype belongs to a project service and project. In dutch this is called 'Urensoort'
registrationDate	string	Yes	A date as YYYY-MM-DD, or the word 'today'. Name the day you mean, there is no default
note	string	No	Note that can be added to the hour registration, supports max 1000 characters
start_time	string	Yes	Start time of the hour registration in HH:mm format
end_time	string	Yes	End time of the hour registration in HH:mm format
external_calendar_item	object	No	The external calendar item this hour is written for. Pass it to keep the hour linked to that item, so the item is not proposed again and no second appointment appears in the external calendar. The link is only made for hours of the employee behind the current credentials, so leave employee_id out when you pass this.

register-hour-time-unaware

Register hours in Simplicate by defining a registration date and a duration in minutes. The hour is registered as a block of time without a specific start- and end time.

Parameter	Type	Required	Description
employee_id	string	No	Employee id of a Simplicate employee. Leave this out to act as the employee behind the current credentials, which is what the user means unless they say otherwise. Never ask the user for this value. Only pass it when the user explicitly acts on behalf of a colleague, and look that colleague up with list-employees-for-registration first.
project_id	string	Yes	Project id of a Simplicate project, projects contain project services
project_service_id	string	Yes	Project service id of a Simplicate project service, a project service belongs to a project and contains hourtypes. In dutch this is called 'Project dienst'
type_id	string	Yes	Hourtype id of a Simplicate hourtype, an hourtype belongs to a project service and project. In dutch this is called 'Urensoort'
registrationDate	string	Yes	A date as YYYY-MM-DD, or the word 'today'. Name the day you mean, there is no default
note	string	No	Note that can be added to the hour registration, supports max 1000 characters
duration_in_minutes	integer	No

create-timeline-note

Create a note in the timeline of an entity

Parameter	Type	Required	Description
employee_id	string	No	Employee id of a Simplicate employee. Leave this out to act as the employee behind the current credentials, which is what the user means unless they say otherwise. Never ask the user for this value. Only pass it when the user explicitly acts on behalf of a colleague, and look that colleague up with list-employees-for-registration first.
note	string	Yes	Content of the timeline note
entity_id	string	Yes	Id of the entity to create the note for
entity_type	enum	Yes	Type of the entity to create the note for. One of: project, sales, organization, person, invoice.

list-employees-for-registration

List employees for which the current employee may register

Parameter	Type	Required	Description
registrationDate	string	Yes	A date as YYYY-MM-DD, or the word 'today'. Name the day you mean, there is no default

get-hour-registrations

Get existing hour registrations for an employee over a period. Can be used to view what hours have been registered, or as input for creating new registrations with a similar configuration. The period may cover at most 31 days, and the API returns at most 100 registrations, so ask per project or per shorter period when you need more.

Parameter	Type	Required	Description
employee_id	string	No	Employee id of a Simplicate employee. Leave this out to act as the employee behind the current credentials, which is what the user means unless they say otherwise. Never ask the user for this value. Only pass it when the user explicitly acts on behalf of a colleague, and look that colleague up with list-employees-for-registration first.
date_from	string	Yes	First day of the period to get hour registrations for, as YYYY-MM-DD or 'today'
date_to	string	Yes	Last day of the period to get hour registrations for, as YYYY-MM-DD or 'today'. The period may cover at most 31 days
project_id	string	No	Optional project ID to filter registrations by project

search-sale-services

Search sale services in Simplicate

Parameter	Type	Required	Description
sale_id	string	Yes	Sale id of a Simplicate sale/opportunity. In Dutch this is called 'Verkoop'
search_term	string	Yes	The name or number for the sale services to search for, only searches the first 10 records that belong to the given sale

search-default-services

Search the catalog of default services (service templates) in Simplicate to find a default_service_id.

Parameter	Type	Required	Description
search_term	string	No	Optional name to filter default services by. Leave out to list the first default services.

list-default-workflows

List the workflows this customer has configured and that the current employee can start, with what each one requires. Use this before starting a workflow: it is the only way to get a valid workflow id. Workflows that cannot be started are left out.

create-workflow

Start a workflow for this customer from one of their configured workflows. Call list-default-workflows first: it is the only source of valid workflow ids and it says per workflow whether a subject is required.

Parameter	Type	Required	Description
default_workflow_id	string	Yes	Id of a Simplicate default workflow, the configured template a workflow is started from. Pass this when starting a workflow. In Dutch this is called 'Standaard workflow'
title	string	Yes	Short subject of the workflow, shown in the overview. Required. Plain text only.
description	string	Yes	What has to happen, for the colleague who picks the workflow up. Required. Plain text only: Simplicate shows it exactly as it is given, so markdown, BBCode and HTML land as the literal characters that spell them.
destination_employee_id	string	Yes	The colleague who gets the first step of the workflow, as the external id list-employees-for-registration returns, so it starts with "employee:". Required: never guess it and never pass an internal number. Ignored when the workflow has a fixed destination configured.
subject_type	enum	No	What the workflow is about. Pick one of the allowedSubjectTypes that list-default-workflows reports for this workflow; that is also the word you search with in search-entity-information. You have to pass one when isSubjectRequired is true. When it is false you may still pass one if allowedSubjectTypes is not empty, and you leave both subject fields out when it is. One of: project, sales, organization, person, employee, invoice.
subject_id	string	No	Id of the subject, as returned by search-entity-information. It has to be that external id, not an internal number. Pass it together with subject_type.
deadline	string	No	Date the whole workflow has to be finished, as YYYY-MM-DD. Optional: leave it out when the user names no deadline. Simplicate refuses a date in the past, so ask the user rather than guessing one. A workflow of one step has a single deadline: pass either this or step_deadline and Simplicate copies it to the other, and it refuses two different dates.
step_deadline	string	No	Date the first step has to be finished, as YYYY-MM-DD. Optional, and it has to fall on or before deadline. Pass this when the user names a deadline for the task rather than for the whole workflow.
attachments	array	No	Documents already stored in Simplicate to attach to the workflow, each as the id search-documents returns. Look the document up there first; the argument takes no file name or content. Only allowed when canHaveAttachment is true for this workflow in list-default-workflows, and Simplicate refuses the call otherwise. When the document is not in Simplicate yet, refer the user to the app to upload it there and leave this out.
confirmed	boolean	Yes	Must be true to start the workflow. Starting one puts work on a colleague's plate and can email them, so always show the details to the user and ask for confirmation BEFORE setting this to true.

search-documents

Find a document that is already stored in Simplicate, by its title or by the name of what it is filed under. Returns per document the id that create-workflow takes as an attachment, its title, its document type and what it is linked to. A document that is not in Simplicate yet cannot be added here: refer the user to the app to upload it first.

Parameter	Type	Required	Description
search_term	string	Yes	Part of the document title, or the name of the organization, person, project or sale the document is filed under. Matched case-insensitively.

add-sale-services

Add one or more services to an existing sale in Simplicate. Each service is created from a default service (template) - find its default_service_id with 'search-default-services' first.

Parameter	Type	Required	Description
sale_id	string	Yes	The ID of the sale to add the services to
services	array	Yes	One or more services to add to the sale
confirmed	boolean	Yes	Must be true to add the services. Always show the services to the user and ask for confirmation BEFORE setting this to true.

register-mileage

Register mileage in Simplicate on a project for a given date. Mileage is registered on a project only, there is no project service and no mileage type to look up. The project must have mileage registration enabled, so find it with search-registration-project using for_mileage set to true.

Parameter	Type	Required	Description
employee_id	string	No	Employee id of a Simplicate employee. Leave this out to act as the employee behind the current credentials, which is what the user means unless they say otherwise. Never ask the user for this value. Only pass it when the user explicitly acts on behalf of a colleague, and look that colleague up with list-employees-for-registration first.
project_id	string	Yes	Project id of a Simplicate project, projects contain project services
registration_date	string	Yes	The date to register the mileage for, as YYYY-MM-DD or 'today'
mileage	number	Yes	Total distance driven, in kilometers. Double it yourself for a return trip ('retour', 'heen en terug')
note	string	No	Note that can be added to the mileage registration, supports max 1000 characters
related_hour_id	string	No	Optional id of an hour registration to link this mileage to. The hour must be on the same project and cannot be leave or absence

get-mileage-registrations

Get existing mileage registrations for an employee over a period. Use it to check what has already been registered, or as input for a correction with update-mileage.

Parameter	Type	Required	Description
employee_id	string	No	Employee id of a Simplicate employee. Leave this out to act as the employee behind the current credentials, which is what the user means unless they say otherwise. Never ask the user for this value. Only pass it when the user explicitly acts on behalf of a colleague, and look that colleague up with list-employees-for-registration first.
date_from	string	Yes	First day of the period to get mileage registrations for, as YYYY-MM-DD or 'today'
date_to	string	Yes	Last day of the period to get mileage registrations for, as YYYY-MM-DD or 'today'
project_id	string	No	Optional project id to filter registrations by project

update-mileage

Correct an existing mileage registration in Simplicate. At least one of mileage, registration_date, note or related_hour_id must be filled. Only the fields you pass are changed, the rest is left alone. The employee and the project cannot be changed after creation, and a registration that has been approved or invoiced can no longer be edited.

Parameter	Type	Required	Description
mileage_id	string	Yes	Id of the mileage registration to update, as returned by get-mileage-registrations
mileage	number	No	The total distance in kilometers to store, replacing the current value
registration_date	string	No	Move the registration to another date
note	string	No	Note on the mileage registration, supports max 1000 characters
related_hour_id	string	No	Id of an hour registration to link this mileage to. The hour must be on the same project

create-crm-relation

Create a new relation in Simplicate: an organization or a person. A person needs a family name. The gender is optional: leave it out rather than derive one from the first name. Look up every id field with search-crm-options. Accountancy fields need the accountancy branch, and a person's bank_account and bank_bic need the setting for private individuals. Always show the relation details to the user and ask for confirmation BEFORE setting confirmed to true.

Parameter	Type	Required	Description
relation	string	Yes	The relation to create, either an organization or a person.
confirmed	boolean	Yes	Must be true to create the relation. Always show the details to the user and ask for confirmation BEFORE setting this to true.

search-crm-options

Read the CRM lookup values available in this environment: relation type, industry, organization size, gender, customer group, country, team, interest and payment term. Use this to find the ids that create-crm-relation takes; it accepts ids only and never matches on a name. customergroup lists the organizations already used as a customer group, not every organization that could become one. team requires the hrm_options module; if this environment does not have it, this call is refused.

Parameter	Type	Required	Description
option_type	enum	Yes	Which lookup values to read: relationtype (relatiesoort), industry (branche), organizationsize (organisatiegrootte), gender (geslacht), customergroup (klantgroep), country (land), team, interest or paymentterm (betalingstermijn). One of: relationtype, industry, organizationsize, gender, customergroup, country, team, interest, paymentterm.