Extend Max with platform Tools

Max uses the canonical Tool catalog published by each managed deployment. There is no separate Max tool manifest, callback protocol, or operator-specific registration API. To add an operator-domain capability, add a Tool to the platform package that owns the domain behavior. The deployment graph exposes selected Tools through its authenticated MCP endpoint. Max discovers the same catalog as every other MCP client.

Platform Tools do not install Max. Max remains available only in managed Voyant deployments.

Define a Tool in its owning package

Use @voyant-travel/tools and delegate to the package service layer.

import {
  defineTool,
  READ_ONLY_RISK,
  requireService,
  type ToolContext,
} from "@voyant-travel/tools"
import { z } from "zod"

type BookingLookupContext = ToolContext & {
  bookings?: {
    getBooking(input: { reference: string }): Promise<unknown>
  }
}

export const getBookingTool = defineTool({
  name: "get_booking",
  description: "Get a Booking by reference.",
  inputSchema: z.object({
    reference: z.string(),
  }),
  outputSchema: z.unknown(),
  requiredScopes: ["bookings:read"],
  tier: "read",
  riskPolicy: READ_ONLY_RISK,
  async handler(input, ctx: BookingLookupContext) {
    return requireService(ctx.bookings, "bookings").getBooking(input)
  },
})

The Tool returns typed domain data. It does not return an MCP envelope or a Max card.

Declare the runtime

Export the Tool from the domain package and declare it in that package’s Voyant manifest. The selected deployment graph supplies package-owned context contributions and determines which Tool runtimes are loaded. Do not maintain a second tools.json, Max manifest, or Cloud catalog. Graph registration validates the Tool identity, scopes, and deployment risk against the selected runtime.

Publish through MCP

Managed deployments mount @voyant-travel/mcp at /v1/admin/mcp.

POST /v1/admin/mcp supports standard initialize, tools/list, and tools/call.
The caller authenticates with a scoped voy_* Bearer key.
Unauthorized Tools are neither listed nor callable.
Tool metadata includes stable capability identity, exact version, scopes, risk policy, and action policy.

Max consumes only canonical Tools. Compatibility aliases remain a deployment transport concern.

Actions and approval

Declare risk as data. When a Tool maps to a guarded Action, the selected graph adds the authoritative actionPolicy. Max uses that policy for confirmation and supplies only the invocation controls advertised by the deployment. The deployment validates actor, target, command fingerprint, confirmation, idempotency, and approval before the handler runs. Do not recreate those checks inside a Cloud-specific wrapper.

Presentation

Return typed pure data from the Tool. Max can add a rich presentation for a first-party capability by its stable capability ID. Plain structured results need no Max-specific code.

Next steps

Max overview

See how Max fits into managed deployments.

Managed availability

Learn how Max is delivered in Admin.

Framework modules

Find the package that owns your capability.

​Define a Tool in its owning package

​Declare the runtime

​Publish through MCP

​Actions and approval

​Presentation

​Next steps

Max overview

Managed availability

Framework modules

Define a Tool in its owning package

Declare the runtime

Publish through MCP

Actions and approval

Presentation

Next steps