How-to guides

How to set up authentication

Goal: Provide credentials so every tool call succeeds without being prompted repeatedly.

The server needs two values for every request:

Option A: Environment variables in the config file (recommended)

Set both values in claude_desktop_config.json under the env key. The server reads these automatically on every call.

"env": {
  "ZENSKAR_ORGANIZATION": "org_abc123",
  "ZENSKAR_AUTH_TOKEN": "eyJhbGciOiJSUzI1NiJ9..."
}

Option B: Pass credentials per tool call

Omit the env block entirely. Claude will prompt for credentials when it needs them. This is less convenient but useful if you're working across multiple organizations.

Option C: Environment variables set in your shell

Export them in your shell profile (~/.zshrc, ~/.bashrc, etc.):

export ZENSKAR_ORGANIZATION="org_abc123"
export ZENSKAR_AUTH_TOKEN="your-token"

Then restart Claude Desktop so it inherits the environment.

How to generate and approve an invoice

Goal: Generate an invoice for a specific contract and billing period, then approve it.

Step 1: Generate the invoice

Ask Claude:

Generate an invoice for contract [contract ID] covering March 2026.

Claude calls generateInvoice with the contract ID and date range. Invoice generation is asynchronous — Claude will call getInvoiceGenerationStatus or listJobs to confirm completion.

Step 2: Review the invoice

Ask Claude:

Show me the line items for invoice [invoice ID].

Claude calls getInvoiceLineItems so you can confirm the amounts before approving.

Step 3: Approve

Ask Claude:

Approve invoice [invoice ID].

Claude calls approveInvoice. The invoice is now in an approved state and can be charged or paid.

Step 4: Optionally, auto-charge

Ask Claude:

Auto-charge invoice [invoice ID] via the payment gateway.

Claude calls createInvoiceCharge.

How to record a payment and issue a credit note

Goal: Record a manual payment against an invoice and, if needed, create a credit note for a partial refund.

Record the payment:

Record a $1,000 manual payment against invoice [invoice ID].

Claude calls createPayment with the amount and invoice allocation.

Issue a credit note:

Create a $250 credit note against invoice [invoice ID].

Claude calls createInvoiceCreditNote. Credit notes are listed via listCreditNotes or retrieved by ID using getCreditNoteById.

Refund a payment:

Refund payment [payment ID] in full.

Claude calls refundPayment. Partial refunds are also supported — specify the amount.

How to create a contract with phases and pricing

Goal: Create a contract with an initial phase and add expansion pricing to it.

Step 1: Create the contract

Ask Claude:

Create a contract for customer [customer ID] starting on 1 May 2026 with monthly billing.

Claude calls createContract.

Step 2: Add a phase

Ask Claude:

Add an add-on phase to contract [contract ID] starting 1 June 2026.

Claude calls createContractPhase.

Step 3: Add pricing to the phase

Ask Claude:

Add $500/month pricing to the new phase on contract [contract ID].

Claude calls createContractPhasePricing.

Step 4: Verify

Ask Claude:

Show me the full details for contract [contract ID], including all phases and pricing.

Claude calls getContractById and returns the complete contract structure.

How to run accounting reports

Goal: Pull a balance sheet and income statement for a reporting period.

Ask Claude:

Show me the balance sheet as of 31 March 2026.

Claude calls getBalanceSheet.

Show me the income statement for Q1 2026.

Claude calls getIncomeStatement.

Trigger revenue recognition up to 31 March 2026.

Claude calls recogniseRevenue. This is an async operation: Claude will poll listJobs or getJobById to confirm completion.

How to use the server outside Claude Desktop

Goal: Use the Zenskar MCP Server with a different AI application or your own tooling.

Install globally:

npm install -g mcp-zenskar

Then run:

ZENSKAR_ORGANIZATION="your-org-id" ZENSKAR_AUTH_TOKEN="your-token" mcp-zenskar

Run without installing:

npx mcp-zenskar

Use a local development build:

git clone <repo>
cd mcp-zenskar
npm install
npm install -g .

Point your AI application to the local entry point:

{
  "command": "node",
  "args": ["/absolute/path/to/mcp-zenskar/src/server.js"],
  "env": {
    "ZENSKAR_ORGANIZATION": "your-org-id",
    "ZENSKAR_AUTH_TOKEN": "your-token"
  }
}