npm package: @signflow/mcp-server
Description: MCP server for SignFlow CRM -- AI-native access to clients, proposals, invoices, payments, and more
Latest version: 1.3.1

# SignFlow MCP Server

Model Context Protocol (MCP) server that gives AI assistants full access to your SignFlow CRM. Works with Claude Desktop, Claude Code, Cursor, and any MCP-compatible client.

## Quick Start

### 1. Create an API Key

Go to **Settings > API Keys** in your SignFlow dashboard and create a key with the permission level you need (see [Permission Levels](#permission-levels)).

### 2. Configure Your AI Client

**Claude Desktop** -- add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "signflow": {
      "command": "npx",
      "args": ["-y", "@signflow/mcp-server"],
      "env": {
        "SIGNFLOW_API_KEY": "sf_live_...",
        "SIGNFLOW_API_URL": "https://app.signflow.pro"
      }
    }
  }
}
```

On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
On Windows: `%APPDATA%\Claude\claude_desktop_config.json`

**Claude Code** -- add to `.claude/settings.json`:

```json
{
  "mcpServers": {
    "signflow": {
      "command": "npx",
      "args": ["-y", "@signflow/mcp-server"],
      "env": {
        "SIGNFLOW_API_KEY": "sf_live_...",
        "SIGNFLOW_API_URL": "https://app.signflow.pro"
      }
    }
  }
}
```

**Cursor** -- add to MCP Servers settings:

```json
{
  "mcpServers": {
    "signflow": {
      "command": "npx",
      "args": ["-y", "@signflow/mcp-server"],
      "env": {
        "SIGNFLOW_API_KEY": "sf_live_...",
        "SIGNFLOW_API_URL": "https://app.signflow.pro"
      }
    }
  }
}
```

### Manual Install

If you prefer a global install instead of `npx`:

```bash
npm install -g @signflow/mcp-server
signflow-mcp  # uses SIGNFLOW_API_KEY and SIGNFLOW_API_URL from environment
```

## Chat Mode (Interactive REPL)

Talk to your CRM directly from the terminal. Supports **Anthropic**, **OpenAI**, and **Google** models.

**Anthropic (Claude):**

```bash
ANTHROPIC_API_KEY=sk-ant-... SIGNFLOW_API_KEY=sf_live_... npx -y @signflow/mcp-server chat
```

**OpenAI (GPT-4o):**

```bash
OPENAI_API_KEY=sk-... SIGNFLOW_API_KEY=sf_live_... npx -y @signflow/mcp-server chat
```

**Google (Gemini):**

```bash
GOOGLE_GENERATIVE_AI_API_KEY=... SIGNFLOW_API_KEY=sf_live_... npx -y @signflow/mcp-server chat
```

The provider is auto-detected from whichever API key is set. Override with `SIGNFLOW_CHAT_PROVIDER` and `SIGNFLOW_MODEL`.

Commands: `/help`, `/clear`, `/exit`

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `SIGNFLOW_API_KEY` | Yes | API key from Settings > API Keys |
| `SIGNFLOW_API_URL` | Yes | Base URL of your SignFlow instance |
| `ANTHROPIC_API_KEY` | Chat mode | Anthropic API key (auto-selects Claude) |
| `OPENAI_API_KEY` | Chat mode | OpenAI API key (auto-selects GPT-4o) |
| `GOOGLE_GENERATIVE_AI_API_KEY` | Chat mode | Google AI API key (auto-selects Gemini) |
| `SIGNFLOW_CHAT_PROVIDER` | No | Force provider: `anthropic`, `openai`, or `google` |
| `SIGNFLOW_MODEL` | No | Override model ID (default varies by provider) |

## AI Workflow

The MCP server provides **conversational workflow guides** that teach any AI client the step-by-step process for creating professional documents and managing operations. Start with these:

1. **`get_system_context`** -- loads org branding, product catalog, and available workflows
2. **`get_proposal_guide`** -- 10-step conversational workflow for creating proposals
3. **`get_sow_guide`** -- 11-step conversational workflow for creating SOWs
4. **`get_invoice_guide`** -- 7-step conversational workflow for creating invoices
5. **`get_dev_hub_guide`** -- workflow for managing dev projects, milestones, tasks, and time billing
6. **`get_va_hub_guide`** -- workflow for VA operations: placements, time tracking, PTO, payroll

### Typical Flow: Proposal Creation

```
1. AI calls get_system_context() -> learns org branding, products, defaults
2. AI calls get_proposal_guide() -> gets step-by-step script
3. AI follows the guide, asking user each question in order:
   - Who is this for? -> search/create client
   - What services? -> select from catalog or add custom
   - Contract terms, payment terms, signing type...
   - Document content sections (intro, scope, timeline, terms...)
