# MCP adapter

Source: https://www.geardex.app/api-docs/mcp-adapter

API access requires the GearDex Studio plan and a scoped Studio API key.

Give AI agents scoped GearDex tools through the Studio API.

## Overview

The MCP adapter connects MCP hosts to the Studio API. Claude, Gemini, Cursor and other hosts use it as a set of GearDex tools.

Use MCP when an AI agent must use GearDex tools. To send HTTP requests from your own code, see [Studio API](https://www.geardex.app/api-docs/studio-api).

## Get started

The adapter is a standalone package. You do not need a GitHub account, an npm account or the GearDex source code. The package contains only the API client and its dependencies.

1. Create a Studio API key in **Settings**, **API & Agents**.
2. Give the key only the [scopes](https://www.geardex.app/api-docs/scopes) that your agent needs.
3. Install Node 22 or newer.
4. Add the adapter to your host: [Claude](https://www.geardex.app/api-docs/mcp-adapter/claude), [Gemini](https://www.geardex.app/api-docs/mcp-adapter/gemini) or [another MCP host](https://www.geardex.app/api-docs/mcp-adapter/other-hosts).
5. Restart the host. The host then starts the adapter.
6. Send a [starter prompt](https://www.geardex.app/api-docs/mcp-adapter#starter-prompts). Make sure that the agent can read your data.

**Run the standalone adapter**

```bash
npx --yes --package https://github.com/dylandersen/geardex-public/releases/download/mcp-v0.2.0/geardex-mcp-0.2.0.tgz geardex-mcp
```

**Environment variables**

```env
GEARDEX_BASE_URL=https://www.geardex.app
GEARDEX_STUDIO_API_KEY=gdx_live_your_key_here
```

You can use `https://www.geardex.app` or `https://geardex.app`. The adapter follows the redirect between the two addresses and keeps your key on the request.

[Download adapter 0.2.0](https://github.com/dylandersen/geardex-public/releases/download/mcp-v0.2.0/geardex-mcp-0.2.0.tgz), or see the [release and SHA-256 checksum](https://github.com/dylandersen/geardex-public/releases/tag/mcp-v0.2.0). At the first start, npx downloads the package. After that, npx uses the copy in the local npm cache. Each download has a version number, so the adapter changes only when you change the URL.

## Connect a host

- [Claude](https://www.geardex.app/api-docs/mcp-adapter/claude): Claude Desktop on macOS or Windows, and Claude Code.
- [Gemini](https://www.geardex.app/api-docs/mcp-adapter/gemini): the Gemini app on macOS or Windows, and Gemini CLI.
- [Other hosts](https://www.geardex.app/api-docs/mcp-adapter/other-hosts): Cursor, Hermes Agent and other hosts that start local MCP servers.

## Starter prompts

These prompts only read data, so you can use them with a read-only key. Each prompt includes the word GearDex. This tells the agent to use the GearDex tools.

**1. Check the connection**

```text
Using GearDex, how many pieces of gear do I have of each type?
```

**2. Full inventory**

```text
List all my GearDex gear grouped by type: brand, model, condition and status.
Page through until you have every item.
```

**3. Lost, stolen and wear**

```text
Is any of my GearDex gear reported lost or stolen?
For my camera bodies, show each shutter count against its rated life.
```

**4. The next two weeks**

```text
What GearDex shoots do I have in the next 14 days, and is any maintenance scheduled before them?
```

**5. Paperwork**

```text
Which of my GearDex warranties have expired or expire soon?
```

**6. Kits and packing**

```text
Which of my GearDex kits are ready to go out?
For my next GearDex shoot, show the packing list and the items that are not packed.
```

**7. Insurance**

```text
Which of my GearDex insurance policies expire in the next 30 days?
Which gear does no active policy cover?
```

**8. Rentals**

```text
Which GearDex rentals are open, and which rentals are past their return date?
```

Prompts that change records need the related write scope on your key. Examples are a service record or a gear checkout. Make sure that the agent asks you before it changes a record.

**Example: change records**

```text
Add my Sony FX3 and my 24-70mm lens to Saturday's GearDex shoot.
Hold them for the shoot dates. Tell me if another shoot or loan holds them.
```

## Tool map

The adapter has 69 tools. Each tool needs the same scope as the endpoint that it calls.

**GearDex MCP tools**

| Tool | Scope | Maps to |
| --- | --- | --- |
| `list_gear` | `gear:read` | GET /gear with type/search/pagination filters. |
| `find_gear` | `gear:read` | Search helper over gear brand/model with required query. |
| `get_gear_totals` | `gear:read` | Aggregated count by gear type. |
| `create_gear` | `gear:write` | POST /gear for trusted inventory sync tools. |
| `update_gear` | `gear:write` | PATCH /gear/{id} for trusted inventory updates. |
| `delete_gear` | `gear:write` | DELETE /gear/{id} for trusted inventory cleanup. |
| `list_shoots` | `shoots:read` | GET /shoots with status/date/search filters. |
| `create_shoot` | `shoots:write` | POST /shoots for trusted planning automations. |
| `update_shoot` | `shoots:write` | PATCH /shoots/{id} for timing, status, location, notes, or progress updates. |
| `delete_shoot` | `shoots:write` | DELETE /shoots/{id} for cancelled or duplicate plans. |
| `list_maintenance` | `maintenance:read` | GET /maintenance with status/date/search filters. |
| `create_maintenance` | `maintenance:write` | POST /maintenance for owned gear service scheduling. |
| `update_maintenance` | `maintenance:write` | PATCH /maintenance/{id} for status, cost, provider, date, notes, or gear reference updates. |
| `delete_maintenance` | `maintenance:write` | DELETE /maintenance/{id} for trusted service-record cleanup. |
| `list_documents` | `documents:read` | GET /documents with type, warranty, date, and search filters. |
| `get_analytics_summary` | `analytics:read` | GET /analytics aggregate summary payload. |
| `get_profile` | `profile:read` | GET /profile account + studio profile metadata. |
| `list_loans` | `loans:read` | GET /loans with status, borrower, and gear filters; each loan lists its items. |
| `get_loan` | `loans:read` | GET /loans/{id} with items and consumables. |
| `check_out_gear` | `loans:write` | POST /loans: check items or a kit out to a borrower. |
| `check_in_loan` | `loans:write` | POST /loans/{id}/check-in: return everything, or chosen items. |
| `extend_loan` | `loans:write` | PATCH /loans/{id} with a new due date. |
| `list_flags` | `loans:read` | GET /flags: open or resolved issues on gear. |
| `flag_gear` | `loans:write` | POST /flags: raise an issue on an item. |
| `check_availability` | `loans:read` | GET /availability for an item and date range. |
| `resolve_flag` | `loans:write` | PATCH /flags/{id}: resolve an open flag. |
| `get_gear` | `gear:read` | GET /gear/{id}: specs, insurance cover, kits, reservations, and flags. |
| `list_categories` | `gear:read` | GET /categories for category\_id on gear writes. |
| `list_locations` | `gear:read` | GET /locations for location\_id on gear writes. |
| `list_shutter_readings` | `gear:read` | GET /gear/{id}/shutter-readings: the shutter count log. |
| `log_shutter_reading` | `gear:write` | POST /gear/{id}/shutter-readings: log a count. |
| `list_kits` | `gear:read` | GET /kits with kind and name filters. |
| `get_kit` | `gear:read` | GET /kits/{id} with gear and readiness. |
| `create_kit` | `gear:write` | POST /kits: create a rig or kit. |
| `update_kit` | `gear:write` | PATCH /kits/{id}: rename, or add and remove gear. |
| `delete_kit` | `gear:write` | DELETE /kits/{id}. The gear stays in the library. |
| `list_incidents` | `gear:read` | GET /incidents: lost and stolen reports. |
| `report_incident` | `gear:write` | POST /incidents: report an item lost or stolen. |
| `update_incident` | `gear:write` | PATCH /incidents/{id}: recover, or add report details. |
| `list_consumables` | `gear:read` | GET /consumables with category and low-stock filters. |
| `adjust_consumable` | `gear:write` | POST /consumables/{id}/adjust: restock, use, or correct stock. |
| `list_insurance` | `documents:read` | GET /insurance: policies, certificates, and coverage totals. |
| `get_insurance` | `documents:read` | GET /insurance/{id} with the gear it covers. |
| `list_rentals` | `shoots:read` | GET /rentals with status, shoot, and overdue filters. |
| `create_rental` | `shoots:write` | POST /rentals: add gear rented in. |
| `update_rental` | `shoots:write` | PATCH /rentals/{id}: edit, pick up, or return. |
| `delete_rental` | `shoots:write` | DELETE /rentals/{id} and its shoot expense. |
| `get_shoot_gear` | `shoots:read` | GET /shoots/{id}/gear: the packing list. |
| `add_shoot_gear` | `shoots:write` | POST /shoots/{id}/gear: add and hold gear or a kit. |
| `update_shoot_gear` | `shoots:write` | PATCH /shoots/{id}/gear: pack, unpack, or remove. |
| `list_bookings` | `bookings:read` | GET /bookings with status/time filters. |
| `decide_booking_request` | `bookings:write` | PATCH /bookings/{id}: approve or decline; emails the client. |
| `list_inquiries` | `bookings:read` | GET /inquiries with status filters. |
| `list_jobs` | `shoots:read` | GET /jobs with status, client, and title filters. |
| `get_job` | `shoots:read` | GET /jobs/{id}: client, shoots, money, costs, and profit. |
| `list_quotes` | `money:read` | GET /quotes with status filters. |
| `create_quote` | `money:write` | POST /quotes: create a draft with line items and tax; does not send it. |
| `send_quote` | `money:write` | POST /quotes/{id}/send: email the client an acceptance link. |
| `list_invoices` | `money:read` | GET /invoices with installments and payments. |
| `record_payment` | `money:write` | POST /invoices/{id}/payments: record a manual payment. |
| `list_deliverables` | `shoots:read` | GET /shoots/{id}/deliverables. |
| `add_deliverable` | `shoots:write` | POST /shoots/{id}/deliverables: add a deliverable. |
| `deliver_to_client` | `shoots:write` | POST /shoots/{id}/deliverables/deliver: mark delivered and optionally email. |
| `get_shoot_profit` | `shoots:read` | GET /shoots/{id}/profit: booked/collected revenue, expenses and wear. |
| `list_clients` | `shoots:read` | GET /clients with search, status, and kind filters. |
| `get_client` | `shoots:read` | GET /clients/{id}: jobs, shoots, open tasks, and recent activity. |
| `create_client` | `shoots:write` | POST /clients: add a person or company. |
| `update_client` | `shoots:write` | PATCH /clients/{id}: change details, status, or follow-up. |
| `log_client_activity` | `shoots:write` | POST /clients/{id}/activities: log a note, call, email, or meeting. |

## Workflow ideas

Use these workflows with your Studio data:

**MCP workflow ideas**

| Workflow | Kind | Tools |
| --- | --- | --- |
| `Weekly Ops Brief` | automation | Use list\_shoots and get\_analytics\_summary to send a weekly studio summary. |
| `Pre-Shoot Gear Check` | assistant | Before a confirmed shoot, use list\_shoots, list\_gear and list\_maintenance. |
| `Service Queue Sync` | automation | Use create\_maintenance and update\_maintenance to copy changes from your repair queue into GearDex. |
| `Warranty Risk Monitor` | automation | Use list\_documents with warranty filters to find coverage that expires soon. |
| `Client Prep Snapshot` | assistant | Use find\_gear and list\_gear to make a packing list for a job. |
| `Overdue Chaser` | automation | Each morning, use list\_loans with status open, and send the overdue borrowers to Slack. |
| `Executive KPI Card` | dashboard | Each day, use get\_analytics\_summary and show KPI cards in Slack or Notion. |

**Prompt pattern: weekly studio brief**

```text
Use GearDex MCP tools to generate a Monday brief:
1) list_shoots for the next 14 days
2) list_maintenance for scheduled/in_progress items
3) list_documents where warrantyStatus is warning or critical
4) get_analytics_summary

Return:
- risks
- upcoming workload
- inventory readiness summary
```

**Prompt pattern: trusted maintenance update**

```text
Use GearDex MCP tools to close this service ticket:
1) find_gear for "Sony A7S III"
2) create_maintenance with service_type "Sensor cleaning"
3) update_maintenance to completed when the ticket is closed

Only use write tools if the configured API key includes maintenance:write.
```

## Security checklist

- Use one key for each host.
- Give each key only the scopes that its agent needs.
- Use keys that expire.
- Replace keys at regular intervals.
- If an unauthorized person gets access to a host or a computer, revoke its key immediately.
- Monitor the [audit activity](https://www.geardex.app/api-docs/audit-logs) in **Settings**, **API & Agents**.

## Troubleshooting

**MCP troubleshooting**

| Symptom | Area | Fix |
| --- | --- | --- |
| `Adapter will not start` | `setup` | Install Node 22 or newer. Make sure that the host can find npx, or use the full path to npx. On Windows, use npx.cmd. Set the key or --key-file, then restart the host. |
| `Additional properties are not allowed` | `version` | Adapters before 0.1.1 reject fields that the API added later, for example incident on gear. In your host config, change the download URL to the current version. Restart the host. |
| `401 key_not_found` | `auth` | GearDex does not know the key. After a pepper rotation, create a new key. A revoked key shows key\_revoked. An expired key shows key\_expired. |
| `403 insufficient_scope` | `authz` | The tool needs a scope that your key does not have. |
| `429 rate_limited` | `limits` | Wait for the time in the Retry-After header. Then send the request again. |
| `503 rate_limit_unavailable` | `availability` | The rate limiter is not available. Wait, then send read requests again. Before you send a write again, make sure that the first write did not complete. |
| `Timed out` | `network` | The write possibly completed. Before you send it again, examine the related list. Writes have no idempotency keys. |
| `Invalid input` | `validation` | Use real UUIDs and real calendar dates. An update must include at least one field that the endpoint accepts. |
| `Empty datasets` | `data` | The key is valid, but the account has no records for that scope or filter range. |