### Install Dependencies for Thenvoi MCP Examples

Source: https://github.com/thenvoi/thenvoi-mcp/blob/develop/README.md

Installs the necessary dependencies for Thenvoi MCP examples. It supports installing all dependencies or specific ones for frameworks like LangGraph or LangChain.

```bash
# Install dependencies for ALL examples
uv sync --extra examples

# OR install dependencies for specific frameworks:

# LangGraph only
uv sync --extra langgraph

# LangChain only
uv sync --extra langchain
```

--------------------------------

### Configure and Run LangChain Agent Example

Source: https://github.com/thenvoi/thenvoi-mcp/blob/develop/README.md

Sets up API keys and runs an interactive LangChain agent example using OpenAI functions. This provides a straightforward implementation for interacting with MCP tools.

```bash
# Set your API keys
export OPENAI_API_KEY="sk-..."
export THENVOI_API_KEY="thnv_..."

# Run the interactive agent
uv run examples/langchain_agent.py
```

--------------------------------

### Installing Dependencies with UV

Source: https://github.com/thenvoi/thenvoi-mcp/blob/develop/claude.md

Commands for managing project dependencies using the `uv` package manager. Includes synchronizing existing dependencies, adding new ones, and installing.

```bash
uv sync
uv add <package>
```

--------------------------------

### Install Dependencies with uv

Source: https://github.com/thenvoi/thenvoi-mcp/blob/develop/README.md

Installs project dependencies using the uv package manager. Supports installing with development dependencies, example dependencies, specific agent framework dependencies, or a combination.

```bash
# Install with dev dependencies
uv sync --extra dev

# Install with ALL examples dependencies
uv sync --extra examples

# Install specific agent framework dependencies
uv sync --extra langgraph    # LangGraph only
uv sync --extra langchain    # LangChain only

# Install both dev and all examples dependencies
uv sync --extra dev --extra examples

# Install pre-commit hooks
uv run pre-commit install
```

--------------------------------

### Configure and Run LangGraph Agent Example

Source: https://github.com/thenvoi/thenvoi-mcp/blob/develop/README.md

Sets up API keys and runs an interactive LangGraph agent example. This agent leverages Thenvoi MCP tools for chat management, message sending, and participant operations, powered by a GPT-4o model.

```bash
# Set your API keys
export OPENAI_API_KEY="sk-..."
export THENVOI_API_KEY="thnv_..."

# Run the interactive agent
uv run examples/langgraph_agent.py
```

--------------------------------

### Install and Configure Thenvoi MCP Server

Source: https://github.com/thenvoi/thenvoi-mcp/blob/develop/README.md

Instructions for cloning the repository, setting up environment variables, and installing pre-commit hooks for the Thenvoi MCP Server. Requires Python 3.10+ and uv package manager.

```bash
git clone https://github.com/thenvoi/thenvoi-mcp-server
cd thenvoi-mcp-server
cp env.example .env
# Add your API key to .env
# THENVOI_API_KEY=your-api-key-here
uv run pre-commit install
```

--------------------------------

### Troubleshoot Server Startup Issues

Source: https://github.com/thenvoi/thenvoi-mcp/blob/develop/README.md

Provides commands to diagnose and resolve issues when the Thenvoi MCP server fails to start. It includes checks for Python and uv versions, and running the server in debug mode.

```bash
# Check Python version (must be 3.10+)
python --version

# Verify uv is installed
uv --version

# Try running with debug mode
THENVOI_LOG_LEVEL=debug uv run thenvoi-mcp
```

--------------------------------

### Test SSE Mode with curl - Start Server

Source: https://github.com/thenvoi/thenvoi-mcp/blob/develop/README.md

Initiates the thenvoi-mcp server in SSE mode on a specific port (e.g., 3000) for testing purposes. This command is the first step in a multi-terminal testing setup for SSE functionality.

```bash
uv run thenvoi-mcp --transport sse --port 3000
```

--------------------------------

### MCP Tool Template Example

Source: https://github.com/thenvoi/thenvoi-mcp/blob/develop/claude.md

A Python template demonstrating how to define a tool for the Thenvoi MCP server. It includes necessary imports, the `@mcp.tool()` decorator, type hints for parameters and return values, accessing the API client via `get_app_context`, and returning a string.

```python
from thenvoi_mcp.shared import mcp, get_app_context, AppContextType

@mcp.tool()
def my_tool(ctx: AppContextType, param: str) -> str:
    """Tool description for AI assistants."""
    client = get_app_context(ctx).client
    # Use client.human_api.* or client.agent_api.*
    return "Success message"
```

--------------------------------

### Local SDK Development Workflow

Source: https://github.com/thenvoi/thenvoi-mcp/blob/develop/README.md

Guides through setting up a local development environment for the thenvoi-rest SDK. This involves generating the SDK with Fern, structuring the package, building a wheel, and configuring uv to use the local SDK. It also details the steps to regenerate and rebuild the SDK after making changes.

