MCP adapter
Give AI agents scoped GearDex tools through the Studio API.
StudioThe Studio API, webhooks, and MCP adapter are included with the Studio plan.Compare plans
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.
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.
- Create a Studio API key in Settings, API & Agents.
- Give the key only the scopes that your agent needs.
- Install Node 22 or newer.
- Add the adapter to your host: Claude, Gemini or another MCP host.
- Restart the host. The host then starts the adapter.
- Send a starter prompt. Make sure that the agent can read your data.
npx --yes --package https://github.com/dylandersen/geardex-public/releases/download/mcp-v0.2.0/geardex-mcp-0.2.0.tgz geardex-mcpGEARDEX_BASE_URL=https://www.geardex.app
GEARDEX_STUDIO_API_KEY=gdx_live_your_key_hereYou 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, or see the release and SHA-256 checksum. 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: Claude Desktop on macOS or Windows, and Claude Code.
- Gemini: the Gemini app on macOS or Windows, and Gemini CLI.
- 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.
Using GearDex, how many pieces of gear do I have of each type?List all my GearDex gear grouped by type: brand, model, condition and status.
Page through until you have every item.Is any of my GearDex gear reported lost or stolen?
For my camera bodies, show each shutter count against its rated life.What GearDex shoots do I have in the next 14 days, and is any maintenance scheduled before them?Which of my GearDex warranties have expired or expire soon?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.Which of my GearDex insurance policies expire in the next 30 days?
Which gear does no active policy cover?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.
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.
| 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:
| 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. |
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 summaryUse 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 in Settings, API & Agents.
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. |