First Plug MCP documentation
First Plug MCP is a remote Model Context Protocol server that gives AI assistants read-only access to a First Plug workspace: members, assets, shipments, quotes and workspace records. It is built and operated by First Plug on top of the First Plug public API (/api/v1).
Quickstart
Add the server URL in your AI tool, sign in to First Plug in the browser window that opens and approve access. There is nothing to copy or paste.
Claude
Settings → Connectors → Add custom connector, paste the URL and click Connect:
https://mcp.firstplug.co/mcp
ChatGPT
Settings → Apps → Advanced settings, turn on developer mode and create an app with the URL:
https://mcp.firstplug.co/mcp
Claude Code
Run in a terminal, then /mcp to sign in:
claude mcp add --transport http firstplug https://mcp.firstplug.co/mcp
Cursor
Settings → MCP → Add new MCP server, or ~/.cursor/mcp.json:
{ "mcpServers": { "firstplug": { "url": "https://mcp.firstplug.co/mcp" } } }Other clients
Any client that supports remote MCP servers over Streamable HTTP with OAuth:
https://mcp.firstplug.co/mcp
Authentication
The connector uses OAuth 2.1 with PKCE and dynamic client registration. Users approve access once; the session renews on its own.
- 1Your AI tool calls the server and receives 401 with the protected-resource metadata.
- 2The tool registers itself and opens First Plug Connect in the browser.
- 3You sign in with your First Plug account and approve access for your workspace.
- 4First Plug creates a key for the connection server-to-server. The key never crosses the browser or the AI tool: it travels sealed (AES-256-GCM) inside the tokens.
- 5The tool gets an access token (valid one hour) and a refresh token. The server is stateless and stores no session data.
Tools reference
Every tool is annotated with readOnlyHint: true and only reads data. No tool creates, updates or deletes anything in v1.
searchSearchreadOnlyHintPeople by name or email, devices by name or serial and shipments by order id, all at once. Entry point when you only have a name.
querycountrycityteamget_member_overviewMember overviewreadOnlyHintEverything about one person: contact and address, team, assigned assets, active shipment and offboarding status.
member_idlist_membersList membersreadOnlyHintList and count people with filters. Totals are exact for the filters.
statusteamcountrycitysearchresume_cursorscan_alllist_assetsList assetsreadOnlyHintSweep and count the device fleet: status, category, location, holder country, warranty, MDM, condition.
statuscategorycondition…resume_cursorscan_alltrack_assetTrack assetreadOnlyHintOne asset: current location and holder, price, specs, active shipment and shipment history.
asset_idlist_shipmentsList shipmentsreadOnlyHintShipments with status, legs, price, tracking and the exact missing fields that block them.
idstatusorder_idasset_idtrack_quotesTrack quotesreadOnlyHintQuote requests: lifecycle status, quoted price with breakdown, the order generated and rejection reasons.
idsearchget_recordsGet recordsreadOnlyHintSecondary entities: teams, offices, activity (audit log), webhooks and settings.
entityidresume_cursorscan_allTool names are 64 characters or fewer and every tool has a human-readable title.
Resources
Read-only context the assistant can load before calling tools.
fp://session/whoami | Session context: workspace, scopes and mcp_version. |
fp://tenant/overview | Workspace counts at a glance. |
fp://attention/queue | Items that need attention (summary + top 20). |
fp://attention/blocking-shipments | Members whose missing data is blocking a shipment. |
fp://offices | Offices list. |
fp://{member|shipment|asset|office|quote|team}/{id} | Detail of a single entity. |
Data and privacy
The connector only reads the workspace approved by the person who connected it. Every connection gets the same fixed set of read-only permissions, whatever that person’s role.
What the connector reads
- Members: name, work and personal email, phone, position, start date, team, office, country and city, delivery address, assigned assets, offboarding status.
- Assets: model, serial, category, status, condition, warranty, location, holder, price.
- Shipments: status, origin and destination, dates, tracking, price, missing fields.
- Quotes: status, quoted price and breakdown, generated order, rejection reason.
- Workspace: teams, offices, activity log, webhooks and settings.
What it never does
- Never receives your conversation or prompts: only the tool calls your assistant makes.
- Never writes, changes or deletes data in v1.
- Never stores your workspace data: the server is stateless and keeps no database.
- Never exposes the API key to the browser or the AI tool.
Operational logs record the tool name, pages read and response size, for reliability. Connections can be revoked in Integrations → API keys. Privacy policy · Terms of service
Limits and versioning
- List tools return one API page by default. The assistant uses resume_cursor, or scan_all=true, when you need more.
- Counts use summary.total, which is exact for the filters applied.
- The First Plug public API rate limits apply.
- The server version is reported by GET /health and by fp://session/whoami.
GET https://mcp.firstplug.co/health
→ { "ok": true, "mcp_version": "1.0.0", "auth": "oauth", … }