`get_access`

Updated October 15, 20262 min read

List the tenants the current user may act on over MCP, with the permissions and scopes granted on each. Only grants enabled for MCP count; ownership of an account grants nothing here. Use it to learn which tenantId to pass to the other tools and what they will be allowed to do.

This is the canonical first call in any MCP session. The server-published agent guidance requires it: agents must validate any user-requested tenant against this list before invoking shipment or report tools.

Parameters

None. The tool reads the signed-in user's access; pass no arguments.

Returns

items — one entry per tenant the user can act on over MCP:

tenant — id (the tenantId you pass to every other MCP tool), name, and status.
subscription — the tenant's plan and subscription status.
isAccountOwner — whether the user owns the tenant's account.
grants — what the user may do on the tenant. Each grant has:
- allow — permissions as entity:action, for example shipment:list.
- scope — the merchants, countries, and locations the permissions apply to. ["_ANY"] means every merchant, country, or location.

Example agent prompt

"Which Carriyo environments can I access?"

get_access()

The agent narrates the result: "You have access to two tenants — Acme Production and Acme Staging. On Acme Staging you can view shipments for the merchant Acme Retail only. Which one would you like to work with?"

Common chain

The standard agent first turn:

get_access
       │
       ▼
get_merchants(tenantId="…")
       │
       ▼
…the user's actual question, scoped…

get_merchants — merchants the user can use within a chosen tenant.
All other MCP tools require tenantId. Resolve it here.

Notes

The result is small and cheap to fetch. Don't try to skip this for performance reasons — agent clients typically cache the result for the session.
Tool calls reach only what the grants allow: an action without its permission is refused, and results stay within the grants' merchants, countries, and locations. Check grants before offering an action.
If the result is empty, the user has no MCP access — the agent should stop and surface that, not try to call shipment tools.

get_access