> For the complete documentation index, see [llms.txt](https://docs.zipwire.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zipwire.io/use-cases/for-agents/zipwire-mcp-server.md).

# Zipwire MCP Server

How to connect Claude Desktop to Zipwire's MCP server and use tools for timesheets, activities, workflows, and more

Zipwire runs an **MCP (Model Context Protocol) server** that exposes the Zipwire v1 API as tools for any MCP-compatible client—Claude Desktop, custom agents, or other tools that support the MCP standard.

**Server URL:** `https://zipwire.io/api/v1/mcp`

**Protocol:** JSON-RPC 2.0 with OAuth 2.1 (Dynamic Client Registration)

***

**MCP is for any client.** This guide uses Claude Desktop as an example, but the same server works with any MCP client that supports the standard.

***

## Quick Start: Connect Your MCP Client

This example uses Claude Desktop. The same server and OAuth flow work with any MCP client.

### 1. Log In to Zipwire

Open your browser and log in to [Zipwire](https://zipwire.io). Keep the browser tab open—you'll need to authorize your MCP client from here.

### 2. Open Your MCP Client Settings

In Claude Desktop (or your MCP client), open the connector/integration settings:

* **Claude Desktop:** Settings → Connectors
* **Other clients:** Consult your client's documentation for where MCP servers are configured

### 3. Add Zipwire as an MCP Server

Click the **+ Add** button to add a new server:

* **Name:** `Zipwire`
* **URL:** `https://zipwire.io/api/v1/mcp`
* **Advanced Settings:** Leave empty

Click **Add** to save.

### 4. Authorize Your Client

You'll see the Zipwire server in your list. Click **Connect** next to it.

A browser window will open to the Zipwire authorization page. Review the requested permissions (your client is asking for access to your Zipwire account and tools), then click **Authorize** to grant access.

### 5. Done!

Your MCP client now has access to all your Zipwire tools. You can start using them immediately by asking your client to help with timesheets, activities, workflows, and more.

***

## Available Tools by Surface

Zipwire's MCP server exposes tools organized by **surfaces** (functional areas). The tools available to you depend on which **features you have activated** in Zipwire.

**How tool availability works:**

1. **You activate a feature** by using it in Zipwire (e.g., create time entries, manage workflows, request collections)
2. **Your usage creates a persona** (Sender, Actor, Admin, etc.)
3. **Your persona determines which surfaces you can access** in the MCP server
4. **Each surface maps to a set of tools**

For example:

* If you've tracked time in the past 90 days → you have the **Sender** persona → you see Journal, Activities, Workflows, Timesheets tools
* If you've managed a collection → you have the **Collection Requestor** persona → you see CollectionAdmin tools
* If you've approved timesheets → you have the **Actor** persona → you see approval tools

**To enable more tools:** Use the feature on any channel: the website, WhatsApp, the zw CLI or MCP itself. For example, keeping your journal over WhatsApp or the CLI unlocks the Sender tools, and creating a workplace over MCP (`workplaces_create_workplace`) unlocks the admin tools: Clients, Assignments, Teams and the collection tools. Search appears once you have your first assigned workflow, which you can set up over MCP by creating a client and assigning yourself as approver or processor.

### Core Time & Attendance

**Journal** — Time Entry Management

* Create, edit, list, and delete daily time entries
* Track time against activities and dates
* Examples: `journal_create_entry`, `journal_list_entries`, `journal_get_entry`

**Activities** — Activity Code Management

* List, search, create, and rename activity codes
* Merge activity codes
* Examples: `activities_list`, `activities_search`, `activities_create`

**Timesheets** — Timesheet Submission & Approval

* List and view timesheets (both submitted and pending approval)
* Submit timesheets for approval
* Approve, reject, or process timesheets
* Run workflow commands on timesheets
* Examples: `timesheets_list`, `timesheets_submit`, `timesheets_approve`

### Workflow & Configuration

**Workflows** — Workflow Management

* Create and configure workflow templates
* List and retrieve workflow state
* Manage workflow boxes and routing
* Examples: `workflows_list`, `workflows_create`, `workflows_get`

**Account** — User Profile & Preferences

* Get/update profile information
* View locale and timezone settings
* Manage wallet information and preferences
* List your workplaces and create a new one (`workplaces_create_workplace`)
* Examples: `account_get_profile`, `account_update_profile`

**Dashboard** — Overview & Status

* Get summary of items needing attention
* View recent activity and aggregate counts
* Overview across all workplaces
* Examples: `dashboard_get_summary`

### Financial & Billing

**Invoicing** — Invoice Configuration

* Get and set invoice details (address, tax information, payment methods)
* Configure company invoice details
* Examples: `invoicing_get_details`, `invoicing_set_details`

**Payment Methods** — Payment Configuration

* List and manage payment methods
* Configure payment details
* Examples: `payment_methods_list`, `payment_methods_add`

**Companies** — Company Information

* List and view company details
* Get companies by relationship (clients, workplaces)
* View company invoice details
* Examples: `companies_list`, `companies_get`, `companies_get_by_relationship`

### Identity & Access

**Authentication** — Credentials & API Access

* Exchange API keys
* Manage OAuth connections
* View connected providers
* Examples: `auth_exchange_key`, `auth_list_connections`

**Documents** — Document Upload

* Upload personal documents to your account
* Examples: `documents_upload`

### Surveys & Collections

**CollectionAdmin** — Collection Review (admin/requestor)

* List and view collections and their status
* Review submitted items and ID check results (e.g. Yoti reports)
* Read self-declared identity data alongside document check outcomes
* Examples: `collections_list`, `collections_get`, `collection_items_get`
* **Note:** Designing and saving reusable collection templates is still web-only. To send someone a collection, see **People** below.
* See it in action: [Right to Work checks](/use-cases/identity-checks-right-to-work.md#reviewing-checks-with-claude) and the [UK Right to Rent template](/zipwire-collect/uk-right-to-rent-template.md#reviewing-checks-with-claude)

**People** — Workplace People & Collection Requests (admin/requestor)

* List and view the people in a workplace, and add a person
* Create a draft collection for a person from an existing template (`requestor_create_draft_collection`)
* **Beta:** build a one-off draft collection from a prompt (`requestor_create_draft_collection_from_prompt`). It isn't saved as a reusable template
* Examples: `people_list_workplace_people`, `people_add_person`

**CollectionRespondent** — Survey Response (respondent only)

* View and respond to assigned collections/surveys
* Upload documents for requested collections
* Creating collections is a requestor task (see CollectionAdmin and People above)

### Advanced Features

**Teams** — Team Management (admin)

* Create, rename and delete teams
* Add and remove members, make a team primary, and invite people

**Clients** — Clients & Assignment Setup (admin)

* Find or create a client (`clients_create_client`)
* Set up the assignment by assigning yourself as approver or processor, or assigning groups (`clients_assign_me_as_approver`, `clients_assign_me_as_processor`, `clients_assign_groups`)
* You need to be an admin of the workplace

**Assignments** — Assignment Management (admin)

* List and view assignments, and update assignment details
* Invite contractors to an assignment (`assignments_add_sender`, subject to the free-sender limit) and remove them
* Set rate plans and billing plans (e.g. `assignments_update_rate_plan`, `assignments_set_billing_plan`)
* Add and deactivate assignment activities

**Search** — Workplace Search

* Search timesheets and invoices within a workplace by text (e.g. invoice number or name) and date range
* Available once you have an assigned timesheet workflow

**Not available over MCP yet:** generating client invoices from approved timesheets (done from the Prep stage in the web app; see [Understanding invoicing](/zipwire-approve/understanding-invoicing.md)) and designing reusable collection templates. Contractor (sender) invoices are created automatically whenever a timesheet is sent, including over MCP.

***

## Tools by User Role

Not all tools are available to every user. Here's what you can access based on your role:

| Role                                         | Tools Available                                                                                                                    |
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Sender** (tracked time)                    | Journal, Activities, Workflows, Timesheets, Companies, Invoicing, Payment Methods, Documents, Account, Authentication, Dashboard   |
| **Approver/Actor** (approved timesheets)     | Timesheets, Account, Authentication, Dashboard                                                                                     |
| **Workflow Admin** (assigned workflows)      | Timesheets, Workflows, Assignments, Clients, Teams, Search, Companies, Account, Authentication, Dashboard                          |
| **Workplace Admin**                          | Companies, Clients, Assignments, Teams, Invoicing (workplace), Account, Authentication, Dashboard, plus the Collection Admin tools |
| **Collection Admin** (requested collections) | CollectionAdmin, People, Dashboard, Account, Authentication                                                                        |
| **Collection Respondent**                    | CollectionRespondent, Documents, Account, Authentication, Dashboard                                                                |

**Don't see a tool you need?** Use that feature first, on any channel (e.g., track time on WhatsApp, request a collection, or approve a timesheet). Once you've activated the feature, the corresponding tools will appear in your MCP client on the next connection.

***

## Authentication

Zipwire's MCP server uses **OAuth 2.1 Dynamic Client Registration** to authenticate Claude Desktop connections.

### How It Works

1. **Initial Connection**: When you click "Connect" in Claude Desktop, the Zipwire MCP server registers Claude as an OAuth client
2. **Authorization**: You're redirected to Zipwire's authorization page where you approve the connection
3. **Token Exchange**: Claude receives an OAuth access token that's used for all subsequent requests
4. **Ongoing Access**: Claude uses the access token to call Zipwire tools—no API key entry required

### For API Clients (Non-Claude)

If you're building your own MCP client or testing the API directly, you can use Zipwire API keys:

```bash
curl -X POST https://zipwire.io/api/v1/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": "1"
  }'
```

API keys are available in Zipwire under **Account → Authentication → API Keys**.

***

## Using Tools in Your MCP Client

Once connected, you can ask your MCP client to use Zipwire tools:

**Example 1: Create a Time Entry**

```
Create a time entry for today with 8 hours logged against the "Development" activity.
```

Your client will call `journal_create_entry` with:

* Date: today
* Hours: 8
* Activity: "Development"

**Example 2: List My Timesheets**

```
Show me all my pending timesheets awaiting approval.
```

Your client will call `timesheets_list` with appropriate filters.

**Example 3: Submit for Approval**

```
Submit my current timesheet for approval.
```

Your client will call `timesheets_submit` to route the timesheet through your workflow.

***

## Rate Limits & Quotas

Zipwire's MCP server enforces rate limits per API key:

* **Standard API Keys**: 1,000 requests per hour
* **Premium API Keys**: 10,000 requests per hour

If you exceed your quota, the server returns HTTP 429 with a `Retry-After` header.

***

## Troubleshooting

### Authorization Failed or "Connect" Button Not Working

* Verify you're logged into Zipwire in your browser before clicking "Connect" in your MCP client
* Check that cookies are enabled in your browser
* Try clicking "Connect" again—the authorization page should open in a new window
* If the page doesn't open, copy the URL from your client and open it manually in your browser

### "Tool not found"

* Verify the tool is available for your user role/account type
* Some tools (e.g., Clients, Assignments and Teams) are only available to workplace admins
* Check your account permissions in Zipwire
* Re-authorize your client to ensure it has the latest permissions

### Tools Not Appearing in Your Client

* Verify the server was successfully added and shows as "Connected" (green indicator)
* Try disconnecting and reconnecting the Zipwire server
* Restart your MCP client
* Check that your Zipwire account has the required roles for the tools you need

### "Connection refused"

* Verify the MCP server URL is correct: `https://zipwire.io/api/v1/mcp`
* Check your internet connection
* Ensure your MCP client has network access
* Try connecting from a different network to rule out firewall issues

***

## What's Next

* [How to verify agent authorization using ProofPacks](/use-cases/for-agents/mcp-agent-authorization.md)
* [How agents can prove compliance for regulated APIs](/use-cases/for-agents/compliant-agent-operations.md)
* [Zipwire API Documentation](/api/api.md)
* [Account Management & Authentication](/tools-and-integrations/authentication.md)

***

**Questions?** Reach out to Zipwire support or check our [API documentation](/api/api.md).