4. AI calls create_proposal() with sections -> server assembles branded HTML
5. AI calls send_proposal() -> confirm_action() -> client gets BoldSign email
```

### Typical Flow: VA Payroll

```
1. AI calls get_va_hub_guide() -> learns the payroll workflow
2. AI calls generate_va_payroll({ periodStart, periodEnd }) -> computes payouts
3. AI calls get_va_payroll({ payrollId }) -> reviews per-VA breakdown
4. AI calls approve_va_payroll({ payrollId }) -> locks the run
5. AI calls process_va_payouts({ payrollId }) -> confirm_action() -> sends money via Wise
6. AI calls generate_va_invoices({ payrollId }) -> confirm_action() -> creates client invoices
```

### Document Assembly (Sections vs Raw HTML)

**Sections (recommended):** Provide structured content sections -- the server handles branding, layout, pricing tables, and BoldSign signature tags automatically.

```
sections: [
  { type: "cover", title: "Website Redesign", subtitle: "For Acme Corp" },
  { type: "introduction", body: "<p>We are excited to propose...</p>" },
  { type: "scope", body: "<h3>Phase 1</h3><p>Discovery and wireframes...</p>" },
  { type: "pricing" },    // auto-generated from line items
  { type: "terms", body: "<p>Payment is due within 30 days...</p>" }
]
```

**Raw HTML (advanced):** Provide complete HTML via `htmlUpload` with your own BoldSign text-tags. The server validates that required signature tags are present.

## Tool Reference

### Guides (6 tools)

| Tool | Description |
|------|-------------|
| `get_system_context` | Load org branding, product catalog, subscription tier, and available workflows |
| `get_proposal_guide` | Get the 10-step conversational workflow for creating proposals |
| `get_sow_guide` | Get the 11-step conversational workflow for creating SOWs |
| `get_dev_hub_guide` | Get the Developer Hub workflow for projects, milestones, tasks, and billing |
| `get_va_hub_guide` | Get the VA Hub workflow for placements, time tracking, PTO, bonuses, and payroll |
| `get_invoice_guide` | Get the 7-step conversational workflow for creating invoices |

### Clients (11 tools)

| Tool | Description |
|------|-------------|
| `list_clients` | List all clients, optionally filter by status (lead, active, inactive) |
| `get_client` | Get detailed client info including contact, status, and financials |
| `create_client` | Create a new client or lead |
| `update_client` | Update a client's name, email, status, company, etc. |
| `delete_client` | Delete a client and all associated data (requires confirmation) |
| `list_leads` | List all leads, optionally filter by pipeline stage |
| `update_lead_stage` | Move a lead to a different stage in the pipeline |
| `log_lead_activity` | Log an activity for a client (call, email, meeting, note) |
| `list_client_notes` | List all notes for a client |
| `create_client_note` | Add a note to a client record |
| `get_client_stats` | Get client financial stats (revenue, invoices, proposals) |

### Proposals (7 tools)

| Tool | Description |
|------|-------------|
| `list_proposals` | List all proposals, optionally filter by status |
| `get_proposal` | Get proposal details including line items and status |
| `create_proposal` | Create a proposal with sections for server-side document assembly |
| `update_proposal` | Update a draft proposal's name, line items, or sections |
| `preview_proposal` | Get a dashboard preview link so the user can review before sending |
| `delete_proposal` | Delete a proposal (requires confirmation) |
| `send_proposal` | Send a proposal to the client via email (requires confirmation) |

### Invoices (7 tools)

| Tool | Description |
|------|-------------|
| `list_invoices` | List all invoices, optionally filter by status or client |
| `get_invoice` | Get invoice details including line items and payment status |
| `create_invoice` | Create a new invoice with line items |
| `update_invoice` | Update a draft invoice's due date, notes, or line items |
| `send_invoice` | Send an invoice to the client via email (requires confirmation) |
| `void_invoice` | Void an invoice, making it uncollectable (requires confirmation) |
| `charge_invoice` | Charge an invoice using saved payment method (admin key, requires confirmation) |

### Payments (3 tools)

| Tool | Description |
|------|-------------|
| `list_payments` | List all payments, optionally filter by status |
| `get_payment` | Get detailed payment information |
| `refund_payment` | Refund a completed payment (admin key, requires confirmation) |

### Products (4 tools)

| Tool | Description |
|------|-------------|
| `list_products` | List all products/services in the catalog |
| `create_product` | Create a new product or service |
| `update_product` | Update a product's name, price, or other details |
| `delete_product` | Delete a product from the catalog (requires confirmation) |

### Search (1 tool)

| Tool | Description |
|------|-------------|
| `search` | Search across clients, proposals, invoices, and products by keyword |

### Analytics (3 tools)

| Tool | Description |
|------|-------------|
| `get_analytics` | Dashboard analytics: revenue, client count, open invoices, overdue amounts |
| `get_pipeline` | Proposal pipeline: proposals by status, conversion rates, total value |
| `get_lead_stats` | Lead statistics: leads by stage, conversion rates, activity metrics |

### Agreements (3 tools)

| Tool | Description |
|------|-------------|
| `list_agreements` | List all signed agreements/contracts |
| `get_agreement` | Get detailed agreement information |
| `update_agreement` | Update an agreement's dates, end-of-term action, or notes |

### Recurring (6 tools)

| Tool | Description |
|------|-------------|
| `list_recurring` | List all recurring invoice schedules |
| `get_recurring` | Get detailed recurring schedule information |
| `create_recurring` | Create a new recurring invoice schedule for a client |
| `pause_recurring` | Pause an active recurring schedule |
| `resume_recurring` | Resume a paused recurring schedule |
| `cancel_recurring` | Cancel a recurring schedule permanently (requires confirmation) |

### SOWs (6 tools)

| Tool | Description |
|------|-------------|
| `list_sows` | List all Statements of Work |
| `get_sow` | Get detailed SOW information |
| `create_sow` | Create a SOW with sections for server-side document assembly |
| `update_sow` | Update a draft SOW's name, line items, or sections |
| `delete_sow` | Delete a SOW (requires confirmation) |
| `send_sow` | Send a SOW to the client for e-signature (admin key, requires confirmation) |

### Audit (1 tool)

| Tool | Description |
|------|-------------|
| `get_audit_log` | Get recent audit log entries showing actions taken in the system |

### Developer Hub (20 tools)

| Tool | Description |
|------|-------------|
| `list_dev_projects` | List dev projects, filter by status/client/search |
| `get_dev_project` | Get project details: billing, budget, progress |
| `create_dev_project` | Create project (optionally from SOW or template) |
| `update_dev_project` | Update project name, status, billing, budget, etc. |
| `delete_dev_project` | Delete project and all data (requires confirmation) |
| `list_dev_milestones` | List milestones for a project |
| `create_dev_milestone` | Create a milestone with amount and due date |
| `update_dev_milestone` | Update milestone status, amount, or due date |
| `delete_dev_milestone` | Delete a milestone (requires confirmation) |
| `request_milestone_approval` | Request client approval for a completed milestone |
| `invoice_dev_milestone` | Generate invoice from milestone amount (requires confirmation) |
| `list_dev_tasks` | List tasks, filter by status/milestone/priority |
| `create_dev_task` | Create a task with priority, estimate, and milestone link |
| `update_dev_task` | Update task status, priority, assignment, etc. |
| `delete_dev_task` | Delete a task (requires confirmation) |
| `list_dev_time_entries` | List time entries, filter by task/status/date/billable |
| `create_dev_time_entry` | Log time against a project (optionally linked to task) |
| `invoice_dev_time_entries` | Generate invoice from approved time entries (requires confirmation) |
| `get_dev_analytics` | Dev hub analytics: projects, tasks, hours, budgets |
| `get_dev_estimates` | Estimate vs actual variance analysis for a project |

### VA Hub (29 tools)

| Tool | Description |
|------|-------------|
| `list_vas` | List virtual assistants, filter by status/search |
| `get_va` | Get VA details: contact, skills, rate, Wise status |
| `create_va` | Create a new virtual assistant |
| `update_va` | Update VA name, skills, rate, status, etc. |
| `delete_va` | Delete VA and all data (requires confirmation) |
| `list_va_placements` | List placements, filter by status/VA/client |
| `get_va_placement` | Get placement details: rates, billing, margin |
| `create_va_placement` | Assign VA to client with billing and pay schedule |
| `update_va_placement` | Update placement rates, status, or schedule |
| `delete_va_placement` | Delete a placement (requires confirmation) |
| `list_va_time_entries` | List VA time entries, filter by VA/placement/status/dates |
| `create_va_time_entry` | Log time for a VA on a placement |
| `approve_va_time_entries` | Bulk approve pending time entries |
| `reject_va_time_entries` | Bulk reject pending time entries |
| `get_va_time_summary` | Aggregated time summary with cost/billing/margin |
| `list_va_pto` | List PTO requests, filter by VA/status |
| `create_va_pto` | Create a PTO request (vacation, sick, personal) |
| `approve_va_pto` | Approve a PTO request |
| `reject_va_pto` | Reject a PTO request |
| `list_va_bonuses` | List bonuses, filter by VA/status |
| `create_va_bonus` | Create a bonus (tenant or client initiated) |
| `approve_va_bonus` | Approve a pending bonus |
| `list_va_payroll` | List payroll runs, filter by status |
| `get_va_payroll` | Get payroll details with per-VA payout items |
| `generate_va_payroll` | Generate payroll for a date range |
| `approve_va_payroll` | Approve a payroll run for processing |
| `process_va_payouts` | Send money to VAs via Wise (DANGEROUS, requires confirmation) |
| `generate_va_invoices` | Generate client invoices from payroll (requires confirmation) |
| `get_va_analytics` | VA hub analytics: VAs, placements, hours, bonuses, payroll |

### System (1 tool)

| Tool | Description |
|------|-------------|
| `confirm_action` | Execute a previously prepared dangerous operation using its confirmation token |

**Total: 108 tools**

## Confirmation Pattern

Dangerous operations (send, charge, refund, delete, payouts) use a two-step confirmation flow to prevent accidental execution:

1. Call the tool (e.g. `send_invoice`) -- returns a confirmation token and description of what will happen
2. Call `confirm_action` with the token to execute

Tokens expire after **2 minutes**. If you don't confirm, nothing happens.

**Example flow:**

```
User: "Send invoice INV-042 to the client"

