> 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

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 in Zipwire's website first. Once you've activated it, the corresponding tools will appear in your MCP client.

### 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
* 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:** Creating and configuring new collections is still web-only
* 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)

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

* View and respond to assigned collections/surveys
* Upload documents for requested collections
* Collection management (create, configure) is web-only

### Advanced Features

**Teams** — Team Management (admin)

* Team management is currently web-only via the Zipwire interface
* Full team management (create, configure, membership) requires using the web app

**WorkplaceAdmin** — Workspace Configuration (admin)

* Workspace configuration is currently web-only
* Full workspace setup and policy management requires using the web app

**Search** — Global Search

* Global search is currently available via the web interface only

***

## 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, Documents, Account, Authentication, Dashboard |
| **Approver/Actor** (approved timesheets)     | Timesheets, Account, Dashboard                                                                       |
| **Workflow Admin** (assigned workflows)      | Timesheets, Workflows, Account, Authentication, Companies, Teams, WorkplaceAdmin, Search             |
| **Workplace Admin**                          | Companies, WorkplaceAdmin, Account                                                                   |
| **Collection Admin** (requested collections) | CollectionAdmin, Dashboard, Account, Authentication, WorkplaceAdmin                                  |
| **Collection Respondent**                    | CollectionRespondent, Documents, Account, Dashboard                                                  |

**Don't see a tool you need?** Use that feature in Zipwire's website first (e.g., create a time entry, 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., WorkplaceAdmin) are only available to 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](https://github.com/zipwireapp/gbk-tz-docs/tree/main/api/v1/README.md)
* [Account Management & Authentication](https://github.com/zipwireapp/gbk-tz-docs/tree/main/fundamentals/getting-started/authentication.md)

***

**Questions?** Reach out to Zipwire support or check our [API documentation](https://github.com/zipwireapp/gbk-tz-docs/tree/main/api/v1/README.md).