MCP server

Use Openavail MCP to give an MCP-compatible AI agent access to calendar context, approval-first booking proposals, availability search, holds, and direct calendar writes.

Overview

Openavail supports two MCP setup paths:

Hosted remote MCP with OAuth — primary path for clients that support remote HTTP MCP and browser login. Use https://mcp.openavail.com/mcp.
Local stdio fallback — API-key setup using the scoped npm package @openavail/mcp. Use this when your MCP client does not support hosted OAuth.

The MCP surface includes:

Compatibility tools — Google Calendar MCP-style tools (list-events, create-event, delete-event, etc.) for agents that already understand calendar operations.
Native tools — Openavail-specific tools (get-agent-context, search-availability, create-hold, confirm-hold, create-booking-proposal, etc.) for agents that want explicit scheduling control.

Hosted MCP

Add a remote MCP server named openavail with this URL:

https://mcp.openavail.com/mcp

When your client opens the browser, sign in to Openavail and approve the connection. Openavail creates a client-specific backing agent such as Codex MCP or Claude Code MCP.

The default OAuth grant is approval-first: the agent can read calendar context and create owner-review booking proposals, but it cannot create holds, book directly, preempt, or cancel events unless you later grant those permissions in the Openavail dashboard.

After changing permissions for a hosted MCP backing agent, start a fresh OAuth session so the client receives the new grant. In Codex, that usually means:

codex mcp logout openavail
codex mcp login openavail

If the server was added before OAuth metadata was available, re-add it:

codex mcp remove openavail
codex mcp add openavail --url https://mcp.openavail.com/mcp --oauth-client-id codex
codex mcp login openavail

Permission downgrades and credential revocations still fail closed on the server. The refresh step is for newly granted tools becoming usable in the client.

Local stdio fallback

Use the scoped npm package:

npx @openavail/mcp

There is no unscoped openavail npm package. Install or run @openavail/sdk for the TypeScript SDK and @openavail/mcp for the local MCP server.

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "openavail": {
      "command": "npx",
      "args": ["-y", "@openavail/mcp"],
      "env": {
        "OPENAVAIL_API_KEY": "ak_01HX7QQM…",
        "OPENAVAIL_OWNER_EMAIL": "owner@example.com"
      }
    }
  }
}

Restart Claude Desktop after saving.

Claude Code

claude mcp add --transport stdio openavail \
  --env OPENAVAIL_API_KEY=ak_01HX7QQM… \
  --env OPENAVAIL_OWNER_EMAIL=owner@example.com \
  -- npx -y @openavail/mcp

Codex CLI

Prefer hosted OAuth when available. For local stdio fallback, add to ~/.codex/config.toml:

[mcp_servers.openavail]
command = "npx"
args = ["-y", "@openavail/mcp"]
env = { OPENAVAIL_API_KEY = "ak_01HX7QQM…", OPENAVAIL_OWNER_EMAIL = "owner@example.com" }

Environment variables

Variable	Required	Description
`OPENAVAIL_API_KEY`	Required for private local owner-scoped tools	API key from the Openavail dashboard. Go to Agents → Register agent, create an agent, then click Create API key.
`OPENAVAIL_REQUESTER_CREDENTIAL`	Optional	Requester credential for public scheduling tools. It proves external requester identity; it does not grant owner calendar access.
`OPENAVAIL_OWNER_EMAIL`	No	Default calendar owner email. When set, private tools can omit `owner_email`. Override per call by passing `owner_email`.

Available tools

Start with get-agent-context. It returns the owner's timezone, working hours, calendar setup warnings, unavailable features, and valid meeting class names.

Native tools

Tool	What it does
`get-agent-context`	Get calendars, working hours, meeting classes, capabilities, and setup warnings in one call.
`search-availability`	Find capped candidate slots without creating a hold.
`create-hold`	Reserve a selected candidate or short negotiation window.
`confirm-hold`	Confirm a hold, committing the booking.
`create-booking-proposal`	Create an approval-first owner-review booking proposal without creating a hold or calendar event.
`get-booking-proposal`	Fetch a private owner-scoped booking proposal by `proposal_id`, including owner decision and final `booking_id` when booked.
`simulate`	Preview the arbitration decision without creating anything.
`get-schedule-rules`	Get working hours and slot interval for an owner.
`list-meeting-classes`	List valid meeting class names and priority policy.
`get-pending-notifications`	Fetch unread agent notifications.
`ack-notifications`	Acknowledge notifications by ID.

Compatibility tools

Tool	What it does
`list-calendars`	List connected calendars for an owner.
`list-events`	List committed bookings in a time window.
`get-event`	Fetch a single booking by ID.
`create-event`	Create a booking directly.
`update-event`	Update a booking's title, description, or attendees.
`delete-event`	Cancel a booking.
`search-events`	Search bookings by title keyword.

Public scheduling tools

Tool	What it does
`list-public-meeting-types`	List meeting types visible on another owner's public scheduling boundary.
`create-public-booking-proposal`	Submit a public booking request.
`confirm-public-requester-contact`	Confirm requester contact email for anonymous public proposals.
`get-public-booking-proposal-status`	Poll safe public status by public proposal access token.
`withdraw-public-booking-proposal`	Withdraw a pending public proposal.

Calendar routing

calendar_type is a routing hint, not a hard requirement. Openavail supports work, personal, and other labels per owner. If an agent passes calendar_type: "work" but the owner has no connected work calendar, Openavail falls back to the owner's primary calendar and returns the resolved calendar type in the response.

Call list-calendars or get-agent-context first when calendar type matters. Those tools expose connected calendar types and setup warnings so the agent can avoid surprising fallbacks.

Google Calendar compatibility

The compatibility tools use the same general names as Google Calendar MCP tools. If your agent already targets that style of server, swap the config and keep the prompt mostly unchanged.

Key differences:

create-event requires meeting_class.
Openavail uses owner_email instead of calendarId for owner-scoped routing.
calendar_type is optional and falls back to the primary calendar when the requested type is unavailable.

For native search-availability, use earliest_start and latest_end. latest_end is when the meeting must end, not the latest start time.

Troubleshooting

Hosted tool appears but fails with OAuth authorization required
Refresh the MCP OAuth session after granting new permissions to the backing agent. For Codex, run codex mcp logout openavail then codex mcp login openavail.

OPENAVAIL_API_KEY is required on local stdio startup
The env var is missing or not being passed by your MCP client. Check that env is set in the config block and the key starts with ak_.

CALENDAR_NOT_FOUND
The owner has not connected a calendar, the primary calendar was disconnected, or owner_email does not match an owner visible to the agent.

PERMISSION_DENIED
The backing agent or API key does not have the required permission. Open the agent in the dashboard and check its permission scopes.