MCP Server

Surflet provides a standard Model Context Protocol (MCP) server, enabling your AI clients (Claude Desktop, Claude Code, Cursor, VS Code, etc.) to publish interactive pages, check approval status, and append content blocks directly.

Installation

The MCP Server is included in the monorepo:

# Build the MCP Server
cd packages/@surflet/mcp-server
pnpm install && pnpm build

The built executable is located at packages/@surflet/mcp-server/dist/index.js.

Configure Your AI Client

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%/Claude/claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "surflet": {
      "command": "node",
      "args": ["/path/to/surflet/packages/@surflet/mcp-server/dist/index.js"],
      "env": {
        "SURFLET_API_KEY": "sk_live_...",
        "SURFLET_API_URL": "https://api.surflet.app"
      }
    }
  }
}

Claude Code

claude mcp add surflet node /path/to/surflet/packages/@surflet/mcp-server/dist/index.js \
  --env SURFLET_API_KEY=sk_live_... \
  --env SURFLET_API_URL=https://api.surflet.app

Cursor

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "surflet": {
      "command": "node",
      "args": ["/path/to/surflet/packages/@surflet/mcp-server/dist/index.js"],
      "env": {
        "SURFLET_API_KEY": "sk_live_...",
        "SURFLET_API_URL": "https://api.surflet.app"
      }
    }
  }
}

VS Code (Copilot)

Create .vscode/mcp.json in your project root:

{
  "servers": {
    "surflet": {
      "command": "node",
      "args": ["/path/to/surflet/packages/@surflet/mcp-server/dist/index.js"],
      "env": {
        "SURFLET_API_KEY": "sk_live_...",
        "SURFLET_API_URL": "https://api.surflet.app"
      }
    }
  }
}

Environment Variables

Variable	Description	Default
SURFLET_API_KEY	API Key (required)	None
SURFLET_API_URL	API base URL	http://localhost:3001

11 MCP Tools

The MCP Server registers 11 tools that AI clients can invoke as needed:

surflet_publish

Publish an interactive page. Supports both Markdown shorthand and full blocks structure.

Parameters:
  title (string, required) — page title
  summary (string) — brief summary
  page_type (enum) — briefing / approval / review / form / dashboard
  content (string) — Markdown content (shorthand mode, auto-creates a text block)
  blocks (array) — structured content blocks
  actions (array) — action buttons
  approval_chain (object) — approval chain configuration
  access (object) — access control
  notify (string) — notification shorthand, e.g. "slack:#channel"
  on_action (object) — callback configuration
  layout (array) — layout configuration
  priority (enum) — low / medium / high / critical
  tags (string[]) — tags

surflet_get_page

Retrieve the details and status of a published page.

Parameters:
  page_id (string, required) — page ID

surflet_get_approval_status

View the current progress of an approval chain.

Parameters:
  page_id (string, required) — page ID

surflet_execute_action

Execute an action on a page (approve, reject, etc.).

Parameters:
  page_id (string, required) — page ID
  action_id (string, required) — action ID
  actor_identity (string) — identity of the executor
  comment (string) — additional comment

surflet_add_comment

Add a comment to a page's comment thread.

Parameters:
  page_id (string, required) — page ID
  content (string, required) — comment content
  author_name (string) — author display name

surflet_list_inbox

List pending inbox items.

Parameters:
  status (string) — filter by status: unread / read / archived
  limit (number) — maximum number of results

surflet_revoke_page

Revoke / cancel a published page.

Parameters:
  page_id (string, required) — page ID

surflet_append_blocks

Append content blocks to an existing page (streaming / progressive updates). First use surflet_publish to create the page, then use this tool to progressively append analysis results.

Parameters:
  page_id (string, required) — page ID
  blocks (array, required) — blocks to append

surflet_get_analytics

Retrieve page view analytics (total views, unique visitors, daily trends).

Parameters:
  page_id (string, required) — page ID

surflet_publish_template

Publish a page from a preset template. 10 industry templates available — pass in variables to generate a complete page.

Parameters:
  template (string, required) — template name
  variables (object, required) — template variables

surflet_list_templates

List all available templates and their required variables. Use this tool before calling surflet_publish_template to review the required parameters.

Parameters: none

Usage Examples

Here are typical scenarios where an agent uses Surflet MCP tools during a conversation:

Scenario: Agent analyzes a refund request and publishes an approval page

User: Help me process a refund request from customer Alice for order #ORD-7891, $127.50, reason: product damaged.

Agent thinks: I need to create a refund approval page for the manager to review.

[Call surflet_publish_template]
template: "refund_approval"
variables: {
  "customer": "Alice Wang",
  "order_id": "#ORD-7891",
  "amount": 127.50,
  "reason": "Product arrived damaged",
  "risk_score": 15,
  "agent_recommendation": "Recommend full refund. Customer has a good history, first complaint."
}

→ Returns: { pageUrl: "https://hai.surf/p/pg_abc123", ... }

Agent: I've created the refund approval page: https://hai.surf/p/pg_abc123
The page includes customer details, a risk score (15%, low risk), and the approval workflow. The manager can approve or reject directly on the page.

Scenario: Progressive analysis report

User: Analyze last week's customer service data and generate a report.

[Call surflet_publish]
title: "CS Weekly Report — 2026-03-20"
page_type: "briefing"
blocks: [{ type: "callout", data: { content: "Analyzing data...", style: "info" } }]

→ Returns: { pageId: "pg_xyz", pageUrl: "..." }

Agent: Report page created, analyzing data...

[After analysis is complete, call surflet_append_blocks]
page_id: "pg_xyz"
blocks: [
  { type: "metric", data: { title: "Key Metrics", items: [...] } },
  { type: "chart", data: { title: "Ticket Trends", chart_type: "line", ... } },
  { type: "table", data: { title: "Top 10 Issues", ... } }
]

Agent: Analysis complete! The report has been updated: https://hai.surf/p/pg_xyz

Local Development

Run the MCP Server in development mode:

cd packages/@surflet/mcp-server
SURFLET_API_KEY=sk_test_surflet123 SURFLET_API_URL=http://localhost:3001 pnpm dev

The MCP Server uses the stdio transport protocol, communicating with AI clients through standard input/output.