npm package: @flowsight/mcp-server
Description: FlowSight MCP server — expose payment observability tools to AI assistants
Author: FlowSight
Latest version: 1.0.3

# @flowsight/mcp-server

MCP (Model Context Protocol) server for [FlowSight](https://flowsight.pro) — expose payment observability tools to AI assistants like Claude, GPT, and any MCP-compatible client.

## Quick Start

```bash
FLOWSIGHT_API_KEY=fs_live_... npx @flowsight/mcp-server
```

## Tools

The server exposes 4 tools:

| Tool | Description |
|------|-------------|
| `flowsight_send_event` | Send a payment event for tracking |
| `flowsight_query_events` | Query events with filters (processor, status, time range) |
| `flowsight_get_flow` | Get a complete payment flow by ID |
| `flowsight_list_processors` | List supported payment processors |

## Setup

### Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "flowsight": {
      "command": "npx",
      "args": ["@flowsight/mcp-server"],
      "env": {
        "FLOWSIGHT_API_KEY": "fs_live_your_api_key_here"
      }
    }
  }
}
```

Restart Claude Desktop. You'll see FlowSight tools available in the tools menu.

### OpenClaw / Other MCP Clients

Any MCP client that supports stdio transport can use this server:

```json
{
  "command": "npx",
  "args": ["@flowsight/mcp-server"],
  "env": {
    "FLOWSIGHT_API_KEY": "fs_live_..."
  }
}
```

### Custom Base URL

For self-hosted FlowSight or development:

```json
{
  "env": {
    "FLOWSIGHT_API_KEY": "fs_test_...",
    "FLOWSIGHT_BASE_URL": "http://localhost:8080"
  }
}
```

## Configuration

| Environment Variable | Required | Default | Description |
|---------------------|----------|---------|-------------|
| `FLOWSIGHT_API_KEY` | ✅ | — | Your FlowSight API key |
| `FLOWSIGHT_BASE_URL` | — | `https://ingest.flowsight.pro` | API base URL |
| `FLOWSIGHT_TIMEOUT_MS` | — | `30000` | Request timeout in ms |

## Tool Details

### flowsight_send_event

Send a payment lifecycle event.

**Parameters:**
- `event_type` (required) — `payment.started`, `payment.completed`, `payment.failed`, `payment.retried`, `refund.started`, `refund.completed`, `refund.failed`
- `flow_id` (required) — UUID grouping related events
- `transaction_id` (required) — Processor transaction ID
- `processor` (required) — `stripe`, `paypal`, `adyen`, `redsys`
- `amount` (required) — Amount in smallest currency unit (cents)
- `currency` (required) — ISO 4217 code (USD, EUR, GBP)
- `status` — `succeeded`, `failed`, `pending`, `cancelled`
- `latency_ms` — Processor response time
- `error_code` — Error code for failed payments
- `error_message` — Error message for failed payments
- `context` — Key-value metadata

### flowsight_query_events

Query events with optional filters.

**Parameters:**
- `processor` — Filter by processor
- `status` — Filter by status
- `event_type` — Filter by event type
- `from` / `to` — ISO 8601 time range
- `page` / `limit` — Pagination (default: page 1, 20 per page)

### flowsight_get_flow

Get all events in a payment flow.

**Parameters:**
- `flow_id` (required) — The flow UUID to look up

### flowsight_list_processors

List supported payment processors and their webhook configurations. No parameters.

## Example Conversations

> "Show me all failed payments in the last hour"

The AI will call `flowsight_query_events` with `status: "failed"` and appropriate time range.

> "What happened with flow abc-123?"

The AI will call `flowsight_get_flow` with `flow_id: "abc-123"` and display the payment timeline.

> "Track a $49.99 Stripe payment"

The AI will call `flowsight_send_event` with the payment details.

## Development

```bash
# Install dependencies
npm install

# Run in development mode
FLOWSIGHT_API_KEY=fs_test_... npm run dev

# Build
npm run build

# Run tests
npm test

# Type check
npm run typecheck
```

## License

MIT — [FlowSight](https://flowsight.pro)