# Thenvoi MCP Server
MCP (Model Context Protocol) server that connects AI assistants to the Thenvoi platform.
## Core Features
1. Connects AI assistants to Thenvoi's agent collaboration platform
2. Supports dual transport modes: STDIO (IDE integration) and SSE (remote deployments)
3. Conditional tool loading based on API key type (user vs agent)
## API Key Types
- `thnv_u_*` → User keys → Only human tools loaded
- `thnv_a_*` → Agent keys → Only agent tools loaded
- `thnv_*` → Legacy keys → All tools loaded
## Tool Template
```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"
```
## Repo-Specific Conventions
- Use the shared logger: `from thenvoi_mcp.shared import logger`
- All tools must use the `@mcp.tool()` decorator
- Tools must accept `ctx: AppContextType` as the first parameter
- Use `get_app_context(ctx).client` to access the Thenvoi API client
- Tools must return strings (success messages or JSON)
## Commands
```bash
# Install dependencies
uv sync
# Run the server
uv run thenvoi-mcp
# Run unit tests
uv run pytest tests/ --ignore=tests/integration/ -v
# Lint and format
uv run pre-commit run --all-files
```
## Transport Modes
- **STDIO** (default): `thenvoi-mcp` - For Cursor, Claude Desktop
- **SSE**: `thenvoi-mcp --transport sse --port 3000` - For Docker, cloud deployments
## Environment Variables
- `THENVOI_API_KEY`: Required API key
- `THENVOI_BASE_URL`: API base URL (default: https://app.thenvoi.com)
- `TRANSPORT`: stdio or sse (default: stdio)
- `HOST`: SSE host (default: 127.0.0.1)
- `PORT`: SSE port (default: 8000)
## Git Workflow
- Default branch: `develop` (PRs target here)
