# Oyster MCP > Oyster manages global HR, payroll, and compliance data directly from your agent. Check time-off requests for a distributed workforce, track expenses, review invoices, or draft new employment records—all without logging into the Oyster dashboard. ## Overview - **Category:** human-resources - **Price:** Free - **Tags:** global-hr, payroll, compliance, expense-management, time-off-tracking ## Description Managing an international team means juggling payroll rules, local labor laws, and disparate systems. This MCP connects your AI client to your Oyster account, letting you handle complex global HR tasks using natural conversation. Instead of jumping between dashboards to check balances or submit expense reports, you ask your agent directly. Need to know if a country supports hiring? Check the list of supported nations. Want to approve leave? Monitor and create time-off requests for every employee, regardless of where they live. This integration gives HR managers and finance teams immediate access to core data—from checking invoice statuses to listing active team engagements. With Vinkius, you connect this power source once, giving your agent a single point of contact for all global workforce management needs. ## Tools ### create_draft_employment Drafts a preliminary employment record, useful when planning a future hire. ### create_expense Submits a new expense report for review by the finance team. ### create_time_off_request Files a formal request for employee leave (vacation or sick time). ### create_webhook Sets up an endpoint to receive real-time updates from Oyster. ### get_company Retrieves general details about the company account. ### get_engagement Fetches specific, detailed records for one employee's current engagement period. ### get_expense Retrieves all the details associated with a single expense report ID. ### get_operation_status Checks if an asynchronous process, like creating an account, has finished or failed. ### get_time_off_request Gets the full status and details for a specific time-off request ID. ### list_engagements Provides an overview list of all current employee engagements in the company. ### list_expenses Returns a comprehensive list of expense reports, allowing filtering by status or date range. ### list_hiring_countries Lists all countries where the company is currently allowed to hire staff. ### list_invoices Pulls a list of company invoices, letting you filter by payment status or payroll period. ### list_subdivisions Lists smaller administrative areas within a specific country for global planning. ### list_time_off_requests Retrieves an overview of all time-off requests, allowing you to see who needs leave approval. ## Prompt Examples **Prompt:** ``` List all active engagements in my Oyster account. ``` **Response:** ``` I've retrieved your engagements. You have 12 active team members across 5 countries. Would you like to see the details for a specific engagement ID? ``` **Prompt:** ``` Show me the details for time off request ID 'tor_98765'. ``` **Response:** ``` Fetching request details... Request 'tor_98765' is for a 'VACATION' from 2023-12-20 to 2024-01-05. The current status is 'APPROVED'. ``` **Prompt:** ``` Create a sick leave request for engagement 'eng_123' for tomorrow. ``` **Response:** ``` I've initiated the sick leave request for engagement 'eng_123' for 2023-10-27. The request has been submitted successfully. ``` ## Capabilities ### Track time off requests View the status of current leave applications or submit new vacation and sick day requests. ### Audit expenses and invoices List existing expense reports, check their review status, or pull company invoice records by payroll period. ### Manage employee details See all active team engagements globally or fetch specific metadata for a single user. ### Plan global hiring Retrieve lists of supported countries and subdivisions to determine where you can hire next. ## Use Cases ### The Quarterly Audit A finance manager needs to reconcile all payroll costs for a specific quarter. Instead of downloading reports from multiple tabs, they ask their agent to list_invoices filtered by the date range and status. This immediately provides an accurate, auditable list for compliance review. ### The Global New Hire An operations lead is planning a team expansion into Vietnam. They first use list_hiring_countries to check availability, then list_subdivisions to find the correct regional office code before calling create_draft_employment. ### The Leave Approver An HR manager needs to process 15 leave requests. Instead of opening 15 profiles, they use list_time_off_requests and then get_time_off_request on the specific ID to confirm approval status for each person. ### The Expense Follow-Up An employee submits an expense report that seems stuck. The manager uses list_expenses to see the report and then get_expense to check exactly which step it's stalled on, allowing for quick follow up. ## Benefits - Audit finances faster. Instead of navigating to the invoicing section, you can simply ask your agent to list invoices filtered by a specific payroll period or status. - Handle leave in bulk. Use list_time_off_requests and get_time_off_request to see who needs approval across your entire global staff instantly, without opening multiple employee profiles. - Improve compliance visibility. List engagements gives you a full view of active employment details for every team member globally, ensuring all records are up-to-date. - Streamline hiring prep. Before planning expansion, use list_hiring_countries and list_subdivisions to confirm local availability and setup requirements in one go. - Track money movement easily. You can query existing expenses using get_expense or check the status of an expense report by calling list_expenses. ## How It Works The bottom line is that your AI client acts as a natural language gateway to complex HR records that used to require multiple dashboard logins. 1. Subscribe to this MCP, then provide your Oyster Personal Access Token within your AI client. 2. Tell your agent exactly what task you need done—for example, 'Show me all pending expense reports for Q2.' 3. The agent executes the necessary action and delivers the requested data or confirms the request's status. ## Frequently Asked Questions **How do I list all active engagements using the Oyster MCP?** You use list_engagements. This tool provides an overview of every current team member's employment status and engagement details across your global organization. **Can I check if a new country is supported for hiring with Oyster MCP?** Yes, you first run list_hiring_countries to see all options. If the country is listed, you can then use list_subdivisions to get precise regional details. **What if I need to check a specific time off request? Do I use Oyster MCP?** Yes. You should first run list_time_off_requests for an overview, and then use get_time_off_request with the ID number to pull up all granular details. **Is creating a draft employment immediate or does it take time?** create_draft_employment is marked as an asynchronous operation. This means you send the request, and the system will update its status over time; you must use get_operation_status to track progress. **How does Oyster MCP handle expense report creation?** You initiate it using create_expense. Remember that this is also an asynchronous process, so the request key will be returned for later status checks.