The Model Context Protocol (MCP) makes bestdesq readable and operable for AI assistants. This post shows how to connect your AI agent to your bestdesq account – and what it does for you once connected.

What this is about

Many people now work with an AI assistant such as Claude, or with a code editor that has AI built in, such as Cursor. These assistants write, summarise and answer questions. Your projects, tasks and invoices are out of their reach, though. They live in bestdesq, and the assistant knows nothing about them.

The Model Context Protocol is an open standard that closes exactly this gap. Think of it as a shared plug: an application offers its functions through the plug, and every AI assistant that knows the plug can use them. bestdesq has such a plug built in, an MCP server. An assistant connected to bestdesq through it is called an AI agent below: it can look things up in bestdesq and also create or change things there.

In daily work it looks like this: you ask your agent "Which projects are over budget right now?", it looks it up in bestdesq and answers with the figures. You write "Book 90 minutes on the task Wireframes", and the time is in your time tracking. You no longer switch back and forth between the chat and bestdesq.

38

tools are offered by the MCP server – for projects, tasks, time tracking, invoices and contacts.

You stay in control:

• The agent works with a personal access key that you create yourself and can revoke at any time.
• It can never do more than you can in bestdesq.
• It only acts when you ask it to.
• It creates invoices, but it does not send them.

AI in the app or AI from outside

There are two ways to bring AI and a business application together. Many applications build in their own assistant: a chat window in the app, backed by an AI provider the vendor has chosen. bestdesq takes the other way. It has no built-in assistant; instead it opens up through MCP to the assistant you already use.

AI from outside via MCP

• You work with the assistant you already know.
• You choose the AI provider – and with it, who gets to see your data.
• One assistant for several tools: you book your time from the code editor without leaving it.
• No AI surcharge in the price of bestdesq.

AI in the app

• There right away, no setup.
• The vendor decides provider and model.
• Knows only this one application.
• Its cost is part of the price or comes as a surcharge.

The way from outside has its price: you need an AI program that speaks MCP, and you set up the connection once. How good the answers are depends on your assistant, not on bestdesq.

I still think it is the better way, because the AI stays your tool and not mine. You decide which assistant you use, what it costs and which provider you trust with your data. And when a better assistant comes along tomorrow, you switch without anything having to change in bestdesq.

FeatureMCP server / AI

What you need

You need a bestdesq account with an active subscription; the free trial counts. You also need an AI program that can connect to MCP servers over the internet (in MCP terms: Streamable HTTP). Below I describe the setup for Claude Code and Cursor. Other programs follow the same pattern if they let you add your own sign-in line to the connection (a header).

Setting it up takes about ten minutes. From here on it gets more technical.

Setup step by step

1. Create an access key in bestdesq

   The agent signs in to bestdesq with a personal access key, an API token. Open Profile from your profile picture, then Settings on the left and the API Tokens tab. + Token creates a new one.

   Profile › Settings › API Tokens. For each token the list shows when it was last used and when it expires.

   

   In the dialog you set three things:

   • Token name: a name you will recognise later, for example "Claude Code laptop".
   • Expiration: 30 days, 90 days, 1 year or no expiry. 90 days is preselected.
   • Permissions: Full access is preselected – everything you may do in bestdesq yourself. Untick it to choose one by one what the agent may read or edit. Which choice covers what is explained below under Permissions.

   After Create, bestdesq shows the token exactly once. Copy it right away and keep it like a password. It starts with bdq_pat_.

2. The address of your MCP server

   Your account's MCP server has this address; replace your-account with the name you use to sign in to bestdesq:

   https://your-account.bestdesq.app/mcp

3. Connect your AI program

   Claude Code: one command in the terminal is enough. Insert your address and your token:

   claude mcp add --transport http bestdesq https://your-account.bestdesq.app/mcp \
     --header "Authorization: Bearer bdq_pat_YOUR_TOKEN"

   Without further options the connection applies to the project in which you run the command, and only to you. With --scope user bestdesq is available in all your projects.

   If a whole team is to use the connection, it belongs in the .mcp.json file of the project. Do not put the token in there; refer to an environment variable that everyone sets on their own machine. That way no key ends up in the repository:

   {
     "mcpServers": {
       "bestdesq": {
         "type": "http",
         "url": "https://your-account.bestdesq.app/mcp",
         "headers": {
           "Authorization": "Bearer ${BESTDESQ_TOKEN}"
         }
       }
     }
   }

   Cursor: add the connection to ~/.cursor/mcp.json (for all projects) or to .cursor/mcp.json in the project folder. Cursor writes environment variables as ${env:NAME}:

   {
     "mcpServers": {
       "bestdesq": {
         "url": "https://your-account.bestdesq.app/mcp",
         "headers": {
           "Authorization": "Bearer ${env:BESTDESQ_TOKEN}"
         }
       }
     }
   }

   Save and restart Cursor.

4. Check the connection

   In Claude Code, claude mcp list in the terminal shows whether the server is connected; inside a session, /mcp opens the same overview. In Cursor you find the servers under Customize › MCPs.

   Then ask your agent a first question, for example: "Which tasks in bestdesq are overdue?" If it answers with your tasks, the connection works.

