> ## Documentation Index
> Fetch the complete documentation index at: https://voyant.travel/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Extend Max with platform Tools

> Expose canonical Voyant platform Tools through the deployment MCP endpoint.

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.

<Warning>
  Platform Tools do not install Max. Max remains available only in managed
  Voyant deployments.
</Warning>

## Define a Tool in its owning package

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

```ts theme={null}
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

<CardGroup cols={2}>
  <Card title="Max overview" icon="robot" href="/docs/max/overview">
    See how Max fits into managed deployments.
  </Card>

  <Card title="Managed availability" icon="cloud" href="/docs/max/embed">
    Learn how Max is delivered in Admin.
  </Card>

  <Card title="Framework modules" icon="boxes-stacked" href="/docs/platform/overview">
    Find the package that owns your capability.
  </Card>
</CardGroup>