API Access

MCP API tools forward requests to the public API. The client cannot override that upstream. See the public endpoints.

Connecting to MCP uses OAuth by default. API-token URLs with api_key remain available for clients that cannot complete OAuth. Team scope is required only when an API tool call needs to operate inside a team.

Reads

Use vrt_api_read for GET requests.

Team discovery reads omit team scope. Partner API-key reads also omit it. OAuth reads of /partner routes require the partner team through teamId or the MCP connection’s team_id. Discovery reads include:

• GET /me/teams
• GET /teams
• GET /teams/issues

vrt_team_lookup searches all data regions without a region input. It calls GET /me/teams for OAuth users and GET /partner/teams for Partner API tokens. After lookup, use the returned team id as teamId; the generic API gateway routes subsequent team-scoped reads by x-team-id. Read one team with GET /team and that team’s id as teamId, whatever region it is in.

Every other read requires either:

• URL-level team_id as the default team
• tool-level teamId

The worker forwards that value as x-team-id.

Regional portfolio reads such as GET /operations/{id} are placed by the x-data-region header. Set the optional dataRegion input (ap, crunchy, eu, hostaway, or us) of vrt_api_read or vrt_api_mutation to send it. A request that needs a region and has none returns 400 with reason dataRegionRequired; set dataRegion. POST /partner/vri-to-vrt creates the new team in us when dataRegion is omitted. The directory connector rejects dataRegion.

Partner Routes

Routes at /partner and /partner/* preserve the partner identity of a Partner API token. The MCP worker does not forward x-team-id for these calls, even when the connection URL has a default team_id or the tool call supplies teamId.

OAuth calls must supply the partner team through teamId or the connection’s team_id. The worker forwards it as x-team-id, and the calling user’s access to that partner applies.

Pass source, target, or filter team ids through the route’s documented query or body fields. For example, VRI statement migration uses sourceTeamId and targetTeamId on the /partner/vri-to-vrt/statements/* routes.

Operation Status

When a mutation returns operationId, poll it with vrt_api_read:

{
  "path": "/operations/<operationId>"
}

With API-key authentication, MCP preserves the credential tenant and ignores the connection’s default team_id for this operation-status read. With OAuth, send the team that initiated the operation through teamId or the connection’s team_id. For a Partner import into a team in another region, that team is the partner. The status reaches the partner’s own region within about 5 minutes; dataRegion set to the target’s region reads it at once. See Asynchronous operations for the status, authorization, and timestamp contract.

Mutations

Use vrt_api_mutation for POST, PATCH, PUT, or DELETE.

Mutations can change data. They require all of the following:

• method set to POST, PATCH, PUT, or DELETE
• a team scope from default URL-level team_id or tool-level teamId, unless the request uses a Partner API key on a /partner path
• confirm: true

A tool-level teamId can switch teams per call, even when the MCP URL has no team_id.

For read-only assistant workflows, disable vrt_api_mutation in the client when the client supports tool deny lists.

API Shape Discovery

Before calling an endpoint, ask the client to read:

• vrplatform://api/openapi-context
• vrplatform://api/path/<encoded-path>
• vrplatform://api/path/<encoded-path>/<method>

For example:

vrplatform://api/path/%2Freservations
vrplatform://api/path/%2Freservations/GET