# MCP

## About MCP

MCP (Model Context Protocol) is a protocol that enables AI systems to connect and interact with external tools, software, and data sources in a standardized way, similar to the API in regular software.

In the context of Timebook, you can use it to connect the AI tool of your choice and use it to perform a series of tasks driven by Timebook data. In this article, we cover configuration for **Claude**, **Cursor**, and **Gemini CLI**.

{% tabs %}
{% tab title="Claude Desktop" %}

<figure><img src="/files/ukodcarMfjdJcsz7kVbC" alt=""><figcaption><p>A conversation in Claude based on Timebook data</p></figcaption></figure>
{% endtab %}

{% tab title="Cursor" %}

<figure><img src="/files/Etf7vGPyar5dVqhIKk6c" alt=""><figcaption><p>List of supported Timebook tools in the Cursor IDE</p></figcaption></figure>
{% endtab %}

{% tab title="Microsoft Copilot" %}

<figure><img src="/files/3jFIfyhNQn6B1DvcTK2x" alt=""><figcaption><p>A Copilot agent test screen with connected Timebook.</p></figcaption></figure>
{% endtab %}

{% tab title="Gemini CLI" %}

<figure><img src="/files/TfE2fmrkDDPnv6X6H3Sm" alt=""><figcaption><p>A prompt from in the Gemini CLI regarding Timebook MCP server connection</p></figcaption></figure>
{% endtab %}
{% endtabs %}

{% hint style="info" %}
Please mind that, for now, all MCP integrations require Google as Timebook's authorization method.

![](/files/lw6sZ5hleB5lQU0F8oAp)
{% endhint %}

## Claude

{% hint style="info" %}
This method is available in **paid instances** of Claude only.
{% endhint %}

{% stepper %}
{% step %}
Go to Settings → Connectors and click 'Add custom connector':

<div align="left"><figure><img src="/files/J26VJeazZrxVV4oGE6zV" alt="" width="563"><figcaption><p>Location of custom connector button in Claude settings</p></figcaption></figure></div>
{% endstep %}

{% step %}
Enter the name and paste the URL to the Timebook MCP: `https://mcp.timebook.net/mcp`

<div align="left"><figure><img src="/files/vuvJKtAw1LKZiYf3gwXd" alt="" width="563"><figcaption><p>Custom connector configuration in Claude</p></figcaption></figure></div>
{% endstep %}

{% step %}
Once you add the connector, Claude will ask you to authenticate in Timebook:

<div align="left"><figure><img src="/files/LlhtFxLybXo4iTuc3JIB" alt="" width="563"><figcaption><p>Timebook OAuth access screen</p></figcaption></figure></div>
{% endstep %}

{% step %}
Upon successful authentication, Timebook will be listed on the connectors list:

<div align="left"><figure><img src="/files/LXcwGmqYIIIjrpd1KmGd" alt="" width="563"><figcaption><p>Claude connectors with configured Timebook MCP</p></figcaption></figure></div>
{% endstep %}
{% endstepper %}

***

## Cursor

{% stepper %}
{% step %}
Go to **Cursor settings** → **Tools & MCP** and click 'Add Custom MCP'.
{% endstep %}

{% step %}
This will take you to the Cursor's `mcp.json` file. Copy the following and paste it into the file:

```json
{
  "mcpServers": {
    "timebook-mcp": {
      "url": "https://mcp.timebook.net/mcp/",
      "description": "Timebook MCP server serving Insights and Opportunities",
      "transport": {
        "type": "http-streamable"
      }
    }
  }
}
```

{% endstep %}

{% step %}
The Timebook MCP server will appear on the list. Click 'Connect' to continue.

<figure><img src="/files/QwlgOGAmrQ6O8fW55L5O" alt=""><figcaption><p>A list of connected MCP servers in Cursor</p></figcaption></figure>
{% endstep %}

{% step %}
Proceed with the instructions on screen to authenticate Cursor in Timebook.

If you configured everything correctly, Timebook will appear as an enabled server on the list.