```bash
# 1. Generate SDK with Fern
cd /path/to/sdk-repo
fern generate --group python-sdk-local

# 2. Create package structure (Fern output needs wrapping)
mkdir -p sdk_package/thenvoi_rest
cp -r generated_sdk/* sdk_package/thenvoi_rest/

# 3. Create pyproject.toml for the package
cat > sdk_package/pyproject.toml << 'EOF'
[project]
name = "thenvoi-rest"
version = "0.0.1"
requires-python = ">=3.11"
dependencies = ["httpx>=0.25.0", "pydantic>=2.0.0"]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
EOF

# 4. Build wheel
cd sdk_package && uv build

# 5. Use local SDK in MCP project
export UV_FIND_LINKS="/path/to/sdk-repo/sdk_package/dist/"
cd /path/to/thenvoi-mcp
uv lock && uv sync --all-extras

# After SDK changes:
# 1. Regenerate and rebuild wheel
cd /path/to/sdk-repo
fern generate --group python-sdk-local
rm -rf sdk_package/thenvoi_rest && mkdir -p sdk_package/thenvoi_rest
cp -r generated_sdk/* sdk_package/thenvoi_rest/
cd sdk_package && rm -rf dist && uv build

# 2. Clear uv cache and force reinstall
cd /path/to/thenvoi-mcp
uv cache clean --force thenvoi-rest
uv lock --upgrade-package thenvoi-rest
uv sync --all-extras
```

--------------------------------

### Running Tests with pytest

Source: https://github.com/thenvoi/thenvoi-mcp/blob/develop/README.md

Executes tests using pytest, with options for running all tests, enabling verbose output, targeting specific test files, and generating HTML coverage reports. Assumes pytest and coverage are installed.

```bash
# Run all tests with coverage
uv run pytest

# Verbose output
uv run pytest -v

# Run specific test file
uv run pytest tests/test_agents.py -v

# Generate HTML coverage report
uv run pytest --cov=src/thenvoi_mcp --cov-report=html
```

--------------------------------

### Get Agent Me Tool (Python)

Source: https://context7.com/thenvoi/thenvoi-mcp/llms.txt

Retrieves the profile information of the authenticated agent, including its ID, name, description, model type, and owner. This tool helps validate API access.

```python
# Tool: get_agent_me()
# No parameters required

# Returns JSON:
# {
#   "data": {
#     "id": "550e8400-e29b-41d4-a716-446655440000",
#     "name": "weather-agent",
#     "description": "Agent that provides weather information",
#     "model_type": "gpt-4o",
#     "owner_id": "user-123",
#     "created_at": "2025-01-15T10:30:00Z",
#     "updated_at": "2025-01-15T10:30:00Z"
#   }
# }
```

--------------------------------

### Test with MCP Inspector

Source: https://github.com/thenvoi/thenvoi-mcp/blob/develop/README.md

Utilizes the MCP Inspector tool to run the thenvoi-mcp server. This command is useful for debugging and inspecting the server's behavior during development. It requires npx and the inspector package to be installed.

```bash
npx @modelcontextprotocol/inspector uv --directory /path/to/thenvoi-mcp-server run thenvoi-mcp
```

--------------------------------

### Retrieve Agent Chat Details

Source: https://context7.com/thenvoi/thenvoi-mcp/llms.txt

Fetches specific details for a given chat ID. This tool is useful for getting metadata about a conversation.

```python
# Tool: get_agent_chat(chat_id)

# Example: Get specific chat details
# get_agent_chat(chat_id="chat-abc-123")

# Returns JSON:
# {
#   "data": {
#     "id": "chat-abc-123",
#     "task_id": "task-project-alpha",
#     "owner_id": "user-456",
#     "owner_type": "User",
#     "created_at": "2025-01-15T09:00:00Z",
#     "updated_at": "2025-01-20T11:30:00Z"
#   }
# }
```

--------------------------------

### Test SSE Mode with curl - Call a Tool

Source: https://github.com/thenvoi/thenvoi-mcp/blob/develop/README.md

Sends a 'tools/call' JSON-RPC request to execute a specific tool on the thenvoi-mcp server. This example demonstrates calling the 'health_check' tool. It requires a valid session ID and tool arguments.

```bash
# 3. Call a tool (e.g., health_check)
curl -X POST "http://127.0.0.1:3000/messages/?session_id=YOUR_SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"health_check","arguments":{}}}'
```

--------------------------------

### Test SSE Transport with Thenvoi MCP Server

Source: https://context7.com/thenvoi/thenvoi-mcp/llms.txt

This section provides instructions for testing the Server-Sent Events (SSE) transport mode of the Thenvoi MCP server, particularly useful for remote deployments. It involves starting the SSE server in one terminal, connecting to the SSE stream in a second terminal using curl, and then sending requests to the server using the session ID obtained from the SSE stream in a third terminal. This allows for validation of remote communication.

