MCP integration
Connect compatible AI applications to six focused KATSANA read tools.
Hosted endpoint and availability
The production endpoint is https://mcp.katsana.com/mcp. It uses stateless Streamable HTTP and does not store user access or refresh tokens.
Hosted sign-in is awaiting KATSANA authentication support. The initial deployment reserves this endpoint and returns 503 Service Unavailable for MCP requests. It cannot list tools or access fleet data yet. A successful /health response reports process liveness and an authentication status of not_ready; it does not mean that sign-in or data access is available.
Once sign-in is enabled, use an MCP client that supports remote Streamable HTTP and the required authorization flow. The client will direct you to KATSANA to sign in and authorize access. Your KATSANA account permissions determine which vehicles and trips you can read.
The API reference’s POST /auth flow and API token field are for direct API requests. They do not sign you into hosted MCP. Never paste a password or API token into an AI chat or a tool argument.
Configure a remote client
After hosted sign-in becomes available, add the endpoint using your client’s remote MCP connection settings. This is an illustrative connection object; field names and configuration locations depend on the client:
{
"type": "http",
"url": "https://mcp.katsana.com/mcp"
}Complete KATSANA sign-in in the client’s authorization flow before requesting data. There is no shared service account, and the endpoint does not accept an arbitrary API token as a substitute for hosted sign-in.
Available tools
These six read tools are implemented for both the hosted service and local stdio. They become accessible on the hosted endpoint after authentication is enabled.
| Tool | Purpose | Input limits |
|---|---|---|
list_vehicles |
List vehicles accessible to your account | Paginated; default 25, maximum 100 records per page |
get_vehicle |
Read one vehicle | Positive integer vehicle ID |
get_vehicle_location |
Read a vehicle’s latest location | Positive integer vehicle ID |
get_travels |
List trips in a time range | At most 48 hours; explicit-offset timestamps and an IANA timezone |
get_travel |
Read one trip | Positive integer vehicle and trip IDs |
get_daily_summaries |
Read daily summaries | At most 31 inclusive calendar dates and an IANA timezone |
For example, after login you can ask the AI application to list vehicles you can access, retrieve a selected vehicle’s latest location, or summarize trips for a specific date and timezone. Results contain the data returned by KATSANA for your account. Check vehicle IDs, dates and timezone before using a result in an operational decision.
Permissions and practical limits
The tools perform only the listed reads. They cannot change vehicles, send commands, run arbitrary API operations or fetch a URL supplied in a prompt. KATSANA authorization still applies to each data request; connecting an AI application does not expand your account’s access.
A tool result is limited to 64 KiB. Use smaller date ranges or page sizes if a result is too large. Upstream requests have a ten-second timeout and limited retries for temporary errors. Rate limits can return 429; follow the retry guidance in the response. An empty result, an authorization error and temporary unavailability have different meanings: do not treat them as evidence that a vehicle or trip does not exist.
Share fleet locations and trip data only with AI applications approved for your organization. Review the application’s data handling before connecting your account.
Local stdio alternative
Developers with a repository checkout can use the local stdio server now with an existing, approved KATSANA API token. Build it from the repository root with Node 24 and pnpm 10.34.7:
pnpm install --frozen-lockfile
pnpm --filter @katsana/mcp-server buildConfigure your MCP client to launch node with the absolute path to packages/katsana-mcp/dist/stdio.js. Supply KATSANA_TOKEN through the client’s secure environment or secret facility. Keep tokens out of chat, command arguments, shell history and committed configuration. Local stdio uses that API token directly and does not depend on the hosted sign-in rollout.
For direct HTTP integrations, continue with the API reference or getting started guide.