<div align="left"><figure><img src="/files/fj8HfHgMyyvaD3FQp3Mf" alt="" width="563"><figcaption><p>Timebook MCP enabled in Cursor</p></figcaption></figure></div>
{% endstep %}
{% endstepper %}

***

## Microsoft Copilot

{% hint style="success" %}
In this example, we'll show how to create a Copilot agent from scratch and connect it to Timebook MCP.
{% endhint %}

{% hint style="info" %}
Follow [Microsoft documentation](https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-add-existing-server-to-agent) for the latest configuration changes on the Copilot's side.
{% endhint %}

{% stepper %}
{% step %}
Go to your Copilot Studio, switch to the **Agents** tab, and create a new blank agent.

<div align="left"><figure><img src="/files/PgKMfQ045d4zCrxTuwCP" alt="" width="563"><figcaption><p>Copilot agent creation screen</p></figcaption></figure></div>
{% endstep %}

{% step %}
Wait a while until the agent is provisioned and configure the basic details: name, description, model you want to use, and other data.

<div align="left"><figure><img src="/files/Y6WxKGaox7gRfAhFjc26" alt="" width="563"><figcaption><p>Agent configuration details</p></figcaption></figure></div>
{% endstep %}

{% step %}
Next, switch to the **Tools** tab and add a new tool:

<div align="left"><figure><img src="/files/i4gx6dymNXp2NBECzZvQ" alt="" width="563"><figcaption><p>Copilot tool creation screen</p></figcaption></figure></div>
{% endstep %}

{% step %}
Select **Model Context Protocol** as the tool type and fill the details:

* Server name: e.g. Timebook MCP
* Server description: e.g. AI operations on Timebook data
* Server URL: `https://mcp.timebook.net/mcp/`
* Authentication: OAuth 2.0 → Dynamic discovery

When ready, click 'Create'.

<div align="left"><figure><img src="/files/mUknCkmG95svNCwWZQvz" alt="" width="563"><figcaption><p>Timebook MCP configuration details</p></figcaption></figure></div>
{% endstep %}

{% step %}
Now we need to configure the link between the agent and the Timebook service. Expand the connection dropdown and click 'Create new connection':

<figure><img src="/files/yEmzgjXRKcowCVFudpQ4" alt=""><figcaption><p>Creating new connectoon to Timebook MCP</p></figcaption></figure>

The agent will request access in your Timebook account:

<div align="left"><figure><img src="/files/TxQACtn8sWgncxRxwzIu" alt="" width="375"><figcaption><p>Copilot access request to Timebook</p></figcaption></figure></div>
{% endstep %}

{% step %}
Once authorized, click 'Add and configure' to save the changes. If everything was configured correctly, the MCP will appear on your tools list:

<div align="left"><figure><img src="/files/RBkGkZt9TYU4Jyfre0re" alt="" width="563"><figcaption><p>Timebook MCP on Copilot agent's tools list</p></figcaption></figure></div>
{% endstep %}
{% endstepper %}

***

## Gemini CLI

{% stepper %}
{% step %}
Go to `~/.gemini/settings.json` and add an MCP server object with the following configuration:

```json
  "mcpServers": {
    "timebook-mcp-server": {
      "httpUrl": "https://mcp.timebook.net/mcp/",
      "authProviderType": "dynamic_discovery"
    }
  }
```

{% endstep %}

{% step %}
Launch the CLI by running `gemini` in the terminal. On the first run, it will ask you to approve its authorization in Timebook. Proceed with the instructions to finish configuration.

<div align="left"><figure><img src="/files/2oEcpxrO6j7RFjXXT2lo" alt="" width="375"><figcaption><p>Gemini CLI access request to Timebook </p></figcaption></figure></div>
{% endstep %}
{% endstepper %}

## MCP tools list

Timebook MCP supports the following tools (calls) that you can run within your AI service. The tools define the range of activities that you can perform using the Timebook data by asking the AI client of your choice.

{% hint style="info" %}
We advise to refer to the table in case of problems with getting the desired results. For example, you can ask the AI to use a specific tool `enter_name_here` for more precision.
{% endhint %}