```bash
# Terminal 1: Start SSE server
uv run thenvoi-mcp --transport sse --port 3000

# Output:
# 2025-12-18 17:15:55 - thenvoi-mcp - INFO - Starting thenvoi-mcp-server v1.0.0
# 2025-12-18 17:15:55 - thenvoi-mcp - INFO - Server ready - listening on http://127.0.0.1:3000
# 2025-12-18 17:15:55 - thenvoi-mcp - INFO - SSE endpoint: /sse | Messages endpoint: /messages/ 

# Terminal 2: Connect to SSE stream (keep running)
curl -N http://127.0.0.1:3000/sse

# Output:
# event: endpoint
# data: /messages/?session_id=abc123def456...

# Terminal 3: Send requests (use session ID from Terminal 2)
export SESSION_ID="abc123def456..."

```

--------------------------------

### Build LangChain Agents with Thenvoi MCP Tools

Source: https://context7.com/thenvoi/thenvoi-mcp/llms.txt

This Python script demonstrates building LangChain agents using Thenvoi MCP tools with the AgentExecutor pattern. It connects to the Thenvoi MCP server, loads the available tools, and then creates an LLM and an agent executor. An interactive loop allows users to chat with the agent. Dependencies include asyncio, os, dotenv, langchain, langchain_mcp_adapters, and langchain_openai.

```python
#!/usr/bin/env python3
import asyncio
import os
from dotenv import load_dotenv
from langchain.agents import create_agent
from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain_openai import ChatOpenAI

load_dotenv()

async def main():
    # Connect to Thenvoi MCP server
    client = MultiServerMCPClient({
        "thenvoi": {
            "command": "uv",
            "args": ["--directory", "/path/to/thenvoi-mcp-server", "run", "thenvoi-mcp"],
            "transport": "stdio",
            "env": {
                "THENVOI_API_KEY": os.getenv("THENVOI_API_KEY"),
                "THENVOI_BASE_URL": "https://app.thenvoi.com"
            }
        }
    })

    # Load Thenvoi tools
    tools = await client.get_tools()
    print(f"Loaded {len(tools)} tools!")

    # Create LLM and agent
    llm = ChatOpenAI(model="gpt-4o", temperature=0)
    agent_executor = create_agent(llm, tools)

    # Interactive loop
    while True:
        user_input = input("You: ").strip()
        if not user_input:
            continue
        if user_input.lower() in ["exit", "quit", "q"]:
            break

        try:
            result = await agent_executor.ainvoke({"messages": [("user", user_input)]})
            last_message = result["messages"][-1]
            print(f"\nAgent: {last_message.content}\n")
        except Exception as e:
            print(f"\nError: {str(e)}\n")

if __name__ == "__main__":
    asyncio.run(main())

# Usage:
# export OPENAI_API_KEY="sk-..."
# export THENVOI_API_KEY="thnv_a_..."
# uv run examples/langchain_agent.py

```

--------------------------------

### Create Agent Chat Task Event

Source: https://context7.com/thenvoi/thenvoi-mcp/llms.txt

Creates a chat event of type 'task' for an agent. This function is used to initiate tasks or actions within a chat conversation, such as starting data analysis.

```python
create_agent_chat_event(
    chat_id="chat-abc-123",
    content="Starting weather analysis for next 7 days",
    message_type="task"
)
```

--------------------------------

### Running Unit Tests with Pytest

Source: https://github.com/thenvoi/thenvoi-mcp/blob/develop/claude.md

Commands for executing unit tests using `pytest`. Includes options for running all tests, specific tests using `-k`, and running tests with code coverage analysis.

```bash
uv run pytest tests/ --ignore=tests/integration/ -v
uv run pytest tests/ -k "test_name"
uv run pytest tests/ --ignore=tests/integration/
```

--------------------------------

### Build LangGraph Agents with Thenvoi MCP Tools

Source: https://context7.com/thenvoi/thenvoi-mcp/llms.txt

This Python script demonstrates how to integrate Thenvoi MCP tools into a LangGraph agent. It sets up a connection to the Thenvoi MCP server, loads tools, defines an agent node using an LLM, and builds a LangGraph with a tool node. The script includes an interactive chat loop for testing. Dependencies include asyncio, os, dotenv, langchain_core, langchain_mcp_adapters, langchain_openai, and langgraph.

