Perfect Venue MCP tools

MCP tool perfect-venue_list_events

Lists events from your account, including leads. Filter by status (lead, qualified, proposal_sent, confirmed, balance_due, completed or lost), by event date, by venue and by event owner. Each item has the event ID that the other tools take. Lost events are returned only when status is lost, as they are hidden from the home stages in the app.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "perfect-venue_list_events",
    "arguments": {}
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "events": [
      {
        "event_id": "ev_8812",
        "name": "Smith rehearsal dinner",
        "status": "confirmed",
        "start_date": "2026-11-14",
        "start_time": "18:00",
        "end_time": "22:00",
        "group_size": 40,
        "spaces": [
          "Private Room"
        ],
        "owner": "maria@example.com",
        "contact": {
          "name": "Jane Smith",
          "email": "jane@example.com"
        }
      }
    ],
    "next_cursor": null
  },
  "isError": false
}

MCP tool perfect-venue_get_event

Returns the details of one event: date and time, spaces, group size, event type, owner, contact, status, internal notes and the proposal summary with totals, the deposit and the remaining balance. Use it before update_event or send_proposal. The proposal locks when your proposal locking rule says so (at signing, 2 weeks or 1 week before the event, or never), and the response tells you if it has.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "perfect-venue_get_event",
    "arguments": {
      "event_id": "event_8c41d2"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "event_id": "ev_8812",
    "name": "Smith rehearsal dinner",
    "status": "confirmed",
    "event_type": "Rehearsal",
    "start_date": "2026-11-14",
    "start_time": "18:00",
    "end_time": "22:00",
    "group_size": 40,
    "spaces": [
      "Private Room"
    ],
    "owner": "maria@example.com",
    "contact": {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "phone": "555-555-0101"
    },
    "internal_notes": "Vegetarian menu for 6 guests.",
    "proposal": {
      "total": 4800,
      "deposit": 1000,
      "paid": 1800,
      "balance_due": 3000,
      "locked": false
    }
  },
  "isError": false
}

MCP tool perfect-venue_list_payments

Returns the rows of the Payments tab of one event. Each payment says whether it was made online or logged offline, and its status. Offline payments already deduct from the total due on the proposal. Online payments can be refunded with refund_payment; offline payments cannot.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "perfect-venue_list_payments",
    "arguments": {
      "event_id": "ev_8812"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "event_id": "ev_8812",
    "payments": [
      {
        "payment_id": "pay_3301",
        "type": "online",
        "purpose": "deposit",
        "amount": 1000,
        "method": "card",
        "status": "paid",
        "paid_on": "2026-10-04"
      },
      {
        "payment_id": "pay_3302",
        "type": "offline",
        "purpose": "remaining_balance",
        "amount": 800,
        "method": "check",
        "status": "paid",
        "paid_on": "2026-10-09"
      }
    ],
    "total": 4800,
    "balance_due": 3000
  },
  "isError": false
}

MCP tool perfect-venue_list_messages

Returns the emails of one event from the Perfect Venue inbox, so your agent sees who wrote last and when before it answers. Each message says whether it came from the guest or from your team.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "perfect-venue_list_messages",
    "arguments": {
      "event_id": "event_8c41d2"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "event_id": "ev_8812",
    "messages": [
      {
        "from": "team",
        "sent_at": "2026-10-02T10:15:00Z",
        "subject": "Your event inquiry",
        "body": "Thanks for your inquiry. Here is our proposal."
      },
      {
        "from": "guest",
        "sent_at": "2026-10-03T08:40:00Z",
        "subject": "Re: Your event inquiry",
        "body": "Can we move to 60 guests?"
      }
    ]
  },
  "isError": false
}

MCP tool perfect-venue_list_email_templates

Returns the template emails you set up in Settings, Email. Use a template_id from this list in send_email. Templates carry the Personalize fields, which Perfect Venue fills in with the details of each event.

Parameters

No parameters.

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "perfect-venue_list_email_templates",
    "arguments": {}
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "templates": [
      {
        "template_id": "tpl_followup",
        "name": "Follow-up",
        "subject": "Still looking at your date?",
        "body": "Hi, just checking in on your event."
      },
      {
        "template_id": "tpl_balance",
        "name": "Balance reminder",
        "subject": "Your remaining balance",
        "body": "Your remaining balance is due before your event."
      }
    ]
  },
  "isError": false
}

MCP tool perfect-venue_list_spaces

Returns the spaces you set up in Settings, Spaces, with the ID that update_event and create_lead take. Use it to name the room a guest asked for.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "perfect-venue_list_spaces",
    "arguments": {}
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "spaces": [
      {
        "space_id": "sp_01",
        "name": "Private Room"
      },
      {
        "space_id": "sp_02",
        "name": "Patio"
      }
    ]
  },
  "isError": false
}

MCP tool perfect-venue_get_events_report

