# Marvenn MCP Server

The **Marvenn MCP Server** exposes the [Marvenn](https://marvenn.ai) AI-powered outreach and CRM platform to any MCP-compatible client (Claude Desktop, Continue, Cursor, etc.).

Connect your AI assistant to Marvenn and let it list campaigns, inspect leads, manage pending agent actions, and more — all through natural language.

---

## Authentication

API key is optional for discovery (`tools/list`, `prompts/list`, `resources/list`).
API key is required for executing tools (`tools/call`).
Pass your key as a Bearer token: `Authorization: Bearer <your-marvenn-api-key>`

API keys are scoped. The scope granted to your key determines which tools are available:

| Scope | Description |
|-------|-------------|
| `read` | Read-only access to campaigns, leads, actions, and agents |
| `write` | Everything in `read`, plus creating campaigns and approving/rejecting actions |
| `admin` | Everything in `write`, plus user management and credit operations (also requires your Marvenn account role to be `admin` or `super_admin`) |

Generate or manage your API keys from your account settings at [marvenn.ai](https://marvenn.ai).

---

## Transport

| Transport | URL | Status |
|-----------|-----|--------|
| Streamable HTTP (recommended) | `https://marvenn.ai/mcp` | **Working** |
| SSE | `https://marvenn.ai/mcp/sse` | **Working** |

---

## Quick Start

### Claude Desktop

Add the following to your `claude_desktop_config.json` (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "marvenn": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://marvenn.ai/mcp/sse",
        "--header",
        "Authorization: Bearer <your-marvenn-api-key>"
      ]
    }
  }
}
```

Restart Claude Desktop. You should see the Marvenn tools available in the tools panel.

### curl

Open the SSE stream in one terminal:

```bash
curl -N \
  -H "Authorization: Bearer <your-marvenn-api-key>" \
  https://marvenn.ai/mcp/sse
```

The server responds with an `endpoint` event that provides a session-specific message URL, for example:

```
event: endpoint
data: https://marvenn.ai/mcp/sse/message?sessionId=mcp_1234567890_abc12345
```

Send a JSON-RPC message to that endpoint in a second terminal:

```bash
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-marvenn-api-key>" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}' \
  "https://marvenn.ai/mcp/sse/message?sessionId=mcp_1234567890_abc12345"
```

The result is delivered back over the open SSE stream.

---

## Tools

### `list_campaigns` — Read scope

List all campaigns for the authenticated user. Returns campaign name, status, creation date, and basic stats.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string | No | Filter by status: `active`, `paused`, `completed`, `draft` |
| `limit` | number | No | Max results to return (default `20`, max `100`) |

---

### `get_campaign_stats` — Read scope

Get detailed analytics and performance stats for a specific campaign.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `campaign_id` | number | **Yes** | Numeric ID of the campaign |

---

### `create_campaign` — Write scope

Create a new outreach campaign.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | **Yes** | Campaign name (max 200 characters) |
| `type` | string | **Yes** | Campaign type: `email`, `phone`, `social`, `multi_channel` |
| `targetAudience` | string | No | Description of the target audience |
| `objective` | string | No | Campaign objective or goal |

---

### `list_leads` — Read scope

List leads in the CRM with optional filtering and pagination.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string | No | Filter by lead status: `new`, `contacted`, `qualified`, `converted`, `lost` |
| `search` | string | No | Search term matched against name, email, or company |
| `limit` | number | No | Max results per page (default `20`, max `100`) |
| `page` | number | No | Page number, 1-indexed (default `1`) |

---

### `list_pending_actions` — Read scope

List all pending actions awaiting your approval.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | number | No | Max results to return (default `20`) |

---

### `approve_action` — Write scope

Approve or reject a pending action that requires human authorization.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `action_id` | number | **Yes** | Numeric ID of the pending action |
| `decision` | string | **Yes** | `approve` or `reject` |
| `notes` | string | No | Optional notes or reason for the decision |

---

### `list_agents` — Read scope

List all AI agents for the authenticated user.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | number | No | Max results to return (default `20`) |

---

### `list_users` — Admin scope

List all users on the platform. Requires `admin` scope **and** an admin account role.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | number | No | Max results to return (default `50`, max `500`) |
| `subscriptionTier` | string | No | Filter by tier: `free`, `startup`, `team` |

---

### `manage_credits` — Admin scope

View or adjust the credit balance for any user. Requires `admin` scope **and** an admin account role.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `target_user_id` | string | **Yes** | ID of the user whose credits to manage |
| `action` | string | **Yes** | `get`, `add`, or `subtract` |
| `amount` | number | Required for `add`/`subtract` | Number of credits to add or subtract |
| `reason` | string | Required for `add`/`subtract` | Reason for the adjustment |

---

## Error Handling

All errors are returned as JSON-RPC error objects with the following codes:

| Code | Meaning |
|------|---------|
| `-32600` | Invalid JSON-RPC request |
| `-32601` | Method or tool not found |
| `-32602` | Invalid arguments |
| `-32603` | Internal server error |

Scope errors (e.g. calling `create_campaign` with a `read`-only key) are returned as a tool result with an `error` field in the response body, not as a JSON-RPC protocol error.

---

## Links

- Website: [https://marvenn.ai](https://marvenn.ai)
- MCP Protocol: [https://modelcontextprotocol.io](https://modelcontextprotocol.io)