集成
将 AI 应用连接到 VentionDesk
此页面尚无中文版本；下方显示的是英文原版。
VentionDesk is the back office of freelance developers and small software studios: customer projects with tasks, support tickets with response times, customers, invoices and quotes, time tracking, documents and a customer portal. The VentionDesk connector lets Claude, ChatGPT, Cursor, Codex or any other client that speaks the Model Context Protocol (MCP) work with that data — with exactly the permissions you grant when you connect.
You need a VentionDesk account as owner or team member of a business. Customer accounts of the customer portal cannot connect an AI app. The rest of the documentation is in German; this page is the English entry point. Deutsche Fassung: KI-Apps verbinden.
Set up the connection
- Add the connector. In your AI app, add an MCP server (often called "connector" or "integration") with this URL:
https://api.ventiondesk.com/mcp. Nothing else is needed — the app discovers the sign-in on its own (OAuth 2.1 with dynamic client registration; the metadata is athttps://api.ventiondesk.com/.well-known/oauth-protected-resource). - Sign in. The app opens a browser window with the VentionDesk sign-in. If you are already signed in, it continues directly.
- Consent. VentionDesk shows a consent page with the app's name. There you choose:
- the business, if you belong to more than one,
- the permissions — team members can only grant what the owner has released for AI apps,
- the projects — all (including future ones) or a selection.
- Connected. You return to the app. From now on it works with exactly these permissions — not with your own. If you decline, nothing is stored.
Claude (claude.ai, Desktop, mobile): Settings › Connectors › Add custom connector, name "VentionDesk", URL https://api.ventiondesk.com/mcp, then "Connect". Whether custom connectors are available depends on your Claude plan and organization settings.
Claude Code: run claude mcp add --transport http ventiondesk https://api.ventiondesk.com/mcp, then /mcp in Claude Code and sign in to "ventiondesk".
ChatGPT: Settings › Apps & Connectors (custom MCP servers require developer mode), new connector with URL https://api.ventiondesk.com/mcp and authentication OAuth. Which plans allow custom connectors is decided by OpenAI.
Cursor, Codex and others: add https://api.ventiondesk.com/mcp as a remote MCP server (Streamable HTTP). The client receives a 401 with a pointer to the metadata, registers itself and starts the sign-in.
Permissions
The OAuth scopes a client requests (openid, email, profile) only cover the sign-in. What the app may do in VentionDesk is decided on the consent page:
| Permission | What the app may do |
|---|---|
projects:read | Read projects: name, status, repository, open tasks. |
tasks:read | Read tasks with their history. |
tasks:write | Claim tasks, report results, create new tasks. |
agent:run | Open and close an agent run, so changes are logged per session. |
deployments:read | Read commits, pull requests and deployments of the connected repositories. |
notes:write | Create notes and turn them into tasks (API only). |
tickets:read | Read support tickets with their history, including customer names and screenshots. |
tickets:write | Add internal notes and reply drafts; nothing reaches the customer. |
tickets:reply | Send replies to customers by email, without a person reviewing them first. A fixed notice marks them as AI-written. |
invoices:write | Create draft invoices and edit their line items. Finalising, sending, cancelling and payments stay with the owner. |
quotes:write | Create, edit and delete draft quotes. Sending, accepting and declining stay with the owner. |
errors:read | Read open errors from the business's error tracker (metadata only). |
errors:write | Mark an error as resolved in the error tracker and in VentionDesk. |
time:read | Read tracked time with the person's name — no rates, no amounts. |
stats:read | Read a project's key figures for a report — no revenue, budget or costs. |
roadmap:write | Read, create and edit roadmap phases; deleting stays with the owner. |
ideas:write | Create new ideas; reading, editing and deleting stay with the owner. |
By default, team members may grant only projects:read, tasks:read, tasks:write, deployments:read and agent:run. The owner can release more under Einstellungen › Meine KI-Apps (Settings › My AI apps; the VentionDesk interface is in German). A tool whose permission is missing answers with a clear "missing permission" error.
Tools
The connector offers 38 tools. Each one calls the VentionDesk API with the permissions of your connection. "Read" tools change nothing; "Write" tools add data; "Overwrite/Delete" and "Sends email" tools are marked destructive, so clients ask before running them.
Projects and tasks
| Tool | What it does | Permission | Kind |
|---|---|---|---|
ventiondesk_list_projects | Lists the projects this connection may see. | projects:read | Read |
ventiondesk_get_project | One project with repository, branch, stack and task counts. | projects:read | Read |
ventiondesk_list_tasks | Lists tasks; claimable returns only tasks an agent may take over. | tasks:read | Read |
ventiondesk_get_task | One task with history, project context and, on request, its images. | tasks:read | Read |
ventiondesk_claim_next_task | Claims the next open task by the runner's rule and returns it. | tasks:write | Write |
ventiondesk_claim_task | Claims a task atomically — two agents never get the same one. | tasks:write | Write |
ventiondesk_report_task_result | Reports progress, a question, review or done (with evidence). | tasks:write | Write |
ventiondesk_create_task | Creates a task for the owner to decide on. | tasks:write | Write |
ventiondesk_start_run | Opens an agent run that logs this session's claims and reports. | agent:run | Write |
ventiondesk_finish_run | Closes the agent run with a status and a one-line summary. | agent:run | Overwrite |
Support tickets
| Tool | What it does | Permission | Kind |
|---|---|---|---|
ventiondesk_list_tickets | Lists tickets with key, subject, status and priority. | tickets:read | Read |
ventiondesk_get_ticket | One ticket with its history, without email addresses. | tickets:read | Read |
ventiondesk_add_ticket_note | Adds an internal note the customer never sees. | tickets:write | Write |
ventiondesk_draft_ticket_reply | Saves a reply draft; a person sends it. | tickets:write | Write |
ventiondesk_send_ticket_reply | Emails a reply to the customer immediately. | tickets:reply | Sends email |
Draft invoices and quotes
| Tool | What it does | Permission | Kind |
|---|---|---|---|
ventiondesk_list_invoice_drafts | Lists draft invoices. | invoices:write | Read |
ventiondesk_get_invoice_draft | One draft invoice with line items. | invoices:write | Read |
ventiondesk_create_invoice_draft | Creates a draft invoice for a project's customer. | invoices:write | Write |
ventiondesk_invoice_from_unbilled | Turns unbilled time into a draft, one line item per entry. | invoices:write | Write |
ventiondesk_add_invoice_position | Adds a line item to a draft invoice. | invoices:write | Write |
ventiondesk_update_invoice_position | Changes a line item of a draft invoice. | invoices:write | Overwrite |
ventiondesk_delete_invoice_position | Removes a line item from a draft invoice. | invoices:write | Delete |
ventiondesk_list_quote_drafts | Lists draft quotes. | quotes:write | Read |
ventiondesk_get_quote_draft | One draft quote with line items. | quotes:write | Read |
ventiondesk_create_quote_draft | Creates a draft quote for a project's customer. | quotes:write | Write |
ventiondesk_update_quote_draft | Changes title or validity of a draft quote. | quotes:write | Overwrite |
ventiondesk_delete_quote_draft | Deletes a draft quote (it has no number yet). | quotes:write | Delete |
ventiondesk_add_quote_position | Adds a line item to a draft quote. | quotes:write | Write |
ventiondesk_update_quote_position | Changes a line item of a draft quote. | quotes:write | Overwrite |
ventiondesk_delete_quote_position | Removes a line item from a draft quote. | quotes:write | Delete |
Errors, time, reports and planning
| Tool | What it does | Permission | Kind |
|---|---|---|---|
ventiondesk_list_project_errors | Lists a project's open errors from the error tracker. | errors:read | Read |
ventiondesk_resolve_error | Marks an error resolved in the error tracker, then in VentionDesk. | errors:write | Overwrite |
ventiondesk_list_time_entries | Lists tracked time without rates or amounts. | time:read | Read |
ventiondesk_get_project_report | Key figures for a status report, without money. | stats:read | Read |
ventiondesk_list_roadmap | Lists a project's roadmap phases. | roadmap:write | Read |
ventiondesk_create_roadmap_phase | Adds a roadmap phase. | roadmap:write | Write |
ventiondesk_update_roadmap_phase | Changes, reorders or completes a phase. | roadmap:write | Overwrite |
ventiondesk_create_idea | Adds an idea to the backlog. | ideas:write | Write |
What the connector does not do: finalise, send, cancel or pay invoices; send, accept or decline quotes; delete tickets, tasks, roadmap phases or errors; read, change or delete ideas; move money. Those steps stay with a person in VentionDesk.
Example prompts
- "Which tasks can be picked up in the project alpha-webshop right now? Show me the three oldest." — uses
ventiondesk_list_projectsandventiondesk_list_tasks. - "Work on the next open VentionDesk task." — uses
ventiondesk_claim_next_task(same selection as the task runner, with description, history, project and board link), thenventiondesk_report_task_resultwith the run ID it returned, and closes the round withventiondesk_finish_run. Screenshots are only loaded when needed (withAttachments: up to three images of 1 MB each, other files as links valid for one hour). - "Take task #14, read why the last attempt failed, and once the fix is merged report it for review with the commit SHA as evidence." — uses
ventiondesk_get_task,ventiondesk_claim_taskandventiondesk_report_task_result. - "Summarise ticket TK-1044 and draft a polite reply in German for me to review." — uses
ventiondesk_list_tickets,ventiondesk_get_ticketandventiondesk_draft_ticket_reply. - "Create a draft invoice for alpha-webshop from all unbilled hours up to 30 September and show me the line items." — uses
ventiondesk_get_project,ventiondesk_invoice_from_unbilledandventiondesk_get_invoice_draft. - "Write a short status report for alpha-webshop: progress, open errors and the next roadmap milestone." — uses
ventiondesk_get_project_report,ventiondesk_list_project_errorsandventiondesk_list_roadmap. - "Add an idea to the backlog: dark mode for the customer portal, high potential." — uses
ventiondesk_create_idea.
Disconnect and expiry
Under Einstellungen › Meine KI-Apps you see your connections in all businesses: app, permissions, projects, connected on and last used. Trennen (disconnect) ends a connection immediately, including tokens the app already holds. A connection that has not been used for 90 days ends on its own. The owner sees the connections of everyone in the business and can disconnect each one.
Every connection and every disconnect is recorded in the business's activity log; changes made by an app are logged with app and person, as far as VentionDesk logs that change.
Privacy
What the app reads goes to its provider — for example Anthropic, OpenAI or Anysphere — and is processed there under that provider's terms. For your business, that provider is a recipient you choose; for tickets, customer data and time entries with names you usually need a data processing agreement with it. VentionDesk itself stores the app, the person, the permissions, the projects and the times of connecting, last use and disconnecting; email addresses of ticket requesters are left out of tool responses.
Details are in the privacy policy (section "Verbundene KI-Apps"; German) and the data processing agreement. Legal notice: Impressum.
Support
Questions and problems: support@ventiondesk.com （在新标签页中打开） or the contact page. Please include the app you connected (for example Claude or ChatGPT), the time and the error message the tool returned.