authenticate
Guide for authenticating with the PI API
LABSCO SUMMARY
The filter vocabulary is discovered from a sample entity instead of looked up in documentation you have to find first.
get-filterable-attributes inspects an entity type and reports what can actually be filtered on, which makes the list calls usable without a schema in front of you. Session state is explicit rather than ambient: the base URL, the token and the organization each have their own call, so moving between environments is three calls instead of a restart. Credential login is marked as the last resort, with token refresh as the intended path.
What it is
A client for the PI API: session and organization setup, then category and chart operations.
What you get
- A base URL set at runtime and a connection check that reports whether the URL and authentication are both valid.
- Session handling: a token verified and refreshed, credential login as the fallback path, logout, and an organization ID applied to later requests.
- Categories listed with filtering and paging, fetched, created, updated and deleted, and their objects listed.
- Charts listed with filtering, fetched, deleted, and exported in a format you choose.
- The attributes available for filtering, discovered by examining a sample entity.
Requirements
A PI API instance to point at and an account on it. Authentication is by token, with a username and password login available as the fallback.
Setup effort
One command plus a key — npm install -g @mingzilla/pi-api-mcp-server, then supply credentials
USE CASES
01
Moving the tools onto a different environment
Base URL, then a connection check, then a token refresh — each is its own call, so a switch does not require restarting anything.
02
Narrowing a long category list to the ones you need
The filterable attributes are read off a sample entity first, which is what makes the filter expression writable without documentation.
03
Adding a category with the cascade behaviour you want
Cascade filters and object positioning are set at creation and adjustable afterwards, and the objects inside are listable separately.
04
Getting a chart out of the platform
Finding the chart and exporting it are separate steps, and the export format is chosen at call time.
18 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
authenticate-with-credentials
Authenticate with the PI API using username and password (last resort option)
check-connection
Check if the current API URL and authentication are valid
create-category
Create a new category
delete-category
Delete a category
delete-chart
Delete a chart
export-chart
Export a chart in various formats
get-category
Get a category by ID
get-chart
Get a chart by ID
get-filterable-attributes
Get the list of attributes that can be used for filtering by examining a sample entity
keep-session-alive
Verify and refresh the current authentication token (also used for token-based authentication)
list-categories
List all categories with filtering support
list-category-objects
List all objects for a specific category
list-charts
List all charts with filtering support
logout
Invalidate the current token and end the session
set-api-url
Set the API base URL for all requests
set-organization
Set the organization ID for subsequent requests
update-category
Update an existing category
BEFORE YOU INSTALL
What to know first
Tools you get
18 tools when we connected.
Requires
- npm on PATH
- PI_API_KEY in your environment
Where it runs
Both documented setups run the server on your machine.
CONTEXT COST
Light Standing cost
Rated by the size of the 18 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
TERMINAL
npm install -g @mingzilla/pi-api-mcp-serverMCP Clients
Claude Desktop — Docker
CLAUDE DESKTOP — DOCKER · JSON
{
"mcpServers": {
"pi-api": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"API_URL=http://localhost:8224/pi/api/v2",
"-e",
"PI_API_KEY=<YOUR_PI_API_KEY>",
"mingzilla/pi-api-mcp-server"
],
"disabled": false,
"autoApprove": [
"keep-session-alive",
"check-connection",
"authenticate",
"list-categories",
"get-category",
"list-charts",
"get-chart",
"export-chart",
"get-filterable-attributes",
"export-chart"
]
}
}
}Claude Desktop — npx
CLAUDE DESKTOP — NPX · JSON
{
"mcpServers": {
"pi-api": {
"command": "npx",
"args": [
"-y",
"@mingzilla/pi-api-mcp-server",
"--api-url",
"http://localhost:8224/pi/api/v2",
"--auth-token",
"<YOUR_PI_API_KEY>"
]
}
}
}
