@flowsight/mcp-server

MCP (Model Context Protocol) server for FlowSight — expose payment observability tools to AI assistants like Claude, GPT, and any MCP-compatible client.

Quick Start

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):

{
  "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:

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

Custom Base URL

For self-hosted FlowSight or development:

{
  "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

# 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