Tip

Create a separate token for each device and each program. If a laptop gets lost, you revoke exactly that one token and all other connections keep working.

What your agent can do then

The MCP server offers the agent 38 tools. You do not need to know them; the agent picks the right one itself. The overview helps you judge what you can ask. The tools return their texts in the language of your account.

Overview and projects

Tool	What it does
bestdesq_daily_briefing	Daily overview: overdue tasks, projects with problems, upcoming invoices, leads without activity
bestdesq_get_dashboard	Your personal dashboard
bestdesq_list_projects	List projects, filtered by status or number
bestdesq_get_project_summary	Overview of one project; amounts depend on your role
bestdesq_update_project	Change a project's title, description, status, dates or budget
bestdesq_project_close_readiness	Check whether a project can be closed

"Give me my daily overview." "Which projects are over budget?"

Tasks

Tool	What it does
bestdesq_list_tasks	Tasks of a project, filtered by status or priority
bestdesq_get_task	One task with description, comments, checklist and subtasks
bestdesq_search_tasks	Full-text search across all projects
bestdesq_find_overdue_tasks	Tasks past their due date that are not done
bestdesq_get_status_keys	The valid statuses of a project
bestdesq_create_task	Create a task
bestdesq_update_task	Change status, priority and fields, move tasks
bestdesq_create_task_heading	Create a heading for grouping, up to three levels
bestdesq_add_comment	Write a comment, in your name
bestdesq_add_checklist	Add a checklist to a task
bestdesq_add_checklist_items	Add items to a checklist
bestdesq_toggle_checklist_item	Tick an item or open it again

"Create the task 'Rework the home page' with high priority in the project Website relaunch." "Mark the task Wireframes as done."

Time tracking

Tool	What it does
bestdesq_log_time	Book minutes on a task
bestdesq_get_time_summary	Booked time per person and task

"Book 90 minutes on the task Wireframes, today, description: concept revised."

Outgoing invoices

Tool	What it does
bestdesq_get_invoicing_status	Due this month, overdue, recently created
bestdesq_list_planned_invoices	Planned invoices, such as instalments
bestdesq_invoicing_readiness	Which planned invoices are ready and what holds the others back
bestdesq_get_invoice	One invoice in detail
bestdesq_update_planned_invoice	Correct a planned invoice before it is created
bestdesq_generate_invoice	Turn a planned invoice into a real one
bestdesq_convert_due_invoices	Create all due, ready invoices at once – as a preview first if you like
bestdesq_payment_followup	Overdue, unpaid invoices; creates internal reminder tasks on request

"Which invoices are due this month?" "Create the instalment invoice for Müller GmbH, service period May."

Incoming invoices

Tool	What it does
bestdesq_fetch_incoming_invoices	Fetch new invoices from the mailbox set up for them and read them
bestdesq_parse_incoming_invoice	Read a single XRechnung, ZUGFeRD or PDF file
bestdesq_import_incoming_invoices	Save read documents as incoming invoices
bestdesq_list_incoming_invoices	List incoming invoices
bestdesq_get_incoming_invoice	One incoming invoice in detail
bestdesq_update_incoming_invoice	Correct supplier, account, due date, status or project
bestdesq_upload_incoming_invoice_attachment	Attach a PDF or image to an incoming invoice

"Fetch the new invoices from the mailbox and show me the amounts."

Contacts

Tool	What it does
bestdesq_list_organisations	List customers and suppliers
bestdesq_search_organisations	Search by name, short name or VAT ID
bestdesq_create_organisation	Create an organisation

"Is there already a supplier called Muster AG?"

Permissions

Every token carries permissions. They follow the pattern area and level, such as read projects or edit projects; whoever may edit may also read. The agent only sees the tools its permissions reach. A read-only token is not even offered the tool that creates tasks.

Tasks are a special case. In bestdesq, tasks belong to projects, leads or offers. The task tools therefore need permissions for all three areas: projects, leads and offers. If one is missing, the agent sees no tasks.

For	Permissions
Looking things up	read projects, leads and offers; read time tracking
Tasks and time tracking	edit projects, leads and offers; edit time tracking
Outgoing invoices	additionally read or edit invoices
Incoming invoices	edit incoming invoices, read organisations
Your own, trusted programs	full access

Your role stands above everything. A token can never do more than you yourself: your role always limits what the token may access – even with full access.

What the agent does not do

• It sends nothing. It creates invoices as open. You check and send them in bestdesq. Even for overdue invoices it sends no reminder; at most it creates a task to remind you.
• It does not work in the background. The server only acts when your agent makes a request. There is no monitoring and no automation.
• It stays within your limits. What token and role do not allow, it cannot do. Your tokens handle at most 1,000 requests per hour.

Ending access

Under Profile › Settings › API Tokens you see all your tokens with the time they were last used. Revoke ends access immediately; a program using that token cannot get in from then on. Nobody but you sees or manages your tokens, not even someone with the owner role in the account.

Want to try it yourself?

The demo runs without sign-up.

Open demo

Further reading

• MCP server at a glance – what the AI connection in bestdesq makes possible
• API documentation – the REST interface for your own development