> 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

**Note:** Collection management via MCP is currently limited. Most collection operations require using the Zipwire web interface.

**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/blob/main/api/v1/README.md)
* [Account Management & Authentication](https://github.com/zipwireapp/gbk-tz-docs/blob/main/fundamentals/getting-started/authentication.md)

***

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.zipwire.io/use-cases/for-agents/zipwire-mcp-server.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.