MCP Tokens
Create tokens that allow AI assistants and MCP-compatible clients to interact with your workspace data via the Model Context Protocol.
MCP tokens give AI assistants access to your workspace through the Model Context Protocol (MCP). Each token is scoped to specific data types and inherits the creating user's role and segment access, so the assistant sees only what that user can see.
MCP tokens require the MCP feature flag to be enabled on your workspace.
How it works
Create a token, assign it scopes, and configure your MCP-compatible client (such as Claude Desktop or Cursor) with the token and the Itsy MCP server URL. The client can then query your workspace data within the boundaries you set.
Tokens expire after 365 days and can be rotated or revoked at any time. Each token is tied to the user who created it -- it inherits that user's role (Admin or User) and segment access. If the user's workspace membership is revoked, their tokens stop working immediately.
Scopes
Each token includes the Operations scope by default. You can optionally add the Participants scope:
| Scope | What it grants |
|---|---|
| Operations | Access to trips, groups, orders, products, and workspace overview -- the operational side of your workspace. Always included. |
| Participants | Access to participant personal data including names, emails, passport numbers, and contact details. Adds PII to tool responses. |
The Participants scope exists to protect personal data. Granting it means participant details leave Itsy and flow to the AI provider, which may be a data-processing concern under GDPR or similar regulations. Only grant it when the AI assistant genuinely needs traveler details.
Available tools
When an MCP client connects with your token, it can use these read-only tools:
| Tool | What it does |
|---|---|
| get_workspace_overview | Returns an orientation summary: your role, segments, orders needing attention (overdue payments, upcoming departures, unmet deposits, drafts), and the five soonest-departing trips |
| list_trips | Searches trips by name with pagination. Returns trip details, status, dates, and deep links into the admin interface |
| get_trip | Returns full details for a single trip: dates, status, segments, products with capacity and availability |
| list_orders | Searches orders by code, email, status, payment status, or date range with pagination |
| get_order | Returns full details for a single order: totals, deposit state, payment status, bookings, and a deep link. Participant count is included but personal details are excluded unless the token has the Participants scope |
| search | Accent-insensitive substring search across orders, trips, inventory products, and clients. Returns ranked matches with deep links |
All tools are read-only. No tool creates, updates, or deletes data in your workspace.
Connecting an MCP client
1. Create a token
- Go to Settings > MCP Tokens
- Click Create Token
- Enter a name (e.g., "Claude Assistant" or "Booking Agent")
- Select scopes (Operations is always included; optionally add Participants)
- Click Create
Copy the token value immediately -- it is shown only once. The list shows only the token prefix for identification.
2. Configure your MCP client
Add the Itsy MCP server to your client's configuration. Your workspace administrator provides the MCP server URL (it ends in /mcp). The token is passed as a Bearer token in the Authorization header.
Claude Code -- Add the server in your MCP settings or project configuration:
{
"mcpServers": {
"itsy": {
"url": "https://your-mcp-server-url/mcp",
"headers": {
"Authorization": "Bearer itsy_mcp_sk_..."
}
}
}
}Claude Desktop -- Use the mcp-remote bridge in your claude_desktop_config.json, since Claude Desktop does not natively support remote HTTP servers:
{
"mcpServers": {
"itsy": {
"command": "npx",
"args": [
"-y", "mcp-remote",
"https://your-mcp-server-url/mcp",
"--header", "Authorization: Bearer itsy_mcp_sk_..."
]
}
}
}Other MCP clients -- Use the server URL with stateless HTTP transport and pass the token as a Bearer token in the Authorization header.
Rate limits
Each token defaults to 120 requests per minute. If the AI assistant exceeds the limit, requests are temporarily rejected until the window resets.
Managing tokens
Rotating a token
If you suspect a token has been compromised or want to refresh it:
- Click the Rotate action on a token row
- A new token is generated with the same name and scopes
- The old token is revoked immediately
- Copy the new token value -- it is shown only once
Update your MCP client configuration with the new token.
Revoking a token
Click Revoke on a token row to permanently disable it. Revoked tokens cannot be reactivated -- create a new one if needed.
Token list
The token list shows:
| Column | Description |
|---|---|
| Name | The name you assigned |
| Token | The token prefix (for identification only) |
| Scopes | Which scopes are granted |
| Status | Active or Revoked |
| Last Used | When the token was last used for an API call |
| Expires | The expiration date (365 days from creation) |
Admins can see and manage all tokens in the workspace. Non-admin users see only their own tokens.
How it connects
- API Keys -- API keys are for external system integrations via the Workspace API; MCP tokens are for AI assistants via the Model Context Protocol. They serve different purposes and use different authentication methods.
- Team -- Each token inherits the creating user's role and segment access. Revoking a user's workspace membership disables their tokens.
- Workspace API -- The Workspace API is for programmatic integrations (booking engines, partner systems). MCP is for conversational AI access. Both are read-heavy but use different protocols and authentication.