```python
#!/usr/bin/env python3
import asyncio
import os
from dotenv import load_dotenv
from langchain_core.messages import HumanMessage
from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain_openai import ChatOpenAI
from langgraph.graph import MessagesState, StateGraph, START
from langgraph.prebuilt import ToolNode, tools_condition

load_dotenv()

async def main():
    # Connect to Thenvoi MCP server
    client = MultiServerMCPClient({
        "thenvoi": {
            "command": "uv",
            "args": ["--directory", "/path/to/thenvoi-mcp-server", "run", "thenvoi-mcp"],
            "transport": "stdio",
            "env": {
                "THENVOI_API_KEY": os.getenv("THENVOI_API_KEY"),
                "THENVOI_BASE_URL": "https://app.thenvoi.com"
            }
        }
    })

    # Load all Thenvoi MCP tools (14 agent + 11 human = 25 total)
    tools = await client.get_tools()
    print(f"Loaded {len(tools)} tools!")

    # Create LLM
    model = ChatOpenAI(model="gpt-4o", temperature=0)

    # Define agent node
    def call_model(state: MessagesState):
        response = model.bind_tools(tools).invoke(state["messages"])
        return {"messages": [response]}

    # Build LangGraph
    builder = StateGraph(MessagesState)
    builder.add_node("agent", call_model)
    builder.add_node("tools", ToolNode(tools))
    builder.add_edge(START, "agent")
    builder.add_conditional_edges("agent", tools_condition)
    builder.add_edge("tools", "agent")
    graph = builder.compile()

    # Interactive chat loop
    messages = []
    while True:
        user_input = input("You: ").strip()
        if user_input.lower() in ["exit", "quit", "q"]:
            break

        messages.append(HumanMessage(content=user_input))
        result = await graph.ainvoke({"messages": messages})
        messages = result["messages"]
        print(f"\nAgent: {messages[-1].content}\n")

if __name__ == "__main__":
    asyncio.run(main())

# Usage:
# export OPENAI_API_KEY="sk-..."
# export THENVOI_API_KEY="thnv_a_..."
# uv run examples/langgraph_agent.py

# Example interaction:
# You: Create a chat room and invite the weather-agent
# Agent: I've created a new chat room (ID: chat-xyz-789) and added weather-agent as a participant.
# You: Send a message asking about tomorrow's weather
# Agent: I've sent the message to weather-agent in the chat room.

```

--------------------------------

### Manual Testing of Thenvoi MCP Server

Source: https://github.com/thenvoi/thenvoi-mcp/blob/develop/README.md

Command to navigate to the cloned repository directory for manual testing or standalone usage of the Thenvoi MCP Server via STDIO.

```bash
cd /path/to/thenvoi-mcp-server
```

--------------------------------

### Manage Message Processing Status

Source: https://context7.com/thenvoi/thenvoi-mcp/llms.txt

Enables tracking the lifecycle of messages processed by agents. This includes marking a message as 'processing' when an agent starts working on it, marking it as 'processed' upon successful completion, or 'failed' if an error occurs.

```python
# Tool: mark_agent_message_processing(chat_id, message_id)

# Example: Mark message as being processed (when agent starts work)
mark_agent_message_processing(
    chat_id="chat-abc-123",
    message_id="msg-incoming-456"
)
```

```python
# Tool: mark_agent_message_processed(chat_id, message_id)

# Example: Mark message as successfully processed (when agent completes work)
mark_agent_message_processed(
    chat_id="chat-abc-123",
    message_id="msg-incoming-456"
)
```

```python
# Tool: mark_agent_message_failed(chat_id, message_id, error)

# Example: Mark message as failed (when agent encounters an error)
mark_agent_message_failed(
    chat_id="chat-abc-123",
    message_id="msg-incoming-456",
    error="Weather API service unavailable - timeout after 30s"
)
```

--------------------------------

### Run Thenvoi MCP Server (Python)

Source: https://context7.com/thenvoi/thenvoi-mcp/llms.txt

Initializes and runs the Thenvoi MCP server. Supports both STDIO mode for local IDE integration and SSE mode for remote deployments. Requires environment variables for API key and base URL.

```bash
# STDIO mode (default - for IDE integration)
# Set environment variables
export THENVOI_API_KEY="thnv_a_1234567890_abcdef"
export THENVOI_BASE_URL="https://app.thenvoi.com"

# Run the server
uv run thenvoi-mcp

# SSE mode (for remote/Docker deployments)
uv run thenvoi-mcp --transport sse --host 0.0.0.0 --port 3000

# Expected output:
# 2025-11-19 17:09:51,621 - thenvoi-mcp - INFO - Starting thenvoi-mcp-server v1.0.0
# 2025-11-19 17:09:51,621 - thenvoi-mcp - INFO - Base URL: https://app.thenvoi.com
# 2025-11-19 17:09:51,621 - thenvoi-mcp - INFO - API key type: agent
# 2025-11-19 17:09:51,621 - thenvoi-mcp - INFO - Server ready - listening for MCP protocol messages on STDIO
```

--------------------------------

### Get Agent Identity via Thenvoi MCP Server

Source: https://context7.com/thenvoi/thenvoi-mcp/llms.txt

Retrieves the identity information of the agent using the 'get_agent_me' tool on the Thenvoi MCP Server. This is executed via a JSONRPC 2.0 'tools/call' request. An active session ID is necessary for this operation.

```shell
curl -X POST "http://127.0.0.1:3000/messages/?session_id=$SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"get_agent_me","arguments":{}}}'
```

--------------------------------

### List Tools API

Source: https://context7.com/thenvoi/thenvoi-mcp/llms.txt

Lists the available tools that can be called by the agent.

```APIDOC
## POST /messages/

### Description
Lists the available tools that can be called by the agent.

### Method
POST

### Endpoint
`/messages/`

### Parameters
#### Query Parameters
- **session_id** (string) - Required - The session identifier for the connection.

#### Request Body
- **jsonrpc** (string) - Required - Specifies the JSON-RPC version, should be "2.0".
- **id** (integer) - Required - A unique identifier for the request.
- **method** (string) - Required - The method to call, should be "tools/list".
- **params** (object) - Required - An empty object for this method.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}
```

