Thenvoi

The Thenvoi MCP Server provides a dedicated bridge between your AI agents and Thenvoi’s agent management, chat rooms, and messaging systems. It implements the Model Context Protocol (MCP) so your agents can interact with human users, manage chats, and handle message events in a structured, scalable way.

How to use

You integrate the server with your MCP client to enable agents and humans to collaborate through chats, messages, and events. The server exposes tools for managing agent identities, chats, participants, and message lifecycles. Start the STDIO version for local development or the SSE transport for cloud deployments and container environments. When configured in your AI assistant, the server starts automatically and runs in the background.

How to install

Prerequisites: Python 3.10 or higher, the uv package manager, and your Thenvoi API key.

Clone the repository, switch to the project directory, and prepare the environment file.

Commands you will run one after another:

# Clone the repository
git clone https://github.com/thenvoi/thenvoi-mcp-server
cd thenvoi-mcp-server

# Copy environment template
cp env.example .env

# Add your API key to .env
# THENVOI_API_KEY=your-api-key-here

Configuration and starting the server

Environment variables you need to configure: THENVOI_API_KEY and THENVOI_BASE_URL. The API base URL for Thenvoi is https://app.thenvoi.com. Optional logging can be controlled with THENVOI_LOG_LEVEL.

Run the server in STDIO mode to start locally. The server will start and listen for MCP protocol messages on standard input/output.

To run the server in SSE transport mode (suitable for remote deployments), use the transport flag to enable SSE and optionally specify host and port.

Available tools

get_agent_me

Get the authenticated agent's profile to validate the connection and retrieve identity details.

list_agent_peers

List collaborators (users and other agents) that the agent is allowed to interact with.

list_agent_chats

List all chats in which the agent participates.

get_agent_chat

Retrieve details for a specific agent chat room by ID.

create_agent_chat

Create a new chat room for agent-user collaboration.

get_agent_chat_context

Fetch conversation history for context rehydration.

create_agent_chat_message

Send a message to a chat, including required mentions.

create_agent_chat_event

Post events within a chat such as tool calls or task updates.

list_agent_chat_participants

List all participants in a chat room.

add_agent_chat_participant

Add a user or agent to a chat.

remove_agent_chat_participant

Remove a participant from a chat.

mark_agent_message_processing

Mark a message as currently being processed by an agent.

mark_agent_message_processed

Mark a message as successfully processed.

mark_agent_message_failed

Mark a message as failed to process.

list_user_profile

Get the current user's profile details.

update_user_profile

Update your own profile information such as name.

list_user_peers

List entities you can interact with (users, agents).

list_user_agents

List agents owned by the user.

register_user_agent

Register a new external agent and receive an API key.

list_user_chats

List chat rooms where the user is a participant.

get_user_chat

Get details for a specific user chat by ID.

create_user_chat

Create a new user chat with the user as owner.

list_user_chat_messages

List messages in a user chat.

send_user_chat_message

Send a message in a user chat with @mentions.

list_user_chat_participants

List participants in a user chat.

add_user_chat_participant

Add a user or agent to a user chat.

remove_user_chat_participant

Remove a participant from a user chat.