Skip to main content

Model Context Protocol (MCP) API

For practical examples of how to use the MCP, see the support documentation.

Setup​

1. Create an API key​

Start by creating an API key in Simplicate that allows use by Simplicate AI-tooling. Go to Settings → API keys → Add. Make sure to enable the MCP usage checkbox.

mcp_api_token_creation.png

caution

Handle API keys carefully. Keys enable modifications to your environment.

2. Determine your endpoint​

The MCP API is available at:

https://<your-simplicate-domain>.mcp.simplicate.app/mcp

Replace <your-simplicate-domain> with your Simplicate environment domain.

3. Authentication​

The token consists of an API-key and API-secret. Combine them with a : to get your authentication token: {API-key}:{API-secret}. For example: 1234567890:0987654321.

Use this token as a Bearer token in the Authorization header.

Client configuration​

Example mcp.json​

{
  "mcpServers": {
    "simplicate": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://<your-simplicate-domain>.mcp.simplicate.com/mcp",
        "--header",
        "Authorization: Bearer ${AUTH_TOKEN}"
      ],
      "env": {
        "AUTH_TOKEN": "<your-api-key>:<your-api-secret>"
      }
    }
  }
}
note

Not all AI tools support this authentication method for MCP interaction.

Supported tools​

When connected to the Simplicate MCP API you can view and use all available tools it provides. Below is a non-exhaustive list of tools provided to give an indication of its capabilities.

search-entity-information​

Search for an entity in Simplicate and return its details.

Parameters:

  • search_term: Search term to search for, each entity determines which fields are searched.
  • entity_type: Type of the entity to search information for. Possible values:project, sales, organization, person, employee, invoice.

register-hour-time-aware​

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

Parameters:

  • employee_id: Employee Id of the employee to register the hours for.
  • project_id: Project Id of the project to register the hours for.
  • project_service_id: Project service ID of the project service to register the hours for.
  • type_id: Hour type Id of the hour type to register the hours for.
  • registrationDate: The date (YYYY-MM-DD) to register the hour for, defaults to today if not set.
  • note: Optional note that can be added to the hour registration, supports max 1000 characters.
  • start_time: Start time of the hour registration in HH:mm format.
  • end_time: End time of the hour registration in HH:mm format.

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.

Parameters:

  • employee_id: Employee Id of the employee to register the hours for.
  • project_id: Project Id of the project to register the hours for.
  • project_service_id: Project service ID of the project service to register the hours for.
  • type_id: Hour type Id of the hour type to register the hours for.
  • registrationDate: The date (YYYY-MM-DD) to register the hour for, defaults to today if not set.
  • note: Optional note that can be added to the hour registration, supports max 1000 characters.
  • duration_in_minutes: Duration of the hour registration in minutes, defaults to 30 minutes if not set.

create-timeline-note​

Create a note in the timeline of an entity.

Parameters:

  • employee_id: Employee Id of the employee that is the creator of the note.
  • note: Note to create in the timeline.
  • entity_id: Id of the entity to create the note for.
  • entity_type: Type of the entity to create the note for. Possible values: project, sales, organization, person, invoice.

Disclaimer​

Simplicate cannot guarantee that AI-generated answers are always accurate. Responsibility covers only API quality and accompanying instructions.