Returns the rows of the Events report, with the filters of a custom view: event status, venue, event owner, event date and created date. Use created dates to count new leads in a week and the status filter to count confirmed events. Lost events come back only when status is lost, with the lost reason.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "perfect-venue_get_events_report",
    "arguments": {}
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "rows": [
      {
        "event_id": "ev_8812",
        "name": "Smith rehearsal dinner",
        "status": "confirmed",
        "created_at": "2026-10-02",
        "start_date": "2026-11-14",
        "owner": "maria@example.com",
        "total": 4800
      },
      {
        "event_id": "ev_8830",
        "name": "Lee birthday",
        "status": "lead",
        "created_at": "2026-10-08",
        "start_date": "2026-12-05",
        "owner": "maria@example.com",
        "total": 0
      }
    ],
    "count": 2,
    "next_cursor": null
  },
  "isError": false
}

MCP tool perfect-venue_create_lead

Adds an event in the Lead status, the status every contact-form inquiry starts in, with the contact, date, time, guest count and spaces you give. It sends nothing to the guest and is undone with set_event_status lost, so it runs without asking first. Perfect Venue may still run your automated emails for the Lead stage.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "perfect-venue_create_lead",
    "arguments": {
      "first_name": "Alex",
      "last_name": "Client",
      "email": "client@example.com",
      "start_date": "2026-11-14",
      "start_time": "18:00",
      "end_time": "22:00",
      "group_size": 40,
      "event_type": "Birthday",
      "message": "Birthday dinner, needs a private room."
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "event_id": "ev_8841",
    "status": "lead",
    "start_date": "2026-11-14",
    "group_size": 40,
    "contact": {
      "name": "Alex Client",
      "email": "client@example.com"
    }
  },
  "isError": false
}

MCP tool perfect-venue_update_event

Changes the fields you pass and leaves the rest. It does not change the proposal items, prices or the status; use set_event_status for the status. It reaches no guest and is undone by calling it again with the old values, so it runs without asking first.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "perfect-venue_update_event",
    "arguments": {
      "event_id": "event_8c41d2"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "event_id": "ev_8812",
    "status": "confirmed",
    "group_size": 60,
    "updated": [
      "group_size"
    ]
  },
  "isError": false
}

MCP tool perfect-venue_set_event_status

Sets the status of one event: lead, qualified, proposal_sent, confirmed, balance_due, completed or lost. Perfect Venue asks for a canceled reason when an event is moved to lost, so reason is required then. Statuses can trigger your automated emails, which are set by event stage, so a change can reach the guest. By default you confirm each call; you can switch that off for this tool.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "perfect-venue_set_event_status",
    "arguments": {
      "event_id": "event_8c41d2",
      "status": "lead"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "event_id": "ev_8830",
    "status": "qualified",
    "previous_status": "lead"
  },
  "isError": false
}

MCP tool perfect-venue_send_proposal

Sends the current proposal of one event to its contact. Perfect Venue then moves the event to Proposal Sent by itself. The guest can change their menu choices only until the proposal locks. By default you confirm each call; you can switch that off for this tool.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "perfect-venue_send_proposal",
    "arguments": {
      "event_id": "event_8c41d2"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "event_id": "ev_8812",
    "status": "proposal_sent",
    "sent_to": "jane@example.com",
    "sent_at": "2026-10-11T09:30:00+02:00"
  },
  "isError": false
}

MCP tool perfect-venue_send_email

Sends one email to the contact of an event from the inbox, so the reply lands in the same thread. With template_id, Perfect Venue fills in the event details of the Personalize fields. Give body or template_id. By default you confirm each call; you can switch that off for this tool.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "perfect-venue_send_email",
    "arguments": {
      "event_id": "ev_8830",
      "template_id": "tpl_followup",
      "subject": "Still looking at Saturday 5 Dec?"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "event_id": "ev_8830",
    "status": "sent",
    "to": "lee@example.com",
    "subject": "Still looking at Saturday 5 Dec?",
    "sent_at": "2026-10-11T09:32:00+02:00"
  },
  "isError": false
}

MCP tool perfect-venue_log_offline_payment

Logs a payment made outside Perfect Venue on one event, with amount, method, status and date, as Add payment, Offline payment does in the app. It charges no one, but the amount deducts from the total due on the proposal and shows in your payment reports. By default you confirm each call; you can switch that off for this tool.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "perfect-venue_log_offline_payment",
    "arguments": {
      "event_id": "event_8c41d2",
      "amount": 1,
      "method": "method"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "payment_id": "pay_3302",
    "event_id": "ev_8812",
    "type": "offline",
    "amount": 800,
    "method": "check",
    "paid_on": "2026-10-09",
    "balance_due": 3000
  },
  "isError": false
}

MCP tool perfect-venue_refund_payment

Refunds a payment that was made online, in full or in part, with a reason. Offline payments cannot be refunded here; they go back by the original payment method. Perfect Venue notes that a refund can take 5 to 7 business days to reach the guest, and takes the money from your connected payment account or bank account. By default you confirm each call; you can switch that off for this tool.

Parameters

tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "perfect-venue_refund_payment",
    "arguments": {
      "payment_id": "payment_8c41d2",
      "reason": "reason"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "payment_id": "pay_3301",
    "event_id": "ev_8812",
    "refunded": 1000,
    "refund_type": "full",
    "status": "refunded"
  },
  "isError": false
}