Setup

1. Create a personal API token

In bestdesq, open Profile → Settings → API Tokens and click + Token.

• Name: a descriptive label, e.g. Claude Code MacBook
• Permissions: full access (recommended for your own trusted clients) or select individual scopes
• Expiry: 30 days / 90 days / 1 year / No expiry

The token is shown once in plain text. Directly below the token a ready-to-use JSON snippet appears for your MCP client configuration – copy it with one click.

2. Configure your MCP client

The MCP endpoint for your bestdesq account is:

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

Claude Code – ~/.config/claude-code/.mcp.json or project-local .mcp.json:

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

Cursor – enter the same structure under Settings → MCP. Cursor detects the server automatically on the next chat start.

Restart your client after saving. Once the connection is established, the agent will confirm it – or just ask: "Connect to bestdesq."

3. Add the bestdesq skill (recommended)

The bestdesq skill is a text file that explains to your AI agent how bestdesq works – workflows, conventions, when to act and when to ask. Without the skill, agents can use the tools but have to improvise more.

You set up the skill once in your AI environment. It is a plain text file and can be adapted to your own workflows.

---

Available tools

bestdesq provides 32 MCP tools, grouped by area. Which tools a token can see depends on the configured permissions – a read-only token won't even see bestdesq_create_task.

Projects & overview

Tool	What it does
bestdesq_list_projects	List all projects, filterable by status
bestdesq_get_project_summary	Project details with task statistics, budget and time utilisation
bestdesq_get_dashboard	Personal overview: open tasks, deadlines, project health, due invoices
bestdesq_get_status_keys	Query valid status values for a project workflow

Typical requests:

"Which projects are active and where are there budget issues?"
"Give me my daily overview with all open tasks and due invoices."

Tasks

Tool	What it does
bestdesq_list_tasks	List tasks in a project, filterable by status and priority
bestdesq_get_task	Task details including comments and checklists
bestdesq_search_tasks	Full-text search across task titles
bestdesq_find_overdue_tasks	Find overdue tasks
bestdesq_create_task	Create a new task
bestdesq_update_task	Update a task – status, title, priority, assignment
bestdesq_create_task_heading	Create a heading / group in the project
bestdesq_add_comment	Add a comment to a task
bestdesq_add_checklist	Create a checklist group on a task
bestdesq_add_checklist_items	Add items to an existing checklist
bestdesq_toggle_checklist_item	Check or uncheck an individual item

Typical requests:

"Create a task 'Revise hero section' with high priority in the Website Relaunch project."
"Which tasks in project 26-004 are overdue and who are they assigned to?"
"Mark task 1234 as done."

Time tracking

Tool	What it does
bestdesq_log_time	Book time on a task
bestdesq_get_time_summary	Time report by project, user or period

Typical requests:

"Book 90 minutes on task 'Wireframes' in project 26-002, today, description: concept revised."
"How much time did the team book on the TMV portal in April?"

Outgoing invoices

Tool	What it does
bestdesq_list_planned_invoices	List planned invoices
bestdesq_get_invoicing_status	Overview: due, overdue, recently created
bestdesq_get_invoice	Read a single invoice
bestdesq_generate_invoice	Convert a planned invoice into a real invoice
bestdesq_update_planned_invoice	Edit a planned invoice

Typical requests:

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

Incoming invoices

Tool	What it does
bestdesq_fetch_incoming_invoices	Fetch new invoices from the email inbox; e-invoices are parsed automatically
bestdesq_parse_incoming_invoice	Parse a PDF or XML file and extract document data
bestdesq_list_incoming_invoices	List saved incoming invoices
bestdesq_get_incoming_invoice	Read a single incoming invoice
bestdesq_import_incoming_invoices	Save parsed documents as incoming invoices
bestdesq_update_incoming_invoice	Edit a saved incoming invoice
bestdesq_upload_incoming_invoice_attachment	Link an attachment to an incoming invoice

Typical requests:

"Fetch new incoming invoices from the inbox and show me the extracted amounts."
"Import the parsed invoices – the supplier is already assigned."

Contacts

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

Typical requests:

"Is there already a supplier entry for Muster AG?"
"Create a new customer entry for Digital Studios GmbH."

---

Permissions

Every API token has scopes that determine which tools it may use. Scopes follow the pattern entity:action – a token with task:write implicitly also has read access.

The effective access is always the intersection of the token scopes and the user's role. A token can never do more than the user would be able to see in the bestdesq UI.

Recommended scope profiles:

Use case	Scopes
Read and research only	project:read, task:read, time-record:read
Task work and time tracking	project:read, task:write, time-record:write
Outgoing invoices	additionally invoice:read, invoice:write
Incoming invoices	incoming-invoice:read, incoming-invoice:write, organisation:read
Full access (own trusted clients)	no scopes selected

---

What the agent does not do

• Invoices are not sent. The agent can create invoices – sending them is up to you.
• The agent acts within your token's scope. What your token is not allowed to do, the agent won't even see as an available tool.
• No automatic actions. The agent only executes tool calls on explicit request – it does not monitor in the background.

---

Further reading

• API documentation – complete REST API reference
• MCP server overview – what the MCP server enables