v1.0 · read-only

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).

Server URLhttps://mcp.firstplug.co/mcp
TransportStreamable HTTP
AuthOAuth 2.1 + PKCE
AccessRead-only · 8 tools

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.

  1. 1Your AI tool calls the server and receives 401 with the protected-resource metadata.
  2. 2The tool registers itself and opens First Plug Connect in the browser.
  3. 3You sign in with your First Plug account and approve access for your workspace.
  4. 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.
  5. 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.

get_member_overviewMember overviewreadOnlyHint

Everything about one person: contact and address, team, assigned assets, active shipment and offboarding status.

Main inputsmember_id
list_membersList membersreadOnlyHint

List and count people with filters. Totals are exact for the filters.

Main inputsstatusteamcountrycitysearchresume_cursorscan_all
list_assetsList assetsreadOnlyHint

Sweep and count the device fleet: status, category, location, holder country, warranty, MDM, condition.

Main inputsstatuscategorycondition…resume_cursorscan_all
track_assetTrack assetreadOnlyHint

One asset: current location and holder, price, specs, active shipment and shipment history.

Main inputsasset_id
list_shipmentsList shipmentsreadOnlyHint

Shipments with status, legs, price, tracking and the exact missing fields that block them.

Main inputsidstatusorder_idasset_id
track_quotesTrack quotesreadOnlyHint

Quote requests: lifecycle status, quoted price with breakdown, the order generated and rejection reasons.

Main inputsidsearch
get_recordsGet recordsreadOnlyHint

Secondary entities: teams, offices, activity (audit log), webhooks and settings.

Main inputsentityidresume_cursorscan_all

Tool 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/whoamiSession context: workspace, scopes and mcp_version.
fp://tenant/overviewWorkspace counts at a glance.
fp://attention/queueItems that need attention (summary + top 20).
fp://attention/blocking-shipmentsMembers whose missing data is blocking a shipment.
fp://officesOffices 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", … }