agent-cal
Documentation

Built for your agent, not for you.

Everything an AI agent needs to register an account, take payment, configure availability, and start booking on behalf of a human — minimal-human-in-the-loop. Humans get the dashboard; agents get this page.

Quick start

Connect via MCP

Hosted HTTP for browser-based clients (Claude.ai web, etc.) — OAuth handled automatically. Or stdio for Claude Desktop / Cursor / Continue.

recommendedHosted MCP URL
https://agent-calweb-production.up.railway.app/api/mcp

Paste into any MCP client that supports remote servers. The client auto-discovers our OAuth server (RFC 8414) and walks the user through sign-in — no token to paste, no secrets to manage.

Claude Desktop config (remote)
{
  "mcpServers": {
    "agent-cal": {
      "url": "https://agent-calweb-production.up.railway.app/api/mcp"
    }
  }
}
or run as stdio subprocess
One-line install (stdio)
npx -y @agent-cal/mcp
Claude Desktop config (stdio)(~/Library/Application Support/Claude/claude_desktop_config.json)
{
  "mcpServers": {
    "agent-cal": {
      "command": "npx",
      "args": [
        "-y",
        "@agent-cal/mcp"
      ],
      "env": {
        "AGENT_CAL_API_BASE_URL": "https://agent-calweb-production.up.railway.app"
      }
    }
  }
}
REST API base URL
https://agent-calweb-production.up.railway.app/api/v1
Three ways to authenticate.
  1. OAuth (hosted HTTP only) — client auto-discovers via /.well-known/oauth-authorization-server, drives the user through /oauth/authorize, exchanges code at /oauth/token. PKCE-only public clients, dynamic registration at /oauth/register.
  2. Agent-driven OTP (both transports) — call register then verify_email tools.
  3. Direct bearer — paste a 3-day token from the dashboard into the Authorization: Bearer header.

Discovery

Agent-discovery URLs

Machine-readable manifests an agent can fetch to learn the surface area without reading prose.

  • Service manifestName, description, API base URL, MCP transports, auth options.
    https://agent-calweb-production.up.railway.app/.well-known/agent.json
  • Tool manifestEvery MCP tool with name, description, and input schema.
    https://agent-calweb-production.up.railway.app/.well-known/tools.json
  • OAuth authorization serverRFC 8414 — endpoints, supported grant types, PKCE methods.
    https://agent-calweb-production.up.railway.app/.well-known/oauth-authorization-server
  • OAuth protected resourceTells MCP clients which authorization server protects /api/mcp.
    https://agent-calweb-production.up.railway.app/.well-known/oauth-protected-resource

Authentication

The agent-driven loop

No human terminal step required. The agent (or its MCP client) drives the OTP flow end-to-end.

  1. 1
    register

    Tool call: register({ email, agent: { name, id, version } }). Sends a 6-digit OTP to the email. Pass name / id / version identifying yourself ("claude-code", a stable UUID, "1.2.3") so the host can attribute and rate-limit. Response: pending_verification.

  2. 2
    (retrieve OTP)

    Two paths: ask the human for the 6-digit code, OR if your MCP client has email connector access, fetch the latest message to that address and parse the code from the subject (we lead with it: 123456 is your agent-cal sign-in code).

  3. 3
    verify_email

    Tool call: verify_email({ email, code }). Stores a 3-day bearer at ~/.config/agent-cal/credentials.json and reports verified. Auto-refreshes when < 12h remain.

  4. 4
    update_profile (one-time)

    Set username + timezone before create_schedule. Username defaults to the email's local part on first verify, but you can override: update_profile({ username, timezone, name }).

Direct REST

If you'd rather skip MCP

Same data, raw HTTP. Bearer goes in the Authorization header (Bearer <token>).

  • POST/api/v1/auth/registerpublic
    https://agent-calweb-production.up.railway.app/api/v1/auth/register
  • POST/api/v1/auth/verifypublic
    https://agent-calweb-production.up.railway.app/api/v1/auth/verify
  • GET/api/v1/auth/mebearer
    https://agent-calweb-production.up.railway.app/api/v1/auth/me
  • POST/api/v1/schedulesbearer
    https://agent-calweb-production.up.railway.app/api/v1/schedules
  • GET/api/v1/schedulesbearer
    https://agent-calweb-production.up.railway.app/api/v1/schedules
  • POST/api/v1/schedules/{id}/invitesbearer
    https://agent-calweb-production.up.railway.app/api/v1/schedules/{id}/invites
  • GET/api/v1/public/{username}/{slug}/availabilitypublic
    https://agent-calweb-production.up.railway.app/api/v1/public/{username}/{slug}/availability
  • POST/api/v1/public/{username}/{slug}/bookpublic
    https://agent-calweb-production.up.railway.app/api/v1/public/{username}/{slug}/book
  • POST/api/v1/billing/checkoutbearer
    https://agent-calweb-production.up.railway.app/api/v1/billing/checkout

Tools

MCP tool surface

Hand-curated mirror of the runtime tools. Full input schemas live at /.well-known/tools.json.

Auth

  • register

    Start registration — sends a 6-digit OTP.

  • verify_email

    Submit the OTP, mint a bearer.

  • whoami

    Read back the current user + agent identity.

  • update_profile

    Set username / timezone / display name.

Calendars + meeting tools

  • connect_google_calendar

    Returns OAuth URL for human to grant access.

  • connect_microsoft_calendar

    Same for Outlook.

  • connect_zoom

    Same for Zoom.

  • list_calendars

    List connected calendars + sync status.

  • list_meeting_tools

    List connected meeting tools (Zoom).

  • disconnect_calendar

    Revoke a calendar connection.

  • disconnect_meeting_tool

    Revoke a meeting tool connection.

Schedules

  • create_schedule

    Create a booking link. Returns booking_url.

  • list_schedules

    Caller's schedules.

  • get_schedule

    Fetch by id.

  • update_schedule

    Partial update.

  • pause_schedule

    Stop accepting new bookings.

  • activate_schedule

    Resume.

  • delete_schedule

    Soft delete.

Invites

  • mint_invite

    Issue a private invite token (plaintext + URL once).

  • list_invites

    Prefixes only — no plaintext.

  • revoke_invite

    Revoke an invite by id.

  • get_invite_events

    Audit log per invite.

Bookings (host)

  • list_bookings

    Host's view.

  • get_booking

    Fetch by id.

Booker side

  • get_invite_availability

    Slots for an invite token (no bearer).

  • book_via_invite

    Confirm a slot. Returns cancel_url + meeting_url.

Calendars + meetings

Connect Google, Outlook, Zoom

Bookings push real events. Bookers get a meeting URL in the confirmation email.

Google Calendar

Free/busy + Google Meet links. One OAuth grant covers both.

Microsoft Outlook

Free/busy + Teams meeting links (work/school accounts).

Zoom

Independent OAuth; per-booking Zoom meetings created via the Zoom API.

Connect from the dashboard, or programmatically: each provider has a connect_* MCP tool that returns a one-time OAuth URL the human visits. Once connected, schedules with location_type set to google_meet, microsoft_teams, or zoom generate fresh meeting URLs per booking.

Build agents, not glue.

Issues, ideas, weird agent behaviour: venkat@amzuit.com.