# SerenAI MCP Server

> Model Context Protocol server for SerenAI - Pay Per Call Agentic Commerce

The SerenAI MCP server enables AI assistants to manage serverless Postgres databases and query the agent marketplace with SerenBucks micropayments.

## Installation

### Claude Desktop (stdio mode)

Add to `~/.config/claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "seren": {
      "command": "seren-mcp",
      "args": ["start"],
      "env": {
        "API_KEY": "seren_live_xxxxx"
      }
    }
  }
}
```

### HTTP Mode (with OAuth)

```bash
seren-mcp start:oauth --port 3000
```

## Available Tools

### Branches

#### `list_branches`

List branches for a project

**Parameters:**
- `project_id`: string (required)

#### `create_branch`

Create a new branch in a project

**Parameters:**
- `project_id`: string (required)
- `name`: string (required)
- `parent_branch_id`: string (optional)

#### `describe_branch`

Get details about a specific branch

**Parameters:**
- `project_id`: string (required)
- `branch_id`: string (required)

#### `delete_branch`

Delete a branch

**Parameters:**
- `project_id`: string (required)
- `branch_id`: string (required)

### Endpoints

#### `list_endpoints`

List all endpoints for a branch

**Parameters:**
- `project_id`: string (required)
- `branch_id`: string (required)

#### `create_endpoint`

Create a new endpoint for a branch

**Parameters:**
- `project_id`: string (required)
- `branch_id`: string (required)
- `autoscaling_min`: integer (optional)
- `autoscaling_max`: integer (optional)

#### `start_endpoint`

Start a suspended endpoint

**Parameters:**
- `project_id`: string (required)
- `branch_id`: string (required)
- `endpoint_id`: string (required)

#### `suspend_endpoint`

Suspend an endpoint

**Parameters:**
- `project_id`: string (required)
- `branch_id`: string (required)
- `endpoint_id`: string (required)

### Marketplace

#### `list_agent_publishers`

List all active publishers in the agent marketplace

**Parameters:**
- `search`: string (optional)
- `is_verified`: boolean (optional)
- `limit`: integer (optional)
- `offset`: integer (optional)

#### `get_agent_publisher`

Get details about a specific publisher including pricing info

**Parameters:**
- `slug`: string (required)

#### `execute_paid_query`

Execute a paid SQL query against a publisher database

**Parameters:**
- `publisher`: string (required) - Publisher slug or UUID
- `query`: string (required)
- `database`: string (optional)
- `confirm`: boolean (optional)

#### `execute_paid_api`

Execute a paid API request against a publisher endpoint

**Parameters:**
- `publisher`: string (required)
- `method`: string (optional)
- `path`: string (optional)
- `body`: object (optional)
- `confirm`: boolean (optional)

#### `estimate_query_cost`

Estimate the cost of a SQL query without executing it

**Parameters:**
- `publisher`: string (required)
- `query`: string (required)

### Payments

#### `get_prepaid_balance`

Get your SerenBucks balance

#### `get_transaction_history`

Get transaction history (deposits, charges, refunds)

**Parameters:**
- `limit`: integer (optional)
- `offset`: integer (optional)

#### `create_prepaid_deposit`

Deposit SerenBucks with a credit card via Stripe

**Parameters:**
- `amount_usd`: number (required) - Amount in USD (minimum $5.00)

### Projects

#### `list_projects`

List all Seren projects accessible to the authenticated user

#### `create_project`

Create a new Seren project

**Parameters:**
- `name`: string (required) - Project name
- `region`: string (required) - Deployment region

#### `describe_project`

Get detailed information about a specific project

**Parameters:**
- `project_id`: string (required)

#### `delete_project`

Delete a Seren project

**Parameters:**
- `project_id`: string (required)

### SQL

#### `run_sql`

Execute a SQL query against a database

**Parameters:**
- `project_id`: string (required)
- `branch_id`: string (required)
- `database`: string (required)
- `query`: string (required)

#### `run_sql_transaction`

Execute multiple SQL statements in a single transaction

**Parameters:**
- `project_id`: string (required)
- `branch_id`: string (required)
- `database`: string (required)
- `queries`: array (required)

#### `explain_sql_statement`

Explain a SQL statement (FORMAT JSON)

**Parameters:**
- `project_id`: string (required)
- `branch_id`: string (required)
- `database`: string (required)
- `query`: string (required)

### Schema

#### `list_databases`

List all databases in a branch

**Parameters:**
- `project_id`: string (required)
- `branch_id`: string (required)

#### `get_database_tables`

List tables in a database schema

**Parameters:**
- `project_id`: string (required)
- `branch_id`: string (required)
- `database`: string (required)
- `schema`: string (optional)

#### `describe_table_schema`

Get schema information for a table

**Parameters:**
- `project_id`: string (required)
- `branch_id`: string (required)
- `database`: string (required)
- `table_name`: string (required)
- `schema`: string (optional)

## Authentication

The MCP server supports three authentication modes:

1. **API Key (stdio)**: Set `API_KEY` environment variable
2. **Bearer Token (HTTP)**: Set `AUTH_TOKEN` for simple auth
3. **OAuth 2.1 (HTTP)**: Full OAuth flow with PKCE

## Read-Only Mode

Set `READ_ONLY=true` to block write operations (useful for shared deployments).

## More Information

- [Full API Documentation](https://docs.serendb.com/)
- [Tool Schemas](/mcp/tools.json)
- [GitHub Repository](https://github.com/serenorg/seren)