Set up your agent

Wire up Codex, Claude Code, any MCP-compatible client, or a custom REST agent in under five minutes.

Prerequisites

Before connecting a production agent, run Agent Test Flight or register an agent manually in the dashboard.

Hosted MCP uses browser OAuth and does not require you to paste an API key into the client. Local stdio MCP and REST integrations use a production agent API key from Dashboard → Agents → open your production agent → Create key.

Your API key looks like ak_01HX7QQM… and is only shown once. Copy it somewhere safe before leaving the page.

Prove the approval flow

Before giving a real agent reusable access, run Agent Test Flight from the dashboard setup guide.

Previewing or running Agent Test Flight creates or reuses a Test Agent, asks for a safe time, lets you approve the proposal, and writes a clearly labeled test booking only after you confirm the calendar side effect. Skipping Agent Test Flight does not create a Test Agent or credential. The audit receipt is marked Test flight, so you can inspect the actor, decision, and Google Calendar write before wiring a production agent.

After the test flight, register a separate production agent with the permissions your integration needs. Test Flight agents use internal credentials only and cannot mint normal API keys.

Hosted MCP with OAuth

Use hosted MCP when your client supports remote HTTP MCP and browser-based OAuth login.

https://mcp.openavail.com/mcp

Create a remote MCP server named openavail, use the URL above, then complete the browser login. Openavail creates a client-specific backing agent such as Codex MCP or Claude Code MCP.

The default grant is approval-first: the agent can read scheduling context and create owner-review proposals. It cannot create holds, book directly, cancel events, or preempt unless you grant those permissions in the dashboard.

After changing permissions for the hosted MCP backing agent, refresh the OAuth session so the client receives the new grant. In Codex:

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

Revocations and permission downgrades fail closed on the server. The refresh step is only needed for newly granted tools to become usable in the client session.

Verify the connection inside your MCP client. openavail should expose tools like get-agent-context, create-booking-proposal, and get-booking-proposal.

Local stdio fallback

Use local stdio when your MCP client does not support hosted OAuth. The local server is the scoped npm package @openavail/mcp; there is no unscoped openavail npm package.

Claude Code

claude mcp add --transport stdio openavail \
  --env OPENAVAIL_API_KEY=YOUR_API_KEY \
  -- npx -y @openavail/mcp

By default this scopes the server to the current project. Pass --scope user to make it available across all your projects.

Claude Desktop

Add the following block to your Claude Desktop config file and replace YOUR_API_KEY:

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": "YOUR_API_KEY"
      }
    }
  }
}

Restart Claude Desktop after saving.

Other MCP clients

Any MCP-compatible client that supports stdio servers uses the same command + args pattern:

{
  "mcpServers": {
    "openavail": {
      "command": "npx",
      "args": ["-y", "@openavail/mcp"],
      "env": {
        "OPENAVAIL_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Config file locations by client:

Client	Config file
Cursor	.cursor/mcp.json in your project root, or ~/.cursor/mcp.json globally
Windsurf	.codeium/windsurf/mcp_config.json
Cline / Roo Code	VS Code settings panel → MCP Servers → paste the block

After saving, restart the client or trigger a config reload. The full list of available tools and parameters is in MCP server.

Supplying the owner email

Every private owner-scoped local stdio tool call requires an owner_email unless the API key is already user-scoped. Hosted OAuth connections usually resolve the owner from the signed-in dashboard user.

For local stdio, there are three ways to handle owner email:

Set a default via env var (recommended for single-owner setups)

Pass OPENAVAIL_OWNER_EMAIL when registering the server and it becomes the default for every tool call. A value supplied by the agent at call time always overrides it.

claude mcp add --transport stdio openavail \
  --env OPENAVAIL_API_KEY=YOUR_API_KEY \
  --env OPENAVAIL_OWNER_EMAIL=you@company.com \
  -- npx -y @openavail/mcp

Write it into the agent's system prompt

Include the owner email in your agent's instructions before the conversation starts:

You are a scheduling assistant. Always use owner_email: you@company.com when calling Openavail tools.

Supply it conversationally

The user tells the agent naturally: "Book a meeting on alex@acme.com's calendar." The agent passes that email in the tool call. Use this when the agent manages calendars for multiple owners.

If the calendar owner has more than one calendar connected, the agent can pass calendar_type: "work", "personal", or "other". This is a hint: if the requested type is unavailable, 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 the specific calendar type matters.

REST API

If your agent calls APIs directly rather than using MCP, pass your key as a bearer token on every request:

Authorization: Bearer YOUR_API_KEY

The Quickstart walks through the two-call flow — availability check then confirm — end-to-end. Every endpoint accepts the same token format.