MCP server

Every Clerq instance is also a Model Context Protocol (MCP) server. It exposes 43 tools spanning clients, projects, tasks, time tracking, invoicing, expenses and team management, so an AI assistant like Claude can operate your back office on your behalf - using a scoped OAuth token, never your password.

The server is part of the app itself. If your instance is running, the MCP endpoint is live at /api/mcp - there is nothing extra to deploy.

How access works

The instance acts as an OAuth 2.1 authorization server, so connecting an assistant is a standard authorization flow:

1. The assistant discovers the endpoints from /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server.
2. It registers itself dynamically - no client ID to copy by hand.
3. You are sent to your instance's sign-in page, then to a consent screen where you approve the connection.
4. The assistant receives a bearer token scoped to your active business. Every tool call runs as you, against that one business, and respects the same permissions the web app enforces.

Because the token is scoped per business and the tools go through the same checks as the UI, an assistant can never see or change data outside the business you connected.

Connect an assistant

Point your MCP client at the /api/mcp URL of your instance. In Claude, add it as a custom connector:

https://clerq.example.com/api/mcp

Claude registers itself, walks you through sign-in and consent, and the tools become available. Other MCP clients take a URL the same way:

{
  "mcpServers": {
    "clerq": {
      "url": "https://clerq.example.com/api/mcp"
    }
  }
}

On a local instance the URL is http://localhost:3000/api/mcp. If you set a custom APP_PORT or run behind a proxy, use that public address instead.

The tools

The 43 tools cover the back office end to end. A representative sample:

• Clients - list_clients, create_client, update_client, add_client_note, archive_client
• Projects and tasks - list_projects, create_project, list_tasks, create_task, set_task_status
• Time - start_timer, stop_timer, log_time, get_running_timer, list_task_time
• Invoicing - create_draft_invoice, generate_invoice_from_time, add_invoice_line, issue_invoice, mark_invoice_paid, get_invoice_pdf_link
• Expenses - list_expenses, create_expense, mark_expense_paid, delete_expense
• Team - list_team_members, invite_team_member, revoke_invitation
• Connectivity - whoami confirms which business the token is bound to

Money is always handled in minor units (cents), and dates as ISO 8601, so the assistant cannot fumble a rounding or timezone detail.

Example

Ask your assistant something like "Draft an invoice to Northwind for this month's unbilled time, one line per task" and it chains the right tools: create_draft_invoice to open a draft, then generate_invoice_from_time to fill it from the unbilled, billable hours. It hands back a draft for you to review - issuing it (which assigns the permanent number) stays a deliberate, separate step.

You can also get a shareable PDF without a browser login: get_invoice_pdf_link returns a signed URL that is valid for 15 minutes.

The assistant only ever holds a scoped bearer token for the business you approved. Revoke its access by rotating BETTER_AUTH_SECRET, which invalidates outstanding tokens and signed links.