<table><thead><tr><th width="45.744873046875" data-type="number">#</th><th>Name</th><th>Friendly name</th><th>Description</th></tr></thead><tbody><tr><td>1</td><td><code>create_contact</code> <sup><sub>NEW</sub></sup></td><td>Create contact</td><td>Creates a new contact with specified name, role, email address, and associated persona.</td></tr><tr><td>2</td><td><code>create_insight</code> <sup><sub>NEW</sub></sup></td><td>Create insight</td><td>Creates a new insight with specified title, item type, learning, quotes, and contacts.</td></tr><tr><td>3</td><td><code>create_link_between_task_and_item</code></td><td>Link existing items </td><td>Creates a link between an existing work item and an object (opportunity, insight, goal or work item).</td></tr><tr><td>4</td><td><code>create_opportunity</code></td><td>Create opportunity</td><td>Creates a new opportunity with specified title and (optional) problem statement.</td></tr><tr><td>5</td><td><code>create_product_initiative</code></td><td>Create product initiative</td><td>Creates a new product initiative with specified ID, name, and status.</td></tr><tr><td>6</td><td><code>create_project</code></td><td>Create project</td><td>Creates a new project in the specified workplace.</td></tr><tr><td>7</td><td><code>create_solution</code></td><td>Create solution</td><td>Creates a new solution in the workplace with specified ID, name, description/theme, and status.</td></tr><tr><td>8</td><td><code>create_workitem</code></td><td>Create work item</td><td>Creates a new work item with specified title, item type (task, bug, story, feature), and optional fields in the selected workplace.</td></tr><tr><td>9</td><td><code>get_basic_insights_info</code></td><td>Get insights</td><td>Retrieves a list of insights with object ID, title, and description.</td></tr><tr><td>10</td><td><code>get_basic_opportunities_info</code></td><td>Get opportunities</td><td>Retrieves all active opportunities together with their ID, title, and description.</td></tr><tr><td>11</td><td><code>get_company_by_id</code></td><td>Get company info</td><td>Retrieves the company matching the selected company ID together with business details, contact information and description.</td></tr><tr><td>12</td><td><code>get_contact_by_id</code></td><td>Get contact info</td><td>Retrieves detailed information (personal details, company associations, personas, description) for the specified contact ID.</td></tr><tr><td>13</td><td><code>get_contacts_by_persona_id</code></td><td>Get contacts by persona ID</td><td>Retrieves all contacts associated with the specified persona ID.</td></tr><tr><td>14</td><td><code>get_current_goals</code></td><td>Get current goals</td><td>Retrieves all active goals with attached key results.</td></tr><tr><td>15</td><td><code>get_custom_fields</code></td><td>Get custom fields</td><td>Retrieves all custom fields for the specified workplace.</td></tr><tr><td>16</td><td><code>get_goal_key_results</code></td><td>Get key results for goal</td><td>Retrieves all key results for the specified goals together with their progress.</td></tr><tr><td>17</td><td><code>get_interview_transcript</code></td><td>Get interview transcript</td><td>Retrieves the contents of the transcript of the specified interview.</td></tr><tr><td>18</td><td><code>get_item_custom_statuses</code></td><td>Get custom statuses</td><td>Retrieves all custom statuses for the specified object (opportunity, work item, or goal).</td></tr><tr><td>19</td><td><code>get_item_projects</code></td><td>Get projects of item</td><td>Retrieves all projects associated with the specified object (opportunity, task, goal, or insight) together with project details (name, status, theme, and summary).</td></tr><tr><td>20</td><td><code>get_item_solutions</code></td><td>Get solutions of item</td><td>Retrieves all solutions associated with the specified object (opportunity, task, goal, or insight) together with solution details (name, status, theme, and theme).</td></tr><tr><td>21</td><td><code>get_item_types_for_application </code><sup><sub><code>NEW</code></sub></sup></td><td>Get item types of application</td><td>Retrieves all item types associated with the specified application (module).</td></tr><tr><td>22</td><td><code>get_linked_insights_to_opportunity_ids</code></td><td>Get insights linked to opportunity</td><td>Retrieves all insights linked to the provided opportunity ID.</td></tr><tr><td>23</td><td><code>get_linked_items</code></td><td>Get items linked to object</td><td>Retrieves all items linked to the selected object (opportunity, insight, goal, or work item).</td></tr><tr><td>24</td><td><code>get_linked_opportunities_to_insight</code></td><td>Get opportunities linked to insight</td><td>Retrieves all opportunities generated from or related to the given insight.</td></tr><tr><td>25</td><td><code>get_opportunities_in_product_initiative</code></td><td>Get opportunities linked to product initiative</td><td>Retrieves all opportunities linked to the selected product initiative.</td></tr><tr><td>26</td><td><code>get_persona_by_id</code></td><td>Get persona by ID</td><td>Finds the persona matching the provided persona ID together with name, description, and associated metadata.</td></tr><tr><td>27</td><td><code>get_products</code></td><td>Get products</td><td>Retrieves all products in the workplace together with details (name, description, context, owner, and creation/update dates).</td></tr><tr><td>28</td><td><code>get_project_info</code></td><td>Get project info</td><td>Retrieves the details of the selected project (name, status, theme, summary).</td></tr><tr><td>29</td><td><code>get_sprint_info</code></td><td>Get sprint info</td><td>Retrieve the details of the selected sprint (title, status, start and end dates, team ID, summary).</td></tr><tr><td>30</td><td><code>get_sprint_work_items</code></td><td>Get work items of sprint</td><td>Retrieves all work items assigned to the selected sprint together with full details for every item.</td></tr><tr><td>31</td><td><code>get_work_items_by_friendly_id</code></td><td>Get work item by ID</td><td>Retrieves the specified work item in the selected workplace by its ID (e.g. <code>TB-123</code>).</td></tr><tr><td>32</td><td><code>get_work_items_in_project_or_solution</code>  <sup><sub>NEW</sub></sup></td><td>Get work items of project or solution</td><td>Retrieves all work items belonging to the selected project or solution together with full details for every item.</td></tr><tr><td>33</td><td><code>link_insight_to_opportunity</code></td><td>Link insight with opportunity</td><td>Creates a link between the insight and the selected opportunity.</td></tr><tr><td>34</td><td><code>link_opportunity_to_goal</code></td><td>Link opportunity with goal</td><td>Creates a link between the opportunity and the selected key result of the goal.</td></tr><tr><td>35</td><td><code>manage_opps_to_initiative</code></td><td>Link or unlink opportunities to product initiative</td><td>Creates or removes a link between the selected opportunities and the product initiative.</td></tr><tr><td>36</td><td><code>manage_goals_to_product_initiative_link</code></td><td>Link or unlink key results of goal and product initiative</td><td>Creates or removes a link between the specified key results of the goal and the product initiative.</td></tr><tr><td>37</td><td><code>manage_opportunities_to_solution_links</code></td><td>Link or unlink opportunities and solution</td><td>Creates or removes a link between the specified opportunities and the solution.</td></tr><tr><td>38</td><td><code>manage_workitems_to_solution_links</code>  <sup><sub>NEW</sub></sup></td><td>Link or unlink work items and solution</td><td>Creates or removes a link between the specified work items and the solution.</td></tr><tr><td>39</td><td><code>remove_link_between_items</code></td><td>Remove link between objects</td><td>Removes the link between the specified objects (opportunities, insights, goals, or work items).</td></tr><tr><td>40</td><td><code>retrieve_product_information</code></td><td>Get product info</td><td>Retrieves the details of the selected product (name, description, context, owner, and creation/update dates).</td></tr><tr><td>41</td><td><code>search_companies_by_workplace_and_name</code></td><td>Find companies</td><td>Finds the companies in the selected workplace filtered by company name.</td></tr><tr><td>42</td><td><code>search_contacts_by_workplace_and_name</code></td><td>Find contacts</td><td>Finds the contacts in the selected workplace filtered by first or last name.</td></tr><tr><td>43</td><td><code>search_document_by_id</code></td><td>Find documents by ID</td><td>Finds the document matching the specified document ID together with all pages and content.</td></tr><tr><td>43</td><td><code>search_documents_by_workplace_and_name</code></td><td>Find documents by name</td><td>Finds the documents in the selected workplace filtered by name and retrieves all pages and content for each matching document. </td></tr><tr><td>44</td><td><code>search_feedback_tickets_workitems_surveys_insights</code> <sup><sub>NEW</sub></sup></td><td>Find feedback tickets, work items, surveys, and insights</td><td>Finds feedback tickets, work items, surveys, and insights</td></tr><tr><td>45</td><td><code>search_insights</code></td><td>Find insights</td><td>Finds the insights matching, similar, or related to the concept of the query.</td></tr><tr><td>46</td><td><code>search_interviews_by_parameters</code></td><td>Find interviews by parameters</td><td>Finds the interviews filtered by date, product, contact, or company.</td></tr><tr><td>47</td><td><code>search_opportunities_by_ids</code></td><td>Find opportunities by ID</td><td>Finds all opportunities matching the provided opportunity ID.</td></tr><tr><td>48</td><td><code>search_opportunities_by_parameters</code></td><td>Find opportunities by parameters</td><td>Finds the opportunities filtered by contact ID, company ID, status, priority, assignee, or custom fields.</td></tr><tr><td>49</td><td><code>search_opportunities_by_query</code></td><td>Find opportunities by query</td><td>Finds the opportunities matching, similar, or related to the concept of the query.</td></tr><tr><td>50</td><td><code>search_personas_by_workplace_and_name</code></td><td>Find personas by workplace and name</td><td>Finds all personas in the selected workplace filtered by the persona name.</td></tr><tr><td>51</td><td><code>search_sprints</code></td><td>Find sprints</td><td>Finds all sprints belonging to one or more teams together with sprint details (ID, title, status, start and end dates).</td></tr><tr><td>52</td><td><code>search_swimlanes</code> <sup><sub>NEW</sub></sup></td><td>Find projects, releases, solutions, and initiatives</td><td>Finds solutions in the selected workplace filtered by chosen parameter together with their details (ID, name, status, and theme).</td></tr><tr><td>53</td><td><code>search_teams</code></td><td>Find active teams</td><td>Retrieves all active teams in the selected workplace.</td></tr><tr><td>54</td><td><code>set_item_parent</code></td><td>Add object to opportunity or goal</td><td>Adds an object to the selected opportunity or goal.</td></tr><tr><td>56</td><td><code>set_project_description</code> <sup><sub>NEW</sub></sup></td><td>Add description to project</td><td>Adds a description in the Markdown format to the specified project. Does not overwrite existing descriptions.</td></tr><tr><td>57</td><td><code>set_solution_description</code></td><td>Add description to solution</td><td>Adds a description in the Markdown format to the specified solution. Does not overwrite existing descriptions.</td></tr><tr><td>58</td><td><code>set_sprint_description</code></td><td>Add description to sprint</td><td>Adds a description in the Markdown format to the specified sprint. Does not overwrite existing descriptions.</td></tr><tr><td>59</td><td><code>update_goal_key_result</code></td><td>Update key result of goal</td><td>Updates the key result of the specified goal. Can be restricted to specific fields. </td></tr><tr><td>60</td><td><code>update_item</code></td><td>Update detail of item</td><td>Updates the title, description, priority, problem, and/or desired outcome of the specified object of any type in the workplace.</td></tr><tr><td>61</td><td><code>update_item_custom_field</code></td><td>Update custom field of item</td><td>Updates the specified custom field of an opportunity or a work item (e.g. importance, satisfaction, importance score).</td></tr><tr><td>62</td><td><code>update_item_custom_status</code></td><td>Update custom status of item</td><td>Updates the custom status of an object (opportunity, goal, or work item).</td></tr><tr><td>63</td><td><code>update_item_date_range</code></td><td>Update date range of item</td><td>Sets the start date and due date of an object (opportunity, goal, insight, or work item)</td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.timebook.ai/hc/integrations/mcp.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.