# FreeScout MCP MCP

> FreeScout MCP connects your AI agent directly to your entire helpdesk instance. Use this tool to manage every aspect of customer communication, from listing full mailboxes and retrieving customer profiles to drafting replies and adding internal notes—all without leaving your chat window.

## Overview
- **Category:** communication-messaging
- **Price:** Free
- **Tags:** shared-inbox, customer-service, open-source, email-management, ticketing-system

## Description

This MCP lets you talk shop with your FreeScout helpdesk using natural language. Instead of logging into the web portal, you tell your AI client exactly what needs doing: check a specific mailbox for new tickets, find out who a customer is, or draft a reply to them. You can list and inspect all incoming mailboxes, keeping track of where every request lands. Need to talk to team members? Your agent can retrieve user details or even assign conversations by updating their status. When you're done with the ticket, you can create a new conversation from scratch or add an internal note for follow-up. Connecting FreeScout through Vinkius gives your AI client access to this entire catalog of customer service functions, letting you handle tickets and manage user data directly within your agent workspace.

## Tools

### add_note
Adds a private internal note to an existing conversation thread, visible only to your team.

### add_reply
Sends a public reply directly to the customer within their active support thread.

### list_conversations
Provides a list of recent or filtered conversations within a specified mailbox.

### create_conversation
Initiates and records an entirely new ticket or conversation in your helpdesk system.

### create_customer
Registers a brand new user account into the customer directory.

### list_customers
Retrieves a searchable directory list of all active customer accounts in the system.

### delete_conversation
Permanently removes a conversation from your helpdesk records.

### get_conversation
Pulls all current details, history, and status information for a specific ticket ID.

### get_customer
Retrieves all stored profile data associated with a named customer account.

### get_mailbox
Pulls the current state and contents of an entire support inbox by name or ID.

### get_user
Retrieves profile details, status, and contact info for a specific agent user account.

### list_mailboxes
Lists every operational support inbox (e.g., 'Sales,' 'Billing') configured in your FreeScout setup.

### list_threads
Shows a summary of all message threads contained within one specific conversation ID.

### update_conversation
Changes the status, assignee, or priority of an existing conversation ticket.

### update_customer
Modifies specific details (like email address or phone) on an existing customer profile.

### list_users
Lists every active user or agent account, including their role and permissions.

## Prompt Examples

**Prompt:** 
```
List all my mailboxes in FreeScout.
```

**Response:** 
```
I've retrieved your mailboxes. You have: 'Support' (ID: 1), 'Sales' (ID: 2), and 'Billing' (ID: 3). Which one would you like to check?
```

**Prompt:** 
```
Show me the latest conversations in mailbox 1.
```

**Response:** 
```
Found 3 recent conversations in the Support mailbox. One is regarding 'Login Issue' (ID: 502) and another about 'API Access' (ID: 505). Would you like to see the threads for any of these?
```

**Prompt:** 
```
Add an internal note to conversation 502 saying 'Checking with the dev team'.
```

**Response:** 
```
Internal note added successfully to conversation 502. Your team will see it in the FreeScout dashboard.
```

## Capabilities

### View Helpdesk Structure
List all mailboxes and retrieve specific mailbox details so you know exactly where a conversation lives.

### Manage Customer Records
Find existing customer profiles or create brand new ones using the agent.

### Handle Ticket Lifecycle
Create, list, update, and delete entire conversations to track tickets from start to finish.

### Communicate with Customers & Team
Send replies directly to customers or add private internal notes for your team's records.

### Monitor Users and Agents
List all available agents and retrieve detailed user information, helping assign tasks efficiently.

## Use Cases

### A customer asks about an old bug.
The agent calls `get_customer` first to verify the account. Then, they call `list_threads` on the ticket ID to pull the full history of communication regarding the issue before drafting a reply using `add_reply`.

### A new ticket arrives in an unfamiliar queue.
The agent calls `list_mailboxes` to identify the correct department (e.g., 'Billing'). They then use `get_mailbox` for that specific inbox, find a new ticket ID, and call `update_conversation` immediately to assign it to the billing specialist.

### A team member leaves suddenly.
The manager calls `list_users` to check agent roles. They then use `get_user` on the departing user's profile, and finally update all their assigned tickets via `update_conversation` to assign them to a backup.

## Benefits

- Stop copy-pasting ticket data. You can pull full context by calling `get_conversation` to see all messages, threads, and status changes in one go.
- Never lose track of who did what. Use the agent to call `add_note`, documenting internal thoughts or next steps without the customer ever seeing them.
- Manage your entire team's workload instantly. You can use `list_users` and then `update_conversation` to reassign a ticket from an overwhelmed colleague to the right specialist.
- Keep customer data clean and current. If a user changes their email, you simply call `update_customer` instead of hunting for it in multiple tabs.
- Start a conversation or manage mailboxes with precision. You can use `list_mailboxes` first to confirm which support queue needs attention before calling `create_conversation`.

## How It Works

The bottom line is you control complex helpdesk actions by talking to the system, not by clicking buttons in a browser.

1. Subscribe to this MCP on Vinkius and input your FreeScout API key and base URL.
2. Your AI agent uses natural language to identify the required action, such as listing all mailboxes or retrieving a customer's account details.
3. The tool executes the function call against your live FreeScout environment and passes back structured data that your agent then presents in plain English.

## Frequently Asked Questions

**How do I list mailboxes with FreeScout MCP?**
You call `list_mailboxes`. This tool lists every support inbox configured in your system, letting you know exactly which queues (like 'Sales' or 'Support') are active.

**Can I update a conversation using the FreeScout MCP?**
Yes. You use `update_conversation` to change ticket statuses, assignees, and priorities within the system.

**What if I need customer details before replying? Use FreeScout MCP.**
You should call `get_customer` first. This pulls all current profile data for that person, so you can make sure your reply is accurate and uses up-to-date information.

**How do I add private notes in FreeScout MCP?**
You use the `add_note` function. This writes a note visible only to your internal team, keeping it separate from the customer's view of the conversation.

**How do I check if the FreeScout MCP connection is working correctly using the `list_users` tool?**
You run `list_users` to verify the integration. This immediately pulls a list of all active agents and team members, confirming your API key and network access are fully functional.

**What is the best way to manage multiple customer records at once using FreeScout MCP?**
Use `list_customers` first. This allows you to pull a comprehensive roster of all client accounts without manually looking them up one by one, making bulk analysis easy.

**When should I use the `delete_conversation` tool within FreeScout MCP?**
You use `delete_conversation` only when a ticket is confirmed resolved and needs to be removed from the active queue. This keeps your workspace clean and focused.

**How do I pull the complete history of messages in FreeScout MCP?**
To get full context, run `list_threads`. This function retrieves every message sent within a conversation's timeline, ensuring you never miss background details when drafting a response.

**How do I reply to a customer conversation using the AI?**
You can use the `add_reply` tool. Just provide the Conversation ID and the body of your message, and the agent will send it to the customer via FreeScout.

**Can I update the status or assignee of a ticket?**
Yes! Use the `update_conversation` tool. You can change the status (active, pending, closed, spam) or provide an `assignee_id` to route the ticket to a specific team member.

**Is it possible to add internal notes that the customer won't see?**
Absolutely. Use the `add_note` tool to post internal comments on a conversation. These are visible to your team in FreeScout but are never sent to the customer.