Connect an AI client with MCP

AssetCenter's MCP server lets an external AI client work with your organization through the customer API. MCP stands for Model Context Protocol: a standard way for AI clients to discover tools and call them. You can ask the client to find records, make changes, manage settings or export data, within the permissions of its API token.

Your client must support remote HTTP MCP servers and custom request headers. The connection uses an API token; a normal AssetCenter browser sign-in does not configure the client.

For the assistant opened with the sparkles button inside AssetCenter, see AI Asset Assistant. MCP uses API token permissions and the API's rate limits; it does not use the in-app assistant's monthly chat allowance. Your external AI provider may have its own charges and limits.

Create a token and choose permissions#

1. Sign in to the organization you want the client to use as an account administrator.
2. Open Settings → API Access.
3. Give the token a recognizable name, such as AI inventory client, and choose an expiry.
4. Select Full Access if you want the client to do everything the customer API can do, including creating, updating and permanently deleting records. Select Read Only for the standard inventory and settings reads, or Custom to choose individual permissions.
5. Press Create token and copy the token into your client's secret storage. It is shown only once.

Read Only does not include billing, GPS positions or dashboard reports. Add those permissions with Custom, or choose Full Access. See API access for the complete permission rules.

The token is tied to the organization where it was created. Switching organizations in the browser does not move the connection. Its creator must remain an active account administrator in that organization. Permissions cannot be changed on an existing token: create a replacement when the client needs different access.

Connect your AI client#

Add a remote MCP server in your client's connection settings with these values:

• Name: AssetCenter.
• Server URL: https://my.assetcenter.app/mcp/assetcenter.
• Transport: remote HTTP (Streamable HTTP).
• Request header: Authorization, with the value Bearer YOUR_API_TOKEN.

Replace YOUR_API_TOKEN with the token you just created. Keep it in the connection's secret or header settings. If the client provides a separate bearer-token field, enter the token there according to its instructions. A client that only supports browser-based authorization needs support for bearer tokens or custom headers to use this connection.

Connect or refresh the server's tools. Available tools and operations depend on your token: a token with no write permissions will not expose write_api.

Start with a read, such as “Find our available laptops” or “List the API operations I can use.” The client should report records from the organization attached to the token.

Available tools#

The server provides nine tools when the token has the relevant permissions:

• search_asset_inventory — find assets, count matches or group results.
• search_people — find people and summarize their records.
• search_locations — find locations and summarize their records.
• search_subscriptions — find subscriptions and summarize their records.
• get_asset — read one asset using its numeric record ID.
• get_asset_timeline — read an asset's timeline using its numeric record ID.
• list_api_operations — discover permitted customer API operations, methods, path parameters, related options, writable inventory fields, upload fields and retry requirements.
• read_api — run a permitted GET operation, including lists, record details, options, settings, billing reads, GPS reads and reports.
• write_api — run a permitted POST, PUT, PATCH or DELETE operation, including inventory changes, assignments, lifecycle actions, timeline edits and comments, to-dos, images, categories, event definitions, organization settings and user management.

Together, the API tools cover every operation in the customer API. Full Access still follows API validation, plan and storage limits, confirmation requirements and rules such as allowing only a comment's author to edit or delete that comment.

Search tools return up to 25 records by default. Their total is the count of matches, even when the displayed list is shorter; request a count or grouping when you need a summary.

Discover and run an operation#

Ask the client to use list_api_operations before making a change. It can filter by search, inspect an exact operation, filter by method, and paginate with page and per_page. The default page size is 25 and the maximum is 100; continue through last_page for the full catalog.

Use the operation name and method exactly as returned. Put record IDs in path_parameters, filters and pagination in query, and mutation fields in body. Read the related options_operation, when present and permitted, for valid choices and field definitions. The API guide describes each endpoint's payload and response.

For example, read_api can list five people with these arguments:

{
  "operation": "people.index",
  "query": {"per_page": 5}
}

With permission to create people, write_api can create a person with these arguments:

{
  "operation": "people.store",
  "method": "POST",
  "body": {"first_name": "Alex", "last_name": "Morgan"}
}

Each successful call to this creation operation creates a new person. It has no idempotency replay protection, so check whether the record was created before repeating a call whose result is uncertain.

The API tools return status, headers and body. A status of 400 or higher means the action failed, even if the MCP connection itself succeeded. A successful delete may return status 204 with an empty body. The client should use the response to confirm the result.

Retry a change#

Many workflow, settings and file operations require an idempotency_key. The catalog identifies them with idempotency_key_required. Create a new key for each intended action; reuse the same key and payload only when retrying that action. Keys must be 8–128 characters using letters, numbers, periods, underscores, colons or hyphens.

Core inventory create, update and delete operations do not provide replay protection, even if you supply a key. Follow the idempotency guide before retrying. Timeline edits also retain the API's version checks and confirmation fields.

Upload and download files#

For operations whose catalog entry lists file_fields, the client sends uploads in the files array. Each item has a field, a filename and content_base64 containing the file's base64-encoded bytes. Use image for an image field, or attachments.0 through attachments.9 for attachments, as allowed by that operation.

The MCP tool accepts up to ten files. API file types, storage quotas and size limits still apply: images up to 20 MiB, attachments up to 10 MiB each. Supply the operation's normal fields in body and its retry key when required. The client needs file-reading and encoding support to prepare an upload.

API Excel exports return filename, mime_type and content_base64 in the result body. The client must decode the bytes and save the file, or offer it as a download. Whether an attachment appears in the chat depends on your client's file support.

Connection errors and limits#

• 401: check that the client sent the API token in its Authorization header and that the token has not expired or been revoked.
• 403: check the token's permissions and that its creator is still an active administrator in the token's organization. Missing tools or operations can also mean the token lacks the required permissions.
• 409: inspect the response for an idempotency conflict or stale record version. Reusing a retry key with different data does not start a new action.
• 422: correct the fields named in the validation errors. Payloads and confirmations follow the same rules as the API.
• 429: wait for the Retry-After interval before trying again.

MCP shares the customer API's limits of 60 requests per minute per token and 300 per minute per organization. Some operations, including exports, have additional limits. See errors and limits for details.

To disconnect a client, remove its connection and revoke its token in Settings → API Access. An expired or revoked token cannot be used again.