### Response
(Note: Responses appear in SSE stream, not in curl response)
#### Success Response (200)
- **jsonrpc** (string) - The JSON-RPC version.
- **id** (integer) - The request ID.
- **result** (array) - An array of available tool objects.
  - **name** (string) - The name of the tool.
  - **description** (string) - A description of the tool.
  - **input_schema** (object) - The JSON schema for the tool's input arguments.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": [
    {
      "name": "health_check",
      "description": "Checks the health of the server.",
      "input_schema": {}
    }
  ]
}
```
```

--------------------------------

### Running Integration Tests with Pytest

Source: https://github.com/thenvoi/thenvoi-mcp/blob/develop/claude.md

Command to execute integration tests using `pytest`. This requires an API key and will run tests in verbose mode without coverage.

```bash
uv run pytest tests/integration/ -v -s --no-cov
```

--------------------------------

### Register and List User Agents

Source: https://context7.com/thenvoi/thenvoi-mcp/llms.txt

Enables the registration of new external agents and listing of agents owned by the user. Registration requires a name and can optionally include a description and model type. Listing returns agent details including ID, name, description, model type, and creation timestamp.

```python
# Tool: list_user_agents(page=1, page_size=50)

# Example: List all agents owned by the user
list_user_agents()

# Tool: register_user_agent(name, description=None, model_type=None)

# Example: Register a new agent
register_user_agent(
    name="translation-agent",
    description="Translates text between languages",
    model_type="gpt-4o"
)
```

--------------------------------

### Initialize Connection API

Source: https://context7.com/thenvoi/thenvoi-mcp/llms.txt

Initializes a connection with the Thenvoi MCP Server. This is typically the first step before sending other commands.

```APIDOC
## POST /messages/

### Description
Initializes a connection with the Thenvoi MCP Server.

### Method
POST

### Endpoint
`/messages/`

### Parameters
#### Query Parameters
- **session_id** (string) - Required - The session identifier for the connection.

#### Request Body
- **jsonrpc** (string) - Required - Specifies the JSON-RPC version, should be "2.0".
- **id** (integer) - Required - A unique identifier for the request.
- **method** (string) - Required - The method to call, should be "initialize".
- **params** (object) - Required - An object containing the parameters for the initialize method.
  - **protocolVersion** (string) - Required - The protocol version, e.g., "2024-11-05".
  - **capabilities** (object) - Optional - Client capabilities.
  - **clientInfo** (object) - Optional - Information about the client.
    - **name** (string) - Required - The name of the client.
    - **version** (string) - Required - The version of the client.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "test",
      "version": "1.0"
    }
  }
}
```

### Response
(Note: Responses appear in SSE stream, not in curl response)
#### Success Response (200)
- **jsonrpc** (string) - The JSON-RPC version.
- **id** (integer) - The request ID.
- **result** (object) - The result of the initialization.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {}
}
```
```

--------------------------------

### Test SSE Mode with curl - List Available Tools

Source: https://github.com/thenvoi/thenvoi-mcp/blob/develop/README.md

Sends a 'tools/list' JSON-RPC request to the thenvoi-mcp server to retrieve a list of available tools. This command is used after initializing the connection and requires a valid session ID.

```bash
# 2. List available tools
curl -X POST "http://127.0.0.1:3000/messages/?session_id=YOUR_SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
```

--------------------------------

### STDIO Server

Source: https://github.com/thenvoi/thenvoi-mcp/blob/develop/README.md

Instructions on how to run the Thenvoi-MCP server using the default STDIO transport mode.

```APIDOC
## Run the STDIO server

Use the following command to start the Thenvoi-MCP server with STDIO transport:

### Command
```bash
uv run thenvoi-mcp
```

### Expected Output
```
2025-11-19 17:09:51,621 - thenvoi-mcp - INFO - Starting thenvoi-mcp-server v1.0.0
2025-11-19 17:09:51,621 - thenvoi-mcp - INFO - Base URL: https://app.thenvoi.com
2025-11-19 17:09:51,621 - thenvoi-mcp - INFO - Server ready - listening for MCP protocol messages on STDIO
```

**Note:** When configured in your AI assistant (Cursor/Claude Desktop/Claude Code), the server starts automatically and requires no manual management.
```

--------------------------------

### List Agent Peers Tool (Python)

Source: https://context7.com/thenvoi/thenvoi-mcp/llms.txt

Finds and lists available agent peers that can be recruited for collaboration in chat rooms. Supports filtering by excluding agents already in a specific chat and pagination.