AI calls send_invoice({ invoiceId: "..." })
-> "Ready to send invoice INV-042 ($1,500.00) to Acme Corp (john@acme.com).
    To proceed, call confirm_action with token: "abc123..."

AI calls confirm_action({ token: "abc123..." })
-> "Action confirmed and executed successfully."
```

## Permission Levels

The API key's permission level controls which tools are available:

| Permission | GET (list/get) | POST/PATCH (create/update) | Dangerous (send/charge/refund/delete) |
|------------|----------------|----------------------------|---------------------------------------|
| **read** | Yes | No | No |
| **write** | Yes | Yes | No |
| **admin** | Yes | Yes | Yes |

A `read` key can list clients, view invoices, check analytics, etc. A `write` key can also create clients, proposals, and invoices. Only `admin` keys can send proposals, charge invoices, refund payments, or delete records.

## Error Handling

| Status | Meaning | Common Cause |
|--------|---------|--------------|
| 401 | Unauthorized | Invalid, expired, or revoked API key |
| 403 | Forbidden | Insufficient permission level or charge limit exceeded |
| 429 | Rate limited | More than 100 requests/minute from this key |
| 404 | Not found | Invalid entity ID |
| 500 | Server error | Unexpected error -- check Sentry |

All errors are returned as clear, AI-friendly text messages (not raw JSON).