Docs

Use Circuit Sherpa with your AI agent

Everything Circuit Sherpa does for you in the browser — search parts across Digi-Key and Mouser, price a BOM at your build quantities, watch a part with a price alert — your own AI agent can do for you too. There are three doors, all opened by one API key from Settings → Agent access: 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 circuitsherpa CLI. The agent acts as you, under your plan's limits, and can never place an order or spend money.

1. Get an API key

Sign in and open Settings → Agent access. Name the key after the thing that will use it (“Claude Code on my laptop”) and pick a scope: read for search, part detail, history and listing alerts; write to also price BOMs and create or delete alerts. The key is shown once. Put it in an environment variable — every snippet below reads CIRCUITSHERPA_API_KEY — rather than pasting it into a config 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 circuitsherpa https://circuitsherpa.com/mcp \
  --header "Authorization: Bearer $CIRCUITSHERPA_API_KEY"

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

{
  "mcpServers": {
    "circuitsherpa": {
      "type": "http",
      "url": "https://circuitsherpa.com/mcp",
      "headers": { "Authorization": "Bearer ${CIRCUITSHERPA_API_KEY}" }
    }
  }
}

claude.ai and Claude Desktop: Customize → Connectors → Add custom connector. Name it Circuit Sherpa, set the URL to https://circuitsherpa.com/mcp, choose “No sign in”, and under Request headers add Authorization with the value Bearer <your key>. Then enable it in a conversation from the + menu. Claude will ask before running any tool marked destructive.

3. Cursor and VS Code

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

{
  "mcpServers": {
    "circuitsherpa": {
      "url": "https://circuitsherpa.com/mcp",
      "headers": { "Authorization": "Bearer ${env:CIRCUITSHERPA_API_KEY}" }
    }
  }
}

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

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

4. ChatGPT, Codex and the OpenAI API

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

[mcp_servers.circuitsherpa]
url = "https://circuitsherpa.com/mcp"
bearer_token_env_var = "CIRCUITSHERPA_API_KEY"

From the OpenAI Responses API, pass the server as an mcp tool. Leave approval on for anything that writes; the read-only tools are safe to run without it:

{
  "model": "gpt-5",
  "tools": [{
    "type": "mcp",
    "server_label": "circuitsherpa",
    "server_url": "https://circuitsherpa.com/mcp",
    "authorization": "<your Circuit Sherpa API key>",
    "require_approval": { "never": { "tool_names": ["search_parts", "get_part", "whoami", "list_price_alerts", "list_bom_history", "get_bom"] } }
  }],
  "input": "Price this BOM at qty 250 and tell me the three most expensive lines"
}

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

5. The CLI

Node 18 or newer. No install needed; npx fetches the circuitsherpa package. It talks to the same API with the same key and the same limits, and prints tables for people or JSON for scripts:

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

npx circuitsherpa whoami
npx circuitsherpa search "STM32F103C8T6" --limit 5
npx circuitsherpa part NE555PWR --history 30
npx circuitsherpa bom price board.csv --name "Rev C"      # CSV with mpn/qty columns; Pro or Team
npx circuitsherpa bom history
npx circuitsherpa alerts list
npx circuitsherpa alerts create NE555PWR 0.25           # USD per unit
npx circuitsherpa alerts delete <id> --yes               # refuses without --yes

# any command: --json for machine-readable output; CIRCUITSHERPA_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. Free-plan limits are stated in each description so the agent can explain a refusal instead of retrying.

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

curl -s -X POST https://circuitsherpa.com/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://circuitsherpa.com/api/v1/parts?q=NE555PWR&limit=3" \
  -H "Authorization: Bearer $CIRCUITSHERPA_API_KEY"

curl -s -X POST https://circuitsherpa.com/api/v1/bom/price \
  -H "Authorization: Bearer $CIRCUITSHERPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Rev C","lines":[{"mpn":"NE555PWR","qty":250},{"mpn":"LM358DR","qty":500}]}'

Endpoints: GET /api/v1/me, GET /api/v1/parts?q=, GET /api/v1/parts/{mpn}, POST /api/v1/bom/price, GET /api/v1/bom/history, GET /api/v1/bom/{id}, GET|POST /api/v1/alerts, GET|DELETE /api/v1/alerts/{id}. Team accounts also keep the bulk search endpoint GET /api/v1/search.

8. Safety, limits and logging

• An API key acts as you. An agent sees only your data and your team's shared BOMs, under your plan's limits.
• Nothing here can buy parts or move money. Circuit Sherpa links to distributors; it never orders.
• The one destructive tool, delete_price_alert, needs confirm: true; the first call only shows what would be deleted. The CLI needs --yes.
• Rate limit: 300 agent calls per key per hour. Free-plan search quota (10/day) is counted through the API exactly as on the website.
• 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. Revoke one in Settings and it stops working immediately. Deleting your account deletes its keys.
• If every distributor is unreachable, tools fail with an error that says so; they never answer “no results” or price a BOM at $0.

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