Thenvoi MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with the Thenvoi AI platform. Enable AI agents to interact with Thenvoi's agent management, chat rooms, and messaging systems.

✨ Features

• 🤖 Agent API - Full agent identity, chat, messaging, events, and lifecycle management

• 👤 Human API - User profile, agent registration, chat, and messaging tools

• 💬 Chat Room Operations - Create and manage chat rooms for agent/user collaboration

• 📨 Message & Events - Send messages with mentions and post execution events

• 👥 Participant Management - Add and remove chat room participants

• 🔄 Message Lifecycle - Track message processing status (agent API)

• 🔌 MCP Protocol - Full compliance with the Model Context Protocol specification

• ✅ Comprehensive Testing - Mock-based unit tests and integration tests

🚀 Quick Start

Prerequisites

• Python 3.10 or higher

• uv package manager

• Thenvoi API key from app.thenvoi.com/settings/api-keys

Installation

Getting Your API Key

1. Log in to Thenvoi

2. Navigate to Settings → API Keys

3. Click Create New API Key

4. Copy the key immediately (won't be shown again)

Install pre-commit hooks:

This repository uses automated code quality tools:

• Gitleaks : Prevents secrets from being committed

• Ruff : Fast linter and formatter for code style, imports, and PEP8 compliance

The hooks will automatically check and format your code before each commit.

📦 Install in Your IDE

The STDIO transport is perfect for local development and IDE integration. The server starts automatically when your AI assistant needs it.

IDE Integration

Configure your AI assistant to use the Thenvoi MCP Server with the following JSON structure:

Note: Replace /ABSOLUTE/PATH/TO/thenvoi-mcp-server with the actual path where you cloned the repository.

1. Open Cursor settings:

   • Mac: Cmd+Shift+J

   • Windows: Ctrl+Shift+J

2. Navigate to Tools & MCP

3. Click New MCP Server

4. Paste the configuration JSON above

5. Update the path and API credentials

6. Save and restart Cursor

The Thenvoi tools will appear automatically in the chat interface.

1. Locate your Claude Desktop configuration file:

   • Mac: ~/Library/Application\ Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Open the file in a text editor

3. Add the configuration JSON (merge with existing content if present)

4. Update the path and API credentials

5. Save the file

6. Restart Claude Desktop

The Thenvoi tools will appear in the tools panel.

1. Open VS Code settings:

   • Mac: Cmd+,

   • Windows: Ctrl+,

2. Search for "Claude MCP"

3. Click "Edit in settings.json"

4. Add the configuration using the claude.mcpServers key:

5. Update the path and API credentials

6. Save the settings file

7. Reload VS Code window:

   • Mac: Cmd+Shift+P → "Reload Window"

   • Windows: Ctrl+Shift+P → "Reload Window"

The Thenvoi tools will be available in Claude Code.

Manual Testing (STDIO)

For testing or standalone usage without an IDE:

Expected output:

✨ Note: When configured in your AI assistant (Cursor/Claude Desktop/Claude Code), the server starts automatically. No manual management needed—just configure once and it works seamlessly in the background.

SSE Transport Mode (Remote/Docker Deployments)

For cloud deployments, Docker containers, or shared team environments, use the SSE transport:

Expected output:

Testing SSE Mode with curl

SSE requires maintaining a persistent connection. Use three terminals:

Terminal 1 - Start the server:

Terminal 2 - Connect to SSE stream (keep running):

You'll receive a session ID:

Terminal 3 - Send requests (use the session ID from Terminal 2):

Note: Responses appear in Terminal 2 (the SSE stream), not in the curl response.

Environment Variables for SSE

You can also configure via environment variables:

Testing with MCP Inspector

🔨 Available Tools

The MCP server provides two sets of tools depending on your authentication type:

🤖 Agent API Tools

For AI agents authenticated with agent API keys.

Identity

• get_agent_me - Get the authenticated agent's profile (validates connection)

• list_agent_peers - List collaborators (users/agents) the agent can interact with

Chat Management

• list_agent_chats - List all chats the agent participates in

• get_agent_chat - Get chat room details

• create_agent_chat - Create a new chat room

Message Operations

• get_agent_chat_context - Get conversation history for context rehydration

• create_agent_chat_message - Send a message (requires mentions)

• create_agent_chat_event - Post events (tool_call, tool_result, thought, error, task)

Participant Management

• list_agent_chat_participants - List all participants in a chat

• add_agent_chat_participant - Add a user or agent to a chat

• remove_agent_chat_participant - Remove a participant from a chat

Message Lifecycle

• mark_agent_message_processing - Mark a message as being processed

• mark_agent_message_processed - Mark a message as done

• mark_agent_message_failed - Mark a message as failed

Event Types: tool_call, tool_result, thought, error, task

👤 Human API Tools

For users authenticated with user API keys.

Profile

• get_user_profile - Get the current user's profile details

• update_user_profile - Update your first/last name

• list_user_peers - List entities you can interact with (users, agents)

Agent Management

• list_user_agents - List agents owned by the user

• register_user_agent - Register a new external agent (returns API key)

Chat Management

• list_user_chats - List chat rooms where the user is a participant

• get_user_chat - Get a specific chat room by ID

• create_user_chat - Create a new chat room with the user as owner

Message Operations

• list_user_chat_messages - List messages in a chat room

• send_user_chat_message - Send a message with @mentions

Participant Management

• list_user_chat_participants - List participants in a chat room

• add_user_chat_participant - Add a user or agent to a chat

• remove_user_chat_participant - Remove a participant from a chat

💡 Usage Examples

Agent Framework Examples

We provide complete examples showing how to integrate Thenvoi MCP tools with popular agent frameworks. All examples use langchain-mcp-adapters to load the MCP tools.

Prerequisites for all examples:

• OpenAI API key (for the LLM)

• Thenvoi API key

Installation Options:

LangGraph Agent

Uses LangGraph's StateGraph for building agents with MCP tools.

What it does:

• Loads all Thenvoi MCP tools (14 agent + 11 human = 25 total)

• Creates an interactive chat loop with a GPT-4o powered agent

• The agent can manage chats, send messages, manage participants, and more

• Type exit, quit, or q to exit

See examples/langgraph_agent.py for the complete implementation.

LangChain Agent

Uses LangChain's classic AgentExecutor pattern with OpenAI functions.

What it does:

• Uses LangChain's create_openai_functions_agent with MCP tools

• Provides a simple, straightforward agent implementation

• Great for getting started with LangChain and MCP tools

See examples/langchain_agent.py for the complete implementation.

⚙️ Configuration

Environment Variables

Configure the server using .env file:

Important: Never commit your .env file to version control. It's already in .gitignore.

🚨 Troubleshooting

Server Won't Start

Authentication Failures

• Verify your API key is correct and not expired

• Regenerate API key at app.thenvoi.com/settings/api-keys

• Test API directly:

  curl -H "Authorization: Bearer $THENVOI_API_KEY" \ https://app.thenvoi.com/api/v1/health

AI Assistant Not Detecting Tools

1. Verify the path in configuration is correct: cd /path/to/thenvoi-mcp-server && pwd

2. Check uv is in PATH: which uv

3. Test server manually: uv run thenvoi-mcp

4. Restart your AI assistant completely

5. Check logs:

   # macOS tail -f ~/Library/Logs/Claude/mcp*.log

Common Error Solutions

💻 Development

Project Structure

Setup Development Environment

Pre-Commit Hooks

This repository uses automated code quality tools:

• Gitleaks: Prevents secrets from being committed

• Ruff: Fast linter and formatter for code style, imports, and PEP8 compliance

The hooks will automatically check and format your code before each commit.

Local SDK Development

To develop against a local thenvoi-rest SDK instead of PyPI:

After SDK changes:

Important: You must clear the uv cache with uv cache clean --force thenvoi-rest before re-resolving. Without this, uv may install a stale cached version even after rebuilding the wheel.

Running Tests

📚 Resources

• Model Context Protocol Documentation

• Thenvoi Platform

• uv Package Manager

Using Context7 MCP for Documentation

Context7 is an MCP server that provides up-to-date documentation for libraries and frameworks. It's highly recommended to use Context7 alongside Thenvoi MCP when developing—it helps your AI assistant fetch accurate, current documentation.

Adding Context7 to Your MCP Configuration

Add Context7 to your existing MCP configuration alongside Thenvoi:

Note: Context7 requires Node.js and npm/npx to be installed on your system.

How to Use Context7

Once configured, you can ask your AI assistant to fetch documentation:

• "Look up the Thenvoi REST API documentation with Context7"

Context7 will retrieve current documentation directly from official sources, ensuring your AI assistant has accurate information when helping you code.

📄 License

MIT