MCP: error messages, limits and troubleshooting

These errors occur before a tool runs.

401 Unauthorized (-32001)

Missing or invalid bearer token, revoked key or expired OAuth token. For an organization-bound connection also: the connection's organization is no longer your active organization. The response header points to the resource metadata for OAuth clients.

Parse error (-32700)

The request body is not valid JSON.

Invalid Request (-32600)

The request is not JSON-RPC 2.0.

Method not found (-32601)

The method is not supported. Supported are initialize, ping, tools/list and tools/call.

Tool not found: <name> (-32601)

There is no tool with this name. Call tools/list.

Internal error (-32603)

Server error, often a brief database problem. Repeat the request.

These messages concern organization context, role, scope and modules. They are returned as JSON-RPC errors with code -32603.

Pass "organization" (name, slug, or ID) as an argument, or call list_organizations…

Account-wide connection without an organization header: pass the organization argument, set a header (X-Organization-Slug) or call list_organizations first.

Organization "…" not found or you are not a member.

The given organization does not exist or you are not an active member there.

Insufficient permissions for this tool

Role, scope or module are not sufficient. Check the tool catalog: minimum role, scope and module.

This tool requires an organization context.

find_team_free_slots needs an organization; provide it.

These messages come from the tools themselves. Errors inside a tool are returned as JSON-RPC errors with code -32603 and the tool's message.

… not found (e.g. Task not found, Project not found, Invoice not found)

The ID does not exist, belongs to another organization or is outside your visibility.

… does not belong to this organization

A reference (project, milestone, parent task) or an assignee does not belong to the organization.

A task cannot be its own parent

parentTaskId must not be the task's own ID.

Reserved or billed time entries cannot be edited / deleted

The time entry is reserved for an invoice or billed and therefore locked.

No running timer found

stop_timer finds no running timer for you.

Only draft invoices can be deleted

delete_invoice deletes drafts only. Correct issued invoices with create_invoice_correction.

Record a payment instead of setting an invoice to paid

The status paid cannot be set directly.

Issued invoice content cannot be changed / Invoice cannot return to an editable state

After finalization only the status can change; going back to draft is blocked.

Only a finalized invoice can be corrected

create_invoice_correction works only for non-draft invoices; edit a draft directly.

Time entry … (not completed and billable / must be approved / already assigned / belongs to another project)

Rules for line items from time entries in create_invoice: completed, billable, approved, same project, not used yet; EUR invoice.

This receipt has a document under legal hold and cannot be deleted.

Conflict 409 from delete_accounting_receipt; the attempt is written to the audit log.

Consent basis missing (TKG § 174) …

For cold outbound leads consentBasis must be documented (update_crm_lead) before a draft is created.

Produkt-Briefing missing …

Create the knowledgebase article with the configured Produkt-Briefing slug.

Recipient is on the suppression list

The recipient is blocked; no draft is created.

Draft is no longer open

Drafts that were already sent or discarded can no longer be changed.

Google Calendar not connected for this user.

Connect the calendar in the web app; list_calendar_events reports connected=false instead.

No analytics integration configured.

Set up PostHog or GA4 with an API key in the organization settings.

Budget is not in draft status

activate_budget works for draft budgets only.

These caps apply to lists and searches.

Standard lists

limit: default 50, max 200 (list_tasks, list_projects, list_time_entries, list_milestones, list_crm_leads, list_crm_email_drafts, list_invoices, list_kb_items, list_metrics, list_meetings, list_network_contacts, list_goals, list_notes, list_members, list_files, list_expenses, list_accounting_receipts).

Deviating limits

list_reviews: 20 / 100. search_kb: 5 / 20. search_network_contacts: 20 / 50. list_unscheduled_tasks: 30 / 100. find_similar_tasks: 6 / 20. list_calendar_events: 20 / 50. find_team_free_slots: maxResults 5 / 20, days 10 / 45. get_crm_weekly_briefing: weeks 1–12.

Email drafts

Subject at most 300 characters, body at most 20,000 characters.

Return format

Results come back as indented JSON text. Large lists are capped by limit – ask again with filters when needed.