Connect AI tools with MCP

BatteryPass runs a Model Context Protocol (MCP) server at https://<your BatteryPass host>/mcp. An AI tool that speaks MCP connects to it with an API key of your organisation and gets one tool for each operation of the integration API: it can look up battery models, units, values and their completeness, read passports and their versions, follow the change feed, export BatteryPass JSON, PDFs and QR codes, and, with the right scope, report condition data and lifecycle events or map and validate spreadsheet imports.

Use it when you want an assistant to answer questions about your data ("Which units of model X still have open fields?") or to prepare and send condition reports on your behalf. For scheduled, unattended integrations call the REST API directly; the tools are the same operations.

Before you startCopy Anchor Link

export BATTERYPASS_API_KEY="bp_live_…"

Set up your toolCopy Anchor Link

{
  "mcpServers": {
    "batterypass": {
      "type": "http",
      "url": "https://passport.example.com/mcp",
      "headers": { "Authorization": "Bearer ${BATTERYPASS_API_KEY}" }
    }
  }
}

claude mcp add --transport http --scope user batterypass https://passport.example.com/mcp \
  --header "Authorization: Bearer bp_live_…"

The toolsCopy Anchor Link

Every operation of the published integration API is one tool, except the file upload createImport. Its name is the operation's operationId in snake_case, so listBatteryModels in the API reference is the tool list_battery_models. The tool's arguments are the operation's path and query parameters under their names and the JSON request body under body; the descriptions come from the API reference and name the scope a tool needs.

A tool only sees the data of the organisation that owns the key, exactly like a REST request with that key. Your tool lists only the tools of the key's scopes; public passport reads are available to every key.

A tool cannot carry a file, so a spreadsheet is uploaded over REST with createImport and the same key; the assistant then maps and validates the import with the tools (Units from production). Committing the import and approving its values stay with members in the portal.

How results come back:

• JSON responses are returned as text and as structured content.
• Lists return one page. The tool descriptions ask the assistant to pass a small limit and to call again with cursor set to next_cursor until it is null.
• Files (PDF, QR codes as PNG or SVG, spreadsheets, documents) are returned as embedded resources up to 1 MiB. Larger files fail with result_too_large; download them over REST with the key instead.
• An error of the API is a tool error with the Problem's code, title, detail, the field errors and the request_id, for example not_found or validation_error. Arguments that do not match the tool's schema fail with invalid_arguments before anything is sent.

SecurityCopy Anchor Link

• One key per tool and person. You can then see in the audit log who acted, and revoke one tool without touching the others.
• Least scopes. Give condition only to tools that must report measurements and import only to tools that prepare imports; a read key cannot change anything.
• Revoke a key on the API keys page as soon as a tool or laptop is no longer used. Revoking works at once.
• Results are data, not instructions. Values, notes and documents in BatteryPass come from your team, your suppliers and service partners. The server tells the assistant to treat them as data; still review what an assistant proposes to write.
• Never put a key into a repository, a URL or a chat message. The configuration files above read it from the environment; only the claude mcp add command and the mcp-remote configuration hold it in plain text.

TroubleshootingCopy Anchor Link