Content
# @trigv/mcp
MCP (Model Context Protocol) server for [Trigv](https://trigv.com). Lets AI clients in Cursor, Claude Code, and VS Code send notification events to your Trigv workspace.
## What Trigv is
Trigv delivers developer notifications to your team's devices. Your backend (or AI agent) sends lightweight JSON events; Trigv queues push delivery. Notification title and body are not stored on Trigv servers — metadata only.
## Installation
```bash
npm install @trigv/mcp
```
Or run directly with `npx`:
```bash
npx @trigv/mcp
```
## Quick start
1. Create a workspace API key at [app.trigv.com](https://app.trigv.com).
2. Set `TRIGV_API_KEY` in your MCP client config (see below).
3. Ask your AI assistant to send an event using the `send_event` tool.
Example tool call:
```json
{
"channel": "deploys",
"title": "Production deploy complete",
"description": "Build #42 succeeded in 38s (commit abc1234)",
"level": "success",
"event_type": "deploy.completed",
"idempotency_key": "deploy-prod-42"
}
```
## Authentication
| Variable | Required | Default | Description |
|----------|:--------:|---------|-------------|
| `TRIGV_API_KEY` | Yes | — | Workspace ingest API key (`trgv_…`) |
| `TRIGV_BASE_URL` | No | `https://api.trigv.com/api` | Override for local dev (`http://trigv-platform.test/api`) |
The API key is sent as `Authorization: Bearer` and is **never** included in tool responses or error messages.
## Tool: `send_event`
Sends a notification event via `POST /v1/events`.
| Field | Required | Description |
|-------|:--------:|-------------|
| `channel` | Yes | Channel slug (e.g. `general`, `deploys`) |
| `title` | Yes | Notification title |
| `description` | No | Body text |
| `image_url` | No | HTTPS image URL (not stored server-side) |
| `url` | No | Destination URL for the notification (max 2048 characters; not stored server-side) |
| `level` | No | `info`, `success`, `warning`, `error` (default: `info`) |
| `delivery_urgency` | No | `standard` or `time_sensitive` (default: `standard`) |
| `event_type` | No | Free-form label (e.g. `deploy.completed`) |
| `idempotency_key` | No | Dedup key per workspace |
**Success response** includes `event.public_id`, `duplicate` (true when HTTP 200), and other event metadata.
**Error response** includes `error.type`, `error.message`, and optional `error.errors` for validation failures.
## Levels
- `info` — general information (default)
- `success` — completed successfully
- `warning` — attention needed
- `error` — failure or alert
## Delivery urgency
- `standard` — normal notifications (default)
- `time_sensitive` — iOS Time Sensitive delivery
## Idempotency
When you set `idempotency_key`, retries with the same key return the existing event (`duplicate: true`) without billing again.
## Error handling
| Error type | When |
|------------|------|
| `ConfigurationError` | Missing `TRIGV_API_KEY` |
| `ValidationError` | Invalid input (client or server 422) |
| `AuthenticationError` | HTTP 401 |
| `AuthorizationError` | HTTP 403 |
| `NotFoundError` | Channel not found (HTTP 404) |
| `RateLimitError` | HTTP 429 |
| `NetworkError` / `TimeoutError` | Connection issues |
## MCP client configuration
### Cursor
Add to `.cursor/mcp.json` in your project (or global Cursor MCP settings):
```json
{
"mcpServers": {
"trigv": {
"command": "npx",
"args": ["-y", "@trigv/mcp"],
"env": {
"TRIGV_API_KEY": "trgv_your_api_key_here"
}
}
}
}
```
For a local checkout during development:
```json
{
"mcpServers": {
"trigv": {
"command": "node",
"args": ["/path/to/trigv-mcp/dist/index.js"],
"env": {
"TRIGV_API_KEY": "trgv_your_api_key_here",
"TRIGV_BASE_URL": "http://trigv-platform.test/api"
}
}
}
}
```
### Claude Code
Add to `~/.claude/settings.json` or project `.claude/settings.json`:
```json
{
"mcpServers": {
"trigv": {
"command": "npx",
"args": ["-y", "@trigv/mcp"],
"env": {
"TRIGV_API_KEY": "trgv_your_api_key_here"
}
}
}
}
```
### VS Code
Add to `.vscode/mcp.json` in your workspace:
```json
{
"servers": {
"trigv": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@trigv/mcp"],
"env": {
"TRIGV_API_KEY": "trgv_your_api_key_here"
}
}
}
}
```
## Examples
### Basic event
```json
{ "channel": "general", "title": "Hello from MCP" }
```
### Deploy completed (canonical)
```json
{
"channel": "deploys",
"title": "Production deploy complete",
"description": "Build #42 succeeded in 38s (commit abc1234)",
"level": "success",
"delivery_urgency": "standard",
"event_type": "deploy.completed",
"idempotency_key": "deploy-prod-42"
}
```
### Cron job failed
```json
{
"channel": "alerts",
"title": "Nightly backup failed",
"description": "Exit code 1 after 12 minutes",
"level": "error",
"event_type": "cron.failed"
}
```
## Development
```bash
git clone https://github.com/Trigv/trigv-mcp.git
cd trigv-mcp
npm install
npm run build
npm test
```
Run locally:
```bash
TRIGV_API_KEY=trgv_… npm run dev
```
## Testing
```bash
npm test
```
Tests use mocked HTTP — no live API key required in CI.
## Contributing
See the [Trigv SDK programme](https://github.com/Trigv/trigv-node) for API contract and conformance requirements.
## Licence
MIT — see [LICENSE](LICENSE).
