# vCita MCP > vCita MCP Server connects your small business operations—scheduling, client records, and billing—to any AI agent. Manage appointments, track invoices, create new clients, and coordinate staff availability all through natural conversation. It keeps your entire service business workflow in one place. ## Overview - **Category:** customer-relationship-management - **Price:** Free - **Tags:** small-business-management, appointment-booking, client-portal, invoicing, business-automation ## Description You connect your vCita account right into your AI client—whether it's Claude or Cursor—and you get direct control over every core part of a service business, all through natural chat. This server gives your agent immediate access to your CRM records, scheduling calendar, and financial ledger. You don't have to jump between systems; everything happens in one conversation. To make sure nothing breaks when you run critical tasks, you can first check the connection health using `get_api_status`. That verifies that all your operations will actually run smoothly before you start booking or billing. Managing client records is straightforward. You can pull a directory of every customer in your CRM by calling `list_crm_clients`, giving you a searchable rundown of everyone you've ever seen. If you know who you're looking for, `get_client_details` pulls comprehensive history and contact info based on their ID or contact data. Need to add a brand-new person? Just run `create_crm_client`; it adds them as a new customer record with all the metadata you specify. Scheduling appointments is quick. To book services, your agent uses `create_new_booking`, taking specified services, dates, and times into account. If plans change, you can instantly cancel an existing booking by running `cancel_appointment` using only the specific appointment ID. You don't need to guess what's open; `list_scheduled_appointments` pulls a full list of both future and past meetings on your calendar so you know exactly where you stand. When it comes to staff, you can check who works for you by calling `list_staff_members`. This gives you a complete roster of all team members, along with their roles and unique user IDs. If you need to see what services are even available, `list_offered_services` shows every service name and its current pricing structure that you've set up for booking. Reviewing the money trail is another thing this server handles perfectly. You can retrieve a list of all invoices tied to a client by calling `list_client_invoices`. To see how much cash has come through, run `list_recorded_payments` which shows a history of every payment and transaction against any client account. If you're trying to estimate costs before sending a final bill, `list_price_estimates` pulls up a record of past quotes or estimates that were sent out for future work. These tools let your AI agent pull together complex data sets. You can list all the invoices and payments received for one client, then check their full details, all in sequence. The system handles it. It's built to keep your entire service business workflow contained right where you are. ## Tools ### cancel_appointment Cancels an existing client booking using a specific appointment ID. ### create_new_booking Schedules a service appointment for a client using specified services, dates, and times. ### create_crm_client Adds a brand new customer record to your CRM with contact and metadata information. ### get_api_status Checks the current connection health status of your vCita account to ensure all operations will run smoothly. ### get_client_details Retrieves comprehensive contact and history details for a specific client ID. ### list_staff_members Lists all staff members associated with the account, including their roles and user IDs. ### list_scheduled_appointments Pulls a list of future and past bookings on your calendar for review. ### list_crm_clients Pulls a searchable directory listing of all customers stored in your CRM system. ### list_price_estimates Retrieves a list of past price quotes or estimates sent to clients for future services. ### list_client_invoices Fetches a list of all invoices associated with a given client ID. ### list_recorded_payments Shows a history of all recorded payments and transactions against client accounts. ### list_offered_services Lists every service and its current pricing that you have configured for booking. ## Prompt Examples **Prompt:** ``` Show me my upcoming appointments for this week. ``` **Response:** ``` I've retrieved your schedule. You have 3 appointments: 'Consultation' with John Doe (Tue, 10 AM), 'Strategy Session' with Jane Smith (Wed, 2 PM), and 'Follow-up' with Mike Ross (Fri, 9 AM). Which one would you like more details on? ``` **Prompt:** ``` Search for a client with the email 'jane.doe@example.com'. ``` **Response:** ``` I've found the record. Jane Doe (ID: cl_10293) is a registered client. She has one outstanding invoice for $150 and an upcoming appointment on Wednesday. Shall I retrieve her full contact history? ``` **Prompt:** ``` Book a 'New Consultation' for client 'cl_10293' on Dec 1st at 10 AM. ``` **Response:** ``` Booking successful! I've scheduled the 'New Consultation' (Service ID: svc_552) for client cl_10293 on 2024-12-01 at 10:00 AM UTC. A confirmation has been sent to the client. ``` ## Capabilities ### Manage client records Create new customer entries or pull detailed history on existing clients using their ID or contact info. ### Schedule and modify appointments Book services for specific dates, list upcoming meetings, or instantly cancel a booking through natural language prompts. ### Review financial history Retrieve lists of outstanding invoices, payments received, and pricing estimates sent to clients. ### Coordinate staff resources List all team members and their roles to check who is available for a specific service or date range. ### Check system health Verify the connection status of your vCita account before running critical business tasks. ## Use Cases ### The Client Follow-Up A client calls back after a service. Instead of having to log into the CRM, check the calendar, and then look up billing history, you simply ask your agent: 'What's going on with John Smith?' The agent runs `get_client_details` (for contact info), checks `list_scheduled_appointments` (to see recent services), and reviews `list_client_invoices` (to check for payment status). You get a complete summary in seconds. ### The New Service Offering You launch a new service package. Instead of manually updating your booking form, you run `list_offered_services` to see the current catalog and then use `create_new_booking` with the correct ID/price structure, confirming it's bookable immediately. ### The Overdue Account Check You need a quick picture of cash flow. You ask your agent to list all invoices for clients who haven't had an appointment in 60 days. The agent runs `list_crm_clients` and filters that data, then uses `list_client_invoices` on the results to pinpoint exactly where the money is stuck. ### The Staff Scheduling Conflict An Operations Manager needs to book a team meeting. They first run `list_staff_members` to see who works and their roles. Then, they use `create_new_booking`, specifying the desired staff member ID and service type, making sure the right people are booked. ## Benefits - **Stop jumping between tabs.** Need to confirm a booking? Your agent can check `list_scheduled_appointments`, pull the client's contact info with `get_client_details`, and tell you if they have an outstanding invoice—all in one chat window. No copy/pasting needed. - **Never miss a payment reminder.** Instead of running reports manually, ask your agent to run `list_client_invoices` for the top 10 clients. It instantly summarizes who owes what and when it was due. - **Keep client data clean.** Before booking someone new, use `create_crm_client` to ensure you have all necessary metadata attached to their record right away. This prevents having incomplete files later on. - **Coordinate team resources fast.** If a client books an appointment, the agent can check `list_staff_members` first. You immediately know if the service provider is free or needs coverage before confirming the time slot. - **Verify your setup instantly.** Before running any major task (like billing), run `get_api_status`. This confirms the connection is active and ready, saving you from frustrating 'connection error' messages mid-process. ## How It Works The bottom line is that your AI client acts as a unified dashboard, running all necessary vCita API calls so you don't have to switch apps. 1. Subscribe to the server and enter your vCita API Token (you find this in your developer portal). 2. Connect your preferred AI client (like Claude or Cursor) to the Vinkius Marketplace using the token. 3. Start giving commands. Your agent uses the tools—for example, 'Show me Jane Doe's invoices'—and pulls the data directly into the conversation. ## Frequently Asked Questions **How do I find out if a client has an overdue bill using list_client_invoices?** The agent runs `list_client_invoices` and returns all invoices for that client. You can then ask the agent to filter those results by 'due date' or 'status' to see exactly what is outstanding. **What if I need to change an existing appointment? Should I use cancel_appointment?** Yes, for a full cancellation, `cancel_appointment` works. If you just need to modify details or reschedule it slightly, the agent can usually handle that update through natural language, referencing the original booking ID. **Can I use list_staff_members to check who is available?** The `list_staff_members` tool lists all staff and their roles. For availability on a specific date, you must follow up by using `list_scheduled_appointments`, which pulls the actual booking data. **What is the difference between list_client_invoices and list_recorded_payments?** `list_client_invoices` shows what was billed to the client. `list_recorded_payments` shows all money that has actually been received and processed against those accounts. **How do I check if my vCita connection is active before running a command, like using `get_api_status`?** You call `get_api_status`. The tool returns an immediate status code and metadata. This verifies your API token works correctly before you run any complex operations, such as scheduling or billing. **When I use `list_client_details`, what types of contact and history data can my agent retrieve for a client?** The tool returns comprehensive records including full contact information, service history links, and associated metadata. This gives your AI client everything it needs to build a complete profile in one go. **If I try to use `create_new_booking` and there’s a scheduling conflict, how does the system handle the error?** The tool reports specific error codes and the reason for the failure. For example, it will specify if the slot is double-booked or unavailable. Your agent can then immediately prompt you with resolution options. **If I use `list_crm_clients` and have thousands of records, is the data paginated for performance?** Yes, the tool handles bulk client requests by returning results in manageable pages. You can specify a page limit or number to ensure your agent processes large lists without timing out. **Can I search for a client by their email address?** Yes! Use the `list_crm_clients` tool and provide the optional email parameter. The agent will return the specific record for that client if it exists in your CRM. **How do I book a new service for an existing client?** Use the `create_new_booking` action. You'll need to provide the Client ID, the Service ID, and the start time in ISO 8601 format (e.g., 2024-12-01T10:00:00Z). **Is it possible to list all unpaid invoices via AI?** Absolutely. Use the `list_client_invoices` query. The agent will retrieve all your billing documents, and you can then ask the AI to filter or identify those with a 'pending' or 'overdue' status.