Docs

Use PartPin with your AI agent

Everything PartPin does for you on the dashboard — resolve a part number against your own catalog, register or update a part, run a zero-result query autopsy, confirm a write-back — your own AI agent can do too. There are three doors, all opened by one API key from the dashboard's API KEY card: a remote MCP server for Claude, ChatGPT/Codex, Cursor, VS Code and any other MCP client; a REST API with an OpenAPI document; and the partpin CLI. The agent acts as your workspace, under your workspace's own data — never another tenant's.

1. Get an API key

Sign in and open the dashboard. A full-access key is minted the first time you sign in; rotate it any time with the Rotate key button. The key is shown once. Put it in an environment variable — every snippet below reads PARTPIN_API_KEY — rather than pasting it into a file that gets committed.

2. Claude Code, claude.ai and Claude Desktop

Claude Code, from a terminal (the key is sent as a header on every request):

claude mcp add --transport http partpin https://partpin.net/mcp \
  --header "Authorization: Bearer $PARTPIN_API_KEY"

Or add it to a project's .mcp.json so the whole team gets it; Claude Code expands ${PARTPIN_API_KEY} from the environment:

{
  "mcpServers": {
    "partpin": {
      "type": "http",
      "url": "https://partpin.net/mcp",
      "headers": { "Authorization": "Bearer ${PARTPIN_API_KEY}" }
    }
  }
}

claude.ai and Claude Desktop: Customize → Connectors → Add custom connector. Name it PartPin, set the URL to https://partpin.net/mcp, choose “No sign in”, and under Request headers add Authorization with the value Bearer <your key>.

3. Cursor and VS Code

Cursor — ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "partpin": {
      "url": "https://partpin.net/mcp",
      "headers": { "Authorization": "Bearer ${env:PARTPIN_API_KEY}" }
    }
  }
}

VS Code — .vscode/mcp.json; the input prompt keeps the key out of the file:

{
  "servers": {
    "partpin": {
      "type": "http",
      "url": "https://partpin.net/mcp",
      "headers": { "Authorization": "Bearer ${input:partpin-key}" }
    }
  },
  "inputs": [{ "id": "partpin-key", "type": "promptString", "password": true, "description": "PartPin API key" }]
}

4. ChatGPT and Codex

Codex CLI and the ChatGPT desktop app share one MCP configuration:

[mcp_servers.partpin]
url = "https://partpin.net/mcp"
bearer_token_env_var = "PARTPIN_API_KEY"

ChatGPT's in-app custom connectors currently require OAuth or no authentication, and cannot send a fixed header. The server also exposes search and fetchin the shape ChatGPT's deep-research connectors expect, so the day sign-in with PartPin is available there, nothing else changes. Until then, use Codex above.

5. The CLI

Node 18 or newer. No install needed; npx fetches the partpin package. It talks to the same API with the same key:

# one-time: paste your key when prompted (stored in ~/.config/partpin/config.json, mode 600)
npx partpin login

npx partpin whoami
npx partpin resolve "6203DDU"
npx partpin search "6203" --limit 10
npx partpin register bearing-6203 6203-2RS --title "Deep groove bearing" --alias 6203DDU
npx partpin autopsy misses.txt            # one query per line; write-scope not required
npx partpin confirm "6203 special" bearing-6203
npx partpin queries --misses

# any command: --json for machine-readable output; PARTPIN_API_KEY overrides the saved key

6. The tools

What any MCP client sees from tools/list. “Read-only” and “destructive” are the server's own annotations; Claude and other clients use them to decide when to ask you first. PartPin ships no destructive tool today — nothing here can delete a catalog or a workspace.

Try the endpoint by hand — initialize and tools/list need no key:

curl -s -X POST https://partpin.net/mcp \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

7. REST API and OpenAPI

The MCP tools and the CLI are thin layers over /api/v1. The full description is at /openapi.json (OpenAPI 3.1), which any code generator or agent framework can read directly.

curl -s "https://partpin.net/api/v1/resolve?q=6203DDU" \
  -H "Authorization: Bearer $PARTPIN_API_KEY"

curl -s -X POST https://partpin.net/api/v1/parts \
  -H "Authorization: Bearer $PARTPIN_API_KEY" -H "Content-Type: application/json" \
  -d '{"id":"bearing-6203","sku":"6203-2RS","aliases":["6203DDU"]}'

Endpoints: GET /api/v1/me, GET /api/v1/resolve?q=, GET /api/v1/search?q=, POST /api/v1/parts, POST /api/v1/autopsy, POST /api/v1/confirm, GET /api/v1/queries.

8. Safety, limits and logging

• An API key acts as your workspace. An agent sees only your catalog, aliases and query log.
• Nothing here is destructive: register_part and confirm_match add or update, never delete.
• Rate limit: 300 agent calls per key per hour.
• Every authenticated call is logged (tool, key, outcome, duration) and shown back to you at GET /api/v1/me; rows are kept 30 days.
• Keys are stored hashed. Rotating one in the dashboard invalidates the old key immediately. Deleting your account deletes its keys.

Reviewed 2026-10-02. Protocol facts checked against modelcontextprotocol.io on that date.