```python
# Tool: list_agent_peers(not_in_chat=None, page=1, page_size=50)

# Example: List all available peers
# list_agent_peers()

# Example: Find peers not in a specific chat (useful for adding new collaborators)
# list_agent_peers(not_in_chat="chat-abc-123")

# Returns JSON:
# {
#   "data": [
#     {
#       "id": "agent-456",
#       "name": "calendar-agent",
#       "description": "Manages calendars and schedules",
#       "model_type": "gpt-4o"
#     },
#     {
#       "id": "agent-789",
#       "name": "email-agent",
#       "description": "Handles email operations",
#       "model_type": "claude-sonnet-3.5"
#     }
#   ],
#   "page": 1,
#   "page_size": 50,
#   "total": 2
# }
```

--------------------------------

### Troubleshoot AI Assistant Tool Detection

Source: https://github.com/thenvoi/thenvoi-mcp/blob/develop/README.md

Steps to resolve issues where an AI assistant is not detecting Thenvoi MCP tools. This involves verifying configuration paths, ensuring uv is in PATH, testing the server, and checking logs.

```bash
# Check server path
cd /path/to/thenvoi-mcp-server && pwd

# Check uv in PATH
which uv

# Test server manually
uv run thenvoi-mcp

# Check logs (macOS example)
tail -f ~/Library/Logs/Claude/mcp*.log
```

--------------------------------

### Running Code Quality Checks

Source: https://github.com/thenvoi/thenvoi-mcp/blob/develop/claude.md

Commands to execute code linting and formatting checks using `pre-commit` and its associated hooks (ruff, pyrefly, detect-secrets). Ensures code quality and security before committing.

```bash
uv run pre-commit run --all-files
```

--------------------------------

### Create Agent Chat Tool (Python)

Source: https://context7.com/thenvoi/thenvoi-mcp/llms.txt

Creates a new chat room where the agent acts as the owner, facilitating multi-agent collaboration. Can be optionally associated with a specific task ID.

```python
# Tool: create_agent_chat(task_id=None)

# Example: Create a basic chat room
# create_agent_chat()

# Example: Create a chat room associated with a task
# create_agent_chat(task_id="task-xyz-789")

# Returns JSON:
# {
#   "data": {
#     "id": "chat-new-456",
#     "task_id": "task-xyz-789",
#     "owner_id": "agent-123",
#     "owner_type": "Agent",
#     "created_at": "2025-01-20T14:22:00Z",
#     "updated_at": "2025-01-20T14:22:00Z"
#   }
# }
```

--------------------------------

### IDE Configuration for Thenvoi MCP Server (JSON)

Source: https://github.com/thenvoi/thenvoi-mcp/blob/develop/README.md

Configuration structure in JSON format for integrating the Thenvoi MCP Server with AI assistants via STDIO transport. This enables local development and IDE integration. Requires specifying command, arguments, and environment variables like API key and base URL.

```json
{
  "mcpServers": {
    "thenvoi": {
      "command": "/ABSOLUTE/PATH/TO/uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/thenvoi-mcp-server",
        "run",
        "thenvoi-mcp"
      ],
      "env": {
        "THENVOI_API_KEY": "your_api_key_here",
        "THENVOI_BASE_URL": "https://app.thenvoi.com"
      }
    }
  }
}
```

--------------------------------

### Initialize Connection with Thenvoi MCP Server

Source: https://context7.com/thenvoi/thenvoi-mcp/llms.txt

Establishes an initial connection to the Thenvoi MCP Server using a POST request to the messages endpoint. This step is crucial before any other operations can be performed. It requires a session ID and sends a JSONRPC 2.0 initialize request with protocol version and client information.

```shell
curl -X POST "http://127.0.0.1:3000/messages/?session_id=$SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
```

--------------------------------

### Testing with MCP Inspector

Source: https://github.com/thenvoi/thenvoi-mcp/blob/develop/README.md

Instructions on how to test the Thenvoi-MCP server using the MCP Inspector tool.

```APIDOC
## Testing with MCP Inspector

Use the MCP Inspector for testing the Thenvoi-MCP server.

### Command
```bash
npx @modelcontextprotocol/inspector uv --directory /path/to/thenvoi-mcp-server run thenvoi-mcp
```
```

--------------------------------

### Call Tool API

Source: https://context7.com/thenvoi/thenvoi-mcp/llms.txt

Calls a specific tool with provided arguments.

```APIDOC
## POST /messages/

### Description
Calls a specific tool with provided arguments.

### Method
POST

### Endpoint
`/messages/`

### Parameters
#### Query Parameters
- **session_id** (string) - Required - The session identifier for the connection.

#### Request Body
- **jsonrpc** (string) - Required - Specifies the JSON-RPC version, should be "2.0".
- **id** (integer) - Required - A unique identifier for the request.
- **method** (string) - Required - The method to call, should be "tools/call".
- **params** (object) - Required - An object containing the parameters for the call method.
  - **name** (string) - Required - The name of the tool to call.
  - **arguments** (object) - Optional - The arguments to pass to the tool.

### Request Example (health_check)
```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "health_check",
    "arguments": {}
  }
}
```

### Request Example (get_agent_me)
```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "get_agent_me",
    "arguments": {}
  }
}
```

### Response
(Note: Responses appear in SSE stream, not in curl response)
#### Success Response (200)
- **jsonrpc** (string) - The JSON-RPC version.
- **id** (integer) - The request ID.
- **result** (any) - The result of the tool call. The structure depends on the tool called.

#### Response Example (health_check)
```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "status": "ok"
  }
}
```
```

--------------------------------

### List Agent Chats Tool (Python)

Source: https://context7.com/thenvoi/thenvoi-mcp/llms.txt

Retrieves a list of chat rooms that the agent is a participant in. Supports pagination for managing large numbers of chats.

```python
# Tool: list_agent_chats(page=1, page_size=50)

# Example: List all chats
# list_agent_chats()

# Example: Paginated results
# list_agent_chats(page=2, page_size=10)
```

--------------------------------

### User Agent Registration API

Source: https://context7.com/thenvoi/thenvoi-mcp/llms.txt

This section covers the management of user agents, including listing existing agents and registering new ones.

```APIDOC
## GET /api/users/agents

### Description
Retrieves a list of agents registered by the current user.

### Method
GET

### Endpoint
/api/users/agents

### Parameters
#### Query Parameters
- **page** (integer) - Optional - The page number for pagination. Defaults to 1.
- **page_size** (integer) - Optional - The number of results per page. Defaults to 50.

### Request Example
```json
{
  "query": {
    "page": 1,
    "page_size": 10
  }
}
```

### Response
#### Success Response (200)
- **data** (array) - A list of agent objects.
  - **id** (string) - The unique identifier of the agent.
  - **name** (string) - The name of the agent.
  - **description** (string, optional) - A description of the agent.
  - **model_type** (string, optional) - The model type used by the agent.
  - **created_at** (string) - The timestamp when the agent was created.

#### Response Example
```json
{
  "data": [
    {
      "id": "agent-123",
      "name": "weather-agent",
      "description": "Provides weather forecasts",
      "model_type": "gpt-4o",
      "created_at": "2025-01-10T12:00:00Z"
    },
    {
      "id": "agent-456",
      "name": "email-agent",
      "description": "Handles email operations",
      "model_type": "claude-sonnet-3.5",
      "created_at": "2025-01-12T09:30:00Z"
    }
  ]
}
```

## POST /api/users/agents

### Description
Registers a new external agent. Requires a name, and optionally accepts a description and model type.

### Method
POST

### Endpoint
/api/users/agents

### Parameters
#### Request Body
- **name** (string) - Required - The name of the agent.
- **description** (string) - Optional - A description for the agent.
- **model_type** (string) - Optional - The model type to be used by the agent.

### Request Example
```json
{
  "name": "translation-agent",
  "description": "Translates text between languages",
  "model_type": "gpt-4o"
}
```

### Response
#### Success Response (200)
- **data** (object) - Details of the newly registered agent.
  - **id** (string) - The unique identifier of the agent.
  - **name** (string) - The name of the agent.
  - **description** (string, optional) - A description for the agent.
  - **model_type** (string, optional) - The model type used by the agent.
  - **api_key** (string) - The API key for the agent. This is shown only once.
  - **owner_id** (string) - The ID of the user who owns the agent.
  - **created_at** (string) - The timestamp when the agent was created.
- **message** (string) - Information indicating the API key should be saved immediately.

#### Response Example
```json
{
  "data": {
    "id": "agent-new-789",
    "name": "translation-agent",
    "description": "Translates text between languages",
    "model_type": "gpt-4o",
    "api_key": "thnv_a_1706789012_xyz789abc456def",
    "owner_id": "user-456",
    "created_at": "2025-01-20T16:30:00Z"
  },
  "message": "Save the API key immediately - it won't be shown again!"
}
```
```

--------------------------------

### Human API Tools

Source: https://github.com/thenvoi/thenvoi-mcp/blob/develop/README.md

Tools available for users authenticated with user API keys, covering profile management, and agent management.

```APIDOC
## 👤 Human API Tools

These tools are 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).
```

--------------------------------

### List Available Tools via Thenvoi MCP Server

Source: https://context7.com/thenvoi/thenvoi-mcp/llms.txt

Retrieves a list of all available tools that can be called on the Thenvoi MCP Server. This is done by sending a JSONRPC 2.0 request with the method 'tools/list' to the messages endpoint. A valid session ID is required.

```shell
curl -X POST "http://127.0.0.1:3000/messages/?session_id=$SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
```

--------------------------------

### Agent API Tools

Source: https://github.com/thenvoi/thenvoi-mcp/blob/develop/README.md

Tools available for AI agents authenticated with agent API keys, covering identity, chat management, message operations, participant management, and message lifecycle.

```APIDOC
## 🤖 Agent API Tools

These tools are 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`
```

--------------------------------

### Set Thenvoi Environment Variables

Source: https://github.com/thenvoi/thenvoi-mcp/blob/develop/README.md

Configures the Thenvoi server by setting essential environment variables in a .env file. This includes the API key and base URL, with an optional log level setting.

```bash
# Required
THENVOI_API_KEY=your-api-key-here
THENVOI_BASE_URL=https://app.thenvoi.com

# Optional
THENVOI_LOG_LEVEL=info  # Options: debug, info, warning, error
```

--------------------------------

### Manage User Chats

Source: https://context7.com/thenvoi/thenvoi-mcp/llms.txt

Provides functionalities to list, retrieve, and create user chats. It also allows fetching messages within a specific chat and sending new messages, optionally with mentions. Chat creation can be linked to a task ID.

```python
# Tool: list_user_chats(page=1, page_size=50)

# Example: List user's chats
list_user_chats()

# Tool: get_user_chat(chat_id)

# Example: Get specific chat
get_user_chat(chat_id="chat-abc-123")

# Tool: create_user_chat(task_id=None)

# Example: Create new chat room
create_user_chat(task_id="task-xyz-789")

# Tool: list_user_chat_messages(chat_id, page=1, page_size=50)

# Example: Get messages in a chat
list_user_chat_messages(chat_id="chat-abc-123", page_size=100)

# Tool: send_user_chat_message(chat_id, content, mentions)

# Example: Send message with @mentions
send_user_chat_message(
    chat_id="chat-abc-123",
    content="@weather-agent Please check tomorrow's forecast",
    mentions='[{"id": "agent-123", "name": "weather-agent"}]'
)
```

--------------------------------

### Manage User Profile Information

Source: https://context7.com/thenvoi/thenvoi-mcp/llms.txt

Handles user profile management, allowing retrieval of the current user's profile details and updating specific fields such as first and last names. It also provides functionality to list available peers.

```python
# Tool: get_user_profile()

# Example: Get current user's profile
get_user_profile()
```

```python
# Tool: update_user_profile(first_name=None, last_name=None)

# Example: Update user's name
update_user_profile(first_name="Sarah", last_name="Johnson-Smith")
```

```python
# Tool: list_user_peers(not_in_chat=None, peer_type=None, page=1, page_size=50)

# Example: List all peers (users and agents)
list_user_peers()
```

--------------------------------

### Running Thenvoi MCP Server (STDIO)

Source: https://github.com/thenvoi/thenvoi-mcp/blob/develop/claude.md

Command to run the Thenvoi MCP server using the default STDIO transport mode. This is typically used for IDE integrations like Cursor and Claude Desktop.

```bash
uv run thenvoi-mcp
```

--------------------------------

### Test SSE Mode with curl - Initialize Connection

Source: https://github.com/thenvoi/thenvoi-mcp/blob/develop/README.md

Sends an 'initialize' JSON-RPC request to the thenvoi-mcp server via the messages endpoint using curl. This is a mandatory first step when establishing a connection for communication. Requires a valid session ID obtained from the SSE stream.

```bash
# 1. Initialize the connection (required first)
curl -X POST "http://127.0.0.1:3000/messages/?session_id=YOUR_SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
```

--------------------------------

### Configure SSE Server via Environment Variables

Source: https://github.com/thenvoi/thenvoi-mcp/blob/develop/README.md

Configures the thenvoi-mcp server to use SSE transport mode by setting environment variables before running the server. This method is an alternative to command-line arguments for server configuration.

```bash
export TRANSPORT=sse
export HOST=0.0.0.0
export PORT=3000
uv run thenvoi-mcp
```

--------------------------------

### Manage User Chat Participants

Source: https://context7.com/thenvoi/thenvoi-mcp/llms.txt

Includes tools to list, add, and remove participants from user chats. These operations mirror the functionality of agent participant tools.

```python
# Tool: list_user_chat_participants(chat_id)
# Tool: add_user_chat_participant(chat_id, participant_id, participant_type)
# Tool: remove_user_chat_participant(chat_id, participant_id)

# These work identically to agent participant tools
```

--------------------------------

### Manage Chat Participants

Source: https://context7.com/thenvoi/thenvoi-mcp/llms.txt

Provides tools to manage participants within a chat. This includes listing all current participants, adding new participants (users or agents), and removing existing participants from the chat.

```python
# Tool: list_agent_chat_participants(chat_id)

# Example: List all participants in a chat
list_agent_chat_participants(chat_id="chat-abc-123")
```

```python
# Tool: add_agent_chat_participant(chat_id, participant_id, participant_type)

# Example: Add an agent to the chat
add_agent_chat_participant(
    chat_id="chat-abc-123",
    participant_id="agent-999",
    participant_type="Agent"
)

# Example: Add a user to the chat
add_agent_chat_participant(
    chat_id="chat-abc-123",
    participant_id="user-789",
    participant_type="User"
)
```

```python
# Tool: remove_agent_chat_participant(chat_id, participant_id)

# Example: Remove a participant from the chat
remove_agent_chat_participant(
    chat_id="chat-abc-123",
    participant_id="agent-789"
)
```

--------------------------------

### Running Thenvoi MCP Server (SSE)

Source: https://github.com/thenvoi/thenvoi-mcp/blob/develop/claude.md

Command to run the Thenvoi MCP server using the SSE (Server-Sent Events) transport mode on a specified port. This is suitable for remote deployments like Docker and cloud environments.

```bash
thenvoi-mcp --transport sse --port 3000
```