For the complete documentation index, see llms.txt.

AI Agent Integration (MCP)

Connect Claude, GPT-4, or any MCP-compatible agent to Vennio's scheduling primitives. Your AI can find mutual availability, create bookings, and negotiate meeting times — all with a single API key.

What is MCP?

The Model Context Protocol (MCP) is an open standard for connecting AI models to external tools and data sources. It lets you expose structured functions — like "find a free time slot" or "create a booking" — as tools that any MCP-compatible AI agent can call autonomously.

Vennio exposes 12 scheduling tools over MCP. This means an AI agent can handle the full scheduling workflow — check availability, propose times, handle counters, confirm the booking — without you writing a custom integration layer.

Prerequisites

1. A Vennio API key — Go to Settings → API Keys on vennio.app and create a secret key (vennio_sk_live_*).
2. Connected calendar — The authenticated user must have a Google Calendar or Microsoft 365 account connected. The MCP tools operate on their behalf.
3. Consent grants (for multi-party scheduling) — Tools like find_mutual_availability require each person to have granted calendar access consent. Use the Consents API or the Vennio app to set these up before running multi-party queries.

Connect to Vennio

The Vennio MCP server runs at https://api.vennio.app/mcp over Streamable HTTP (stateless JSON-RPC). Each request is authenticated with your API key.

Claude Desktop

Add Vennio to your claude_desktop_config.json file (found at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "vennio": {
      "type": "http",
      "url": "https://api.vennio.app/mcp",
      "headers": {
        "Authorization": "Bearer vennio_sk_live_YOUR_KEY"
      }
    }
  }
}

Restart Claude Desktop. You'll see "vennio" listed in the MCP tools panel.

Programmatic (Node.js)

For agents and automation, connect directly using the MCP SDK:

npm install @modelcontextprotocol/sdk

import { Client } from '@modelcontextprotocol/sdk/client/index.js'
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'

const client = new Client({ name: 'my-agent', version: '1.0.0' })

const transport = new StreamableHTTPClientTransport(
  new URL('https://api.vennio.app/mcp'),
  {
    requestInit: {
      headers: { Authorization: `Bearer ${process.env.VENNIO_API_KEY}` },
    },
  }
)

await client.connect(transport)

// List available tools
const { tools } = await client.listTools()
console.log(tools.map(t => t.name))
// → ['find_availability', 'find_mutual_availability', 'create_booking', ...]

Tool walkthrough

Three tools cover the core scheduling loop. All others are listed in the full table below.

find_mutual_availability

Find time slots where all specified people are free. This is Vennio's signature feature — consent-scoped mutual scheduling across multiple calendars.

const result = await client.callTool({
  name: 'find_mutual_availability',
  arguments: {
    principal_ids: [
      'USER_UUID_1',
      'USER_UUID_2',
    ],
    duration_minutes: 60,
    from: '2026-04-01T00:00:00Z',
    to: '2026-04-07T23:59:59Z',
    timezone: 'America/New_York',
    limit: 5,
  },
})

{
  "mutual_slots": [
    {
      "start": "2026-04-02T14:00:00-05:00",
      "end": "2026-04-02T15:00:00-05:00",
      "duration_minutes": 60,
      "principals_free": ["USER_UUID_1", "USER_UUID_2"]
    },
    {
      "start": "2026-04-03T10:00:00-05:00",
      "end": "2026-04-03T11:00:00-05:00",
      "duration_minutes": 60,
      "principals_free": ["USER_UUID_1", "USER_UUID_2"]
    }
  ],
  "total": 2
}

create_booking

Create a confirmed booking directly — no proposal round trip required. Use this when you already know the time (e.g., the user just picked a slot from a widget). The booking metadata records the AI agent's identity for the audit trail.

const result = await client.callTool({
  name: 'create_booking',
  arguments: {
    business_id: 'BUSINESS_UUID',
    customer_email: 'customer@example.com',
    customer_name: 'Jane Doe',
    start_time: '2026-04-02T14:00:00Z',
    end_time: '2026-04-02T15:00:00Z',
    notes: 'Initial consultation',
    agent_name: 'My Scheduling Agent',
  },
})

{
  "booking_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "confirmed",
  "business_id": "BUSINESS_UUID",
  "customer_name": "Jane Doe",
  "customer_email": "customer@example.com",
  "start_time": "2026-04-02T14:00:00Z",
  "end_time": "2026-04-02T15:00:00Z",
  "created_at": "2026-03-28T22:00:00Z"
}

propose_meeting

Create a multi-party meeting proposal with one or more time slots. Participants can accept, counter with alternative times, or reject. This enables the full negotiate-until-confirmed loop that agents like the calendar agent example implement.

const result = await client.callTool({
  name: 'propose_meeting',
  arguments: {
    participant_ids: ['USER_UUID_1', 'USER_UUID_2'],
    slots: [
      {
        start: '2026-04-02T14:00:00Z',
        end: '2026-04-02T15:00:00Z',
        preference: 0,
      },
      {
        start: '2026-04-03T10:00:00Z',
        end: '2026-04-03T11:00:00Z',
        preference: 1,
      },
    ],
    message: 'Happy to meet at either of these times.',
    expires_in_hours: 48,
  },
})

When a participant responds, poll get_proposal or listen for a proposal.responded webhook. If they counter, call propose_meeting again with the revised slots. If they accept, call create_booking with the accepted slot.

All 12 tools

Tool	Description
find_availability	Bookable slots for a business, accounting for calendar events and existing bookings
find_mutual_availability	Slots where 2–5 people are all free (requires consent from each)
create_booking	Confirm a booking directly — creates calendar event, sends emails, fires webhooks
get_booking	Retrieve a booking by ID
cancel_booking	Cancel a confirmed booking, fires cancellation webhooks
propose_meeting	Create a multi-party meeting proposal with proposed time slots
respond_to_proposal	Accept, counter, or reject a proposal on behalf of a participant
get_proposal	Retrieve a proposal and optionally the full negotiation thread
check_consent	Verify you have consent to access a principal's calendar data
get_network	Snapshot of your connection network — counts, types, recent contacts
list_connections	List network connections with filtering by type, status, or search
find_mutual_connections	Find people connected to all specified principals (must include yourself)

Full agent example

The examples/calendar-agent/ directory contains a complete working agent that runs the full scheduling loop autonomously:

1. DISCOVER — Fetches /.well-known/ai-agent to learn capabilities
2. CONSENT — Verifies the customer has granted availability access
3. AVAILABLE — Queries the customer's calendar for free blocks
4. PROPOSE — Selects optimal slots and creates a proposal
5. NEGOTIATE — Handles accept / counter / reject (up to 3 rounds)
6. CONFIRM — Locks the booking and fires webhooks

# Clone the repo, then:
cd examples/calendar-agent
VENNIO_API_KEY=vennio_sk_live_YOUR_KEY node agent.js BUSINESS_ID CUSTOMER_ID

# Or try it with mock data (no API key needed)
node agent.js --demo --verbose

The agent handles counter-proposals automatically — if the customer suggests a different time, the agent re-proposes using those slots. After three rounds without agreement, it escalates to a human operator.