> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.zenskar.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

| Value           | Where to find it                        |
| --------------- | --------------------------------------- |
| Organization ID | Zenskar Dashboard → Settings → General  |
| API Token       | Zenskar Dashboard → Settings → API Keys |

**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.

```json theme={null}
"env": {
  "ZENSKAR_ORGANIZATION": "22998477-f7eb-4757-a452-d482bbe7acc5",
  "ZENSKAR_AUTH_TOKEN": "your-token"
}
```

**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.):

```bash theme={null}
export ZENSKAR_ORGANIZATION="22998477-f7eb-4757-a452-d482bbe7acc5"
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:**

```bash theme={null}
npm install -g mcp-zenskar
```

Then run:

```bash theme={null}
ZENSKAR_ORGANIZATION="your-org-id" ZENSKAR_AUTH_TOKEN="your-token" mcp-zenskar
```

**Run without installing:**

```bash theme={null}
npx mcp-zenskar
```

**Use a local development build:**

```bash theme={null}
git clone <repo>
cd mcp-zenskar
npm install
npm install -g .
```

Point your AI application to the local entry point:

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

***