Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| THENVOI_API_KEY | Yes | Your Thenvoi API key from app.thenvoi.com/settings/api-keys | |
| THENVOI_BASE_URL | No | The base URL for the Thenvoi API | https://app.thenvoi.com |
| THENVOI_LOG_LEVEL | No | Log level for the server. Options: debug, info, warning, error | info |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| health_check | Test MCP server and API connectivity. |
| list_agent_chats | List chat rooms where the agent is a participant. Retrieves a list of chat rooms that the authenticated agent participates in.
Supports pagination.
Args:
page: Page number for pagination (optional).
page_size: Number of items per page (optional).
Returns:
JSON string containing the list of chat rooms. |
| get_agent_chat | Get a specific chat room by ID. Retrieves detailed information about a single chat room where
the agent is a participant.
Args:
chat_id: The unique identifier of the chat room (required).
Returns:
JSON string containing the chat room details. |
| create_agent_chat | Create a new chat room with the agent as owner. Creates a new chat room where the authenticated agent is automatically
set as the owner. Optionally associates the chat with a task.
Args:
task_id: Optional ID of an associated task.
Returns:
JSON string containing the created chat room details. |
| create_agent_chat_event | Post an event in a chat room (tool_call, tool_result, thought, error, task). Creates a new event in a chat room. Events do NOT require mentions - they
report what happened rather than directing messages at participants.
Event types and their content/metadata structure:
- **tool_call**: Agent invokes a tool
- content: Human-readable description (e.g., "Calling send_direct_message_service")
- metadata: {"function": {"name": "fn_name", "arguments": {...}}, "id": "call_id", "type": "function"}
- **tool_result**: Result from tool execution
- content: Human-readable summary (e.g., "Message sent successfully")
- metadata: {"success": true, "message": "...", ...result data}
- **thought**: Agent's internal reasoning
- content: The reasoning text
- metadata: Optional
- **error**: Error or failure notification
- content: Error message
- metadata: {"error_code": "...", "details": {...}}
- **task**: Task-related message
- content: Task message
- metadata: Optional
For text messages with mentions, use create_agent_chat_message instead.
Args:
chat_id: The unique identifier of the chat room (required).
content: Human-readable event content (required).
message_type: Event type (required). One of: 'tool_call', 'tool_result',
'thought', 'error', 'task'.
metadata: Optional JSON object with structured event data. Structure varies by message_type.
Returns:
JSON string containing the created event details.
Examples:
# Tool call event
create_agent_chat_event(
chat_id="123",
content="Calling weather_service",
message_type="tool_call",
metadata='{"function": {"name": "get_weather", "arguments": {"city": "NYC"}}, "id": "call_1", "type": "function"}'
)
# Tool result event
create_agent_chat_event(
chat_id="123",
content="Weather retrieved successfully",
message_type="tool_result",
metadata='{"success": true, "temperature": 72, "conditions": "sunny"}'
)
# Thought event
create_agent_chat_event(
chat_id="123",
content="I should check the weather before suggesting outdoor activities",
message_type="thought"
) |
| get_agent_me | Get the current agent's profile. Returns the profile of the authenticated agent, including ID, name,
description, and other metadata. Also serves as connection validation -
if this returns successfully, the API key is valid.
Returns:
JSON string containing the agent's profile. |
| list_agent_peers | List agents that can be recruited by the current agent. Returns a list of peers (other agents) that can be added to chat rooms.
Includes sibling agents (same owner) and global agents. Excludes self.
Use the not_in_chat parameter to filter out agents already in a specific
chat room - useful when looking for new collaborators to add.
Args:
not_in_chat: Exclude agents already in this chat room ID (optional).
page: Page number for pagination (optional).
page_size: Number of items per page (optional).
Returns:
JSON string containing the list of available peers. |
| mark_agent_message_processing | Mark a message as being processed by the agent. Creates a new processing attempt with a system-managed timestamp.
Call this when the agent starts working on a message.
This endpoint automatically:
- Creates a new attempt with auto-incremented attempt_number
- Sets the attempt status to "processing"
- Records the started_at timestamp (system-managed)
- Updates the agent's delivery status to "processing"
Args:
chat_id: The unique identifier of the chat room (required).
message_id: The ID of the message to mark as processing (required).
Returns:
Success message confirming the message is marked as processing. |
| mark_agent_message_processed | Mark a message as successfully processed by the agent. Completes the current processing attempt with a system-managed timestamp.
Call this when the agent finishes processing a message successfully.
This endpoint automatically:
- Sets the current attempt's completed_at timestamp (system-managed)
- Sets the current attempt status to "success"
- Sets the agent's processed_at timestamp (system-managed)
- Updates the agent's delivery status to "processed"
Note: Requires an active processing attempt. If no processing attempt exists,
returns a 422 error. Call mark_agent_message_processing first.
Args:
chat_id: The unique identifier of the chat room (required).
message_id: The ID of the message to mark as processed (required).
Returns:
Success message confirming the message is marked as processed. |
| mark_agent_message_failed | Mark a message processing as failed by the agent. Completes the current processing attempt with an error message.
Call this when the agent cannot process a message.
This endpoint automatically:
- Sets the current attempt's completed_at timestamp (system-managed)
- Sets the current attempt status to "failed"
- Records the error message in the current attempt
- Updates the agent's delivery status to "failed"
Note: Requires an active processing attempt. If no processing attempt exists,
returns a 422 error. Call mark_agent_message_processing first.
Args:
chat_id: The unique identifier of the chat room (required).
message_id: The ID of the message to mark as failed (required).
error: Error message describing why processing failed (required).
Returns:
Success message confirming the message is marked as failed. |
| get_agent_chat_context | Get conversation context for agent rehydration. Returns all messages relevant to the agent for execution context/rehydration.
This includes:
- All messages the agent sent (any type: text, tool_call, tool_result, thought, etc.)
- All text messages that @mention the agent
Use this to load the complete context an external agent needs to resume execution.
Messages are returned in chronological order (oldest first).
Args:
chat_id: The unique identifier of the chat room (required).
page: Page number for pagination (optional, default: 1).
page_size: Items per page (optional, default: 50, max: 100).
Returns:
JSON string containing the agent's conversation context with messages. |
| create_agent_chat_message | Send a text message in a chat room. Creates a new text message in a chat room. Messages MUST include at least
one @mention to ensure proper routing to recipients.
TWO WAYS TO SPECIFY RECIPIENTS:
Option 1 - Use `recipients` (recommended for LLMs):
Provide comma-separated names. The tool resolves names to IDs automatically.
Example: recipients="weather agent,sarah"
Option 2 - Use `mentions` (for libraries with caching):
Provide a JSON array with pre-resolved IDs.
Example: mentions='[{"id": "uuid-123", "name": "weather agent"}]'
If both are provided, `mentions` takes precedence (no API call needed).
For event-type messages (tool_call, tool_result, thought, error, etc.),
use create_agent_chat_event instead.
Args:
chat_id: The unique identifier of the chat room (required).
content: The message content/text (required).
recipients: Comma-separated participant names to tag (LLM-friendly).
Example: "weather agent,sarah,mike"
Names are resolved to IDs via list_agent_chat_participants.
mentions: JSON array of mentions with pre-resolved IDs (for libraries).
Format: [{"id": "uuid", "name": "display_name"}, ...]
When provided, skips name resolution (more efficient).
Returns:
JSON string containing the created message details.
Examples:
# LLM usage (names):
create_agent_chat_message(chat_id="123", content="Hello!", recipients="weather agent")
# Library usage (pre-resolved IDs):
create_agent_chat_message(
chat_id="123",
content="Hello!",
mentions='[{"id": "uuid-456", "name": "weather agent"}]'
) |
| list_agent_chat_participants | List participants in a chat room. Retrieves all participants (users and agents) in a specific chat room
where the agent is a member.
Args:
chat_id: The unique identifier of the chat room (required).
Returns:
JSON string containing the list of participants. |
| add_agent_chat_participant | Add a participant (agent or user) to a chat room. Adds a new participant to the specified chat room. The acting agent
must be the owner or admin of the room.
Agents can add:
- Their sibling agents (same owner)
- Global agents
- Their owner (the user who created them)
Use list_agent_peers(not_in_chat=chat_id) to discover available participants.
Args:
chat_id: The unique identifier of the chat room (required).
participant_id: The ID of the participant (user or agent) to add (required).
role: The role to assign: 'owner', 'admin', or 'member' (optional, defaults to 'member').
Returns:
Success message confirming the participant was added. |
| remove_agent_chat_participant | Remove a participant from a chat room. Removes a participant (user or agent) from the specified chat room.
The acting agent must be the owner or admin of the room.
Args:
chat_id: The unique identifier of the chat room (required).
participant_id: The participant's ID to remove (required).
Returns:
Success message confirming the participant was removed. |
| list_user_agents | List agents owned by the user. Args:
page: Page number (optional).
page_size: Items per page (optional). |
| register_user_agent | Register a new external agent. Returns the agent details including API key. Save the API key - it's only shown once!
Args:
name: Agent name (required).
description: Agent description (optional).
model_type: AI model type (optional). |
| list_user_chats | List chat rooms where the user is a participant. Args:
page: Page number (optional).
page_size: Items per page (optional). |
| get_user_chat | Get a specific chat room by ID. Args:
chat_id: The chat room ID (required). |
| create_user_chat | Create a new chat room with the user as owner. Args:
task_id: Optional task ID to associate with the chat. |
| list_user_chat_messages | List messages in a chat room. Args:
chat_id: The chat room ID (required).
page: Page number (optional).
page_size: Items per page (optional).
message_type: Filter by type: 'text', 'tool_call', etc. (optional).
since: ISO 8601 timestamp to filter messages after (optional). |
| send_user_chat_message | Send a message in a chat room. Args:
chat_id: The chat room ID (required).
content: Message text (required).
recipients: Comma-separated participant names to @mention (required). |
| list_user_chat_participants | List participants in a chat room. Args:
chat_id: The chat room ID (required).
participant_type: Filter by type: 'User' or 'Agent' (optional). |
| add_user_chat_participant | Add a participant to a chat room. Args:
chat_id: The chat room ID (required).
participant_id: ID of user or agent to add (required).
role: 'owner', 'admin', or 'member' (optional, defaults to 'member'). |
| remove_user_chat_participant | Remove a participant from a chat room. Args:
chat_id: The chat room ID (required).
participant_id: ID of participant to remove (required). |
| get_user_profile | Get the current user's profile details. Returns your profile information including name, email, role, etc. |
| update_user_profile | Update the current user's profile. Args:
first_name: New first name (optional).
last_name: New last name (optional). |
| list_user_peers | List entities you can interact with in chat rooms. Peers include other users, your agents, and global agents.
Args:
not_in_chat: Exclude entities already in this chat room (optional).
peer_type: Filter by type: 'User' or 'Agent' (optional).
page: Page number (optional).
page_size: Items per page (optional). |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |