Quickstart guides

Quickstart 1: Connect the server in Claude Desktop

By the end of this tutorial, Claude Desktop will be connected to the Zenskar MCP Server and able to respond to prompts about your Zenskar data.

What you'll need:

• Claude Desktop installed
• A Zenskar account with API access
• Node.js 18 or later installed (node --version to check)
• Your Zenskar Organization ID and API token (see Authentication Reference)

Step 1: Open your Claude Desktop config file

On macOS, open a terminal and run:

open ~/Library/Application\ Support/Claude/claude_desktop_config.json

If the file doesn't exist yet, create it:

mkdir -p ~/Library/Application\ Support/Claude
touch ~/Library/Application\ Support/Claude/claude_desktop_config.json

On Windows, the config file is located at:

%APPDATA%\Claude\claude_desktop_config.json

Step 2: Add the Zenskar server entry

Paste the following into the config file, replacing the placeholder values with your real credentials:

{
  "mcpServers": {
    "zenskar": {
      "command": "npx",
      "args": ["mcp-zenskar"],
      "env": {
        "ZENSKAR_ORGANIZATION": "your-org-id",
        "ZENSKAR_AUTH_TOKEN": "your-bearer-token"
      }
    }
  }
}

Note: If you already have other MCP servers configured, add the "zenskar" entry inside the existing "mcpServers" object — don't replace it.

Step 3: Restart Claude Desktop

Fully quit and reopen Claude Desktop. The server starts automatically on launch.

Step 4: Verify the connection

In Claude Desktop, type:

Show me my Zenskar customers.

If the connection is working, Claude will call listCustomers and return results from your account. If you see an error, check the Authentication Reference to confirm your credentials are correct.

Quickstart 2: Your first Zenskar workflow

This tutorial walks through a complete, realistic workflow: finding a customer, checking their contracts, and listing their unpaid invoices.

🚧

Prerequisite: Complete Quickstart 1 first.

Step 1: Find a customer

Ask Claude:

List my Zenskar customers.

Claude calls listCustomers and returns a paginated list. Note the ID or name of a customer you want to explore.

Step 2: Get the customer's contracts

Ask Claude:

Show me all contracts for [customer name].

Claude calls listContracts with a customer filter. You'll see contract IDs, statuses, and date ranges.

Step 3: Check for unpaid invoices

Ask Claude:

List all unpaid invoices for [customer name].

Claude calls listInvoices filtered by customer and status. You now have a clear picture of what's outstanding.

Step 4: Approve an invoice

Pick one of the unpaid invoices and ask:

Approve invoice [invoice ID].

Claude calls approveInvoice. The invoice status changes to approved and is ready for payment collection.

You've completed a full read-then-act workflow using natural language. The same pattern applies to any domain — contracts, payments, products, accounting.

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

Reference

Reference material is for looking things up. It is complete, accurate, and consistent. It does not explain how to accomplish goals.

Authentication Reference

Every tool invocation requires two parameters. The server resolves them in this order:

1. Values passed directly in the tool call (highest priority)
2. ZENSKAR_ORGANIZATION environment variable
3. ZENSKAR_AUTH_TOKEN environment variable

Token format detection is automatic:

No credentials are stored or logged by the server.

Customers, Contacts & Addresses

Customers

Contacts

Customer Addresses

Payment Methods

Contracts

Invoices & Credit Notes

Invoices

Credit Notes

Payments

Products, Plans & Quotes

Products

Plans (Templates)

Quotes

Accounting

Metrics, Events & Other

Billable Metrics (Aggregates)

Usage Events (Raw Metrics)

Custom Attributes & Tax

Business Entities

Jobs & Utilities

Core Concepts

Core concepts are for understanding. They provide context, rationale, and background — not instructions.

What is MCP and why does it matter?

MCP (Model Context Protocol) is an open protocol that allows AI assistants to call external tools and APIs in a structured, reliable way. Instead of asking Claude to "figure out" how to call an API from documentation, MCP gives Claude a typed, discoverable set of tools it can invoke directly.

The Zenskar MCP Server packages the entire Zenskar REST API surface — 103 operations — as MCP tools. This means you can interact with your billing, contracts, and accounting data using plain language, and Claude will translate your intent into precise API calls.

The key benefits are:

• No code required. You don't need to write API clients or know Zenskar's REST endpoints.
• Composability. Claude can chain multiple tool calls to accomplish complex workflows — for example, finding a customer, identifying their open invoices, and approving them in a single conversation.
• Auditability. Every action goes through the Zenskar API and is recorded in your account's audit log.

How the server handles authentication

The server is stateless — it stores no credentials between calls. Every tool invocation independently supplies authentication headers to the Zenskar API.

Token format detection is automatic. If your token is a JWT (starts with eyJ), it's sent as a Bearer token. Otherwise it's sent as an API key via the x-api-key header. You don't need to configure this; the server detects it at runtime.

This design means you can switch between API keys and JWT tokens without changing your configuration — you only need to update the token value.

How credentials are resolved at runtime

Credentials follow a clear precedence chain:

1. Inline tool call parameters — if credentials are passed directly in a tool invocation, they take priority. This is useful when working across multiple Zenskar organizations in the same session.
2. Environment variables — ZENSKAR_ORGANIZATION and ZENSKAR_AUTH_TOKEN serve as a fallback. Setting these in the config file is the recommended default for single-organization use.

If neither source provides credentials, the tool call will fail with an authentication error. The server will not attempt to prompt interactively outside of Claude's conversation context.

Design decisions and limitations

Why 103 separate tools?

MCP works best when each tool has a single, well-defined purpose. Rather than exposing a generic "call Zenskar API" tool, each operation is discrete. This lets Claude reason accurately about what it's doing, reduces ambiguity in tool selection, and makes error messages meaningful.

Asynchronous operations

Some Zenskar operations — invoice generation and revenue recognition in particular — are asynchronous. The server exposes listJobs and getJobById so Claude can poll for completion. In practice, Claude will do this automatically when it knows an operation is async, but you can also ask explicitly: "Check the status of job [job ID]."

No data stored by the server

The MCP server is a thin proxy. It receives tool calls, constructs HTTP requests to the Zenskar API, and returns the response. No data is cached, logged, or stored by the server itself. All persistence happens in your Zenskar account.

Scope of this server

The server covers the full published Zenskar API surface as of the time of release. If Zenskar adds new API endpoints after a given server version is published, those endpoints won't be available until the server package is updated. Run npm outdated -g mcp-zenskar to check for a newer version.