Surfit for Claude Desktop, Claude Code, and any MCP client

How it works

Surfit ships an MCP (Model Context Protocol) server at https://mcp.surfit.ai. Any MCP-compatible client — Claude Desktop, Claude Code, Cursor, Cline, and others — can connect to it with a single config entry.

Once connected, the client sees seven Surfit tools: surfit_x_post, surfit_slack_send, surfit_github_action, surfit_aws_action, surfit_gmail_send, surfit_notion_action, surfit_outlook_send. The agent calls these instead of hitting the underlying APIs directly. Each call is scored by Surfit's Wave engine in real time. Low-risk actions execute automatically; high-risk actions are held for human approval.

Get an API key

1. Sign in to your Surfit admin dashboard at app.surfit.ai.
2. Generate an API key under Admin → API Keys. The key starts with sk_surfit_.
3. The key is shown once. Copy it somewhere safe.

If you don't have access to the admin dashboard yet, contact hello@surfit.ai and we'll get you set up.

Claude Desktop

Edit your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the surfit server to the mcpServers object:

Copy{
  "mcpServers": {
    "surfit": {
      "url": "https://mcp.surfit.ai/mcp",
      "headers": {
        "Authorization": "Bearer sk_surfit_YOUR_KEY_HERE"
      }
    }
  }
}

Save and restart Claude Desktop. The seven Surfit tools will appear in your tool list. Try a prompt like "Post a tweet announcing our new feature" — Claude will call surfit_x_post, Surfit will evaluate the proposed tweet, and either auto-publish or hold it for your approval.

Claude Code

From any project directory, run:

Copyclaude mcp add surfit \
  --transport http \
  --header "Authorization: Bearer sk_surfit_YOUR_KEY_HERE" \
  https://mcp.surfit.ai/mcp

Or edit your ~/.claude.json directly:

Copy{
  "mcpServers": {
    "surfit": {
      "type": "http",
      "url": "https://mcp.surfit.ai/mcp",
      "headers": {
        "Authorization": "Bearer sk_surfit_YOUR_KEY_HERE"
      }
    }
  }
}

Restart Claude Code. Verify the connection with /mcp — you should see surfit listed with seven tools.

Cursor

Open Cursor settings, navigate to Features → MCP, click Add new MCP server, and use the same config:

Copy{
  "mcpServers": {
    "surfit": {
      "url": "https://mcp.surfit.ai/mcp",
      "headers": {
        "Authorization": "Bearer sk_surfit_YOUR_KEY_HERE"
      }
    }
  }
}

Cline (VS Code)

Open Cline's MCP settings, click Configure MCP Servers, and add:

Copy{
  "mcpServers": {
    "surfit": {
      "transportType": "http",
      "url": "https://mcp.surfit.ai/mcp",
      "headers": {
        "Authorization": "Bearer sk_surfit_YOUR_KEY_HERE"
      }
    }
  }
}

Available tools

The Surfit MCP server exposes seven tools, one per supported system:

Reading Surfit responses

Every tool returns a structured message describing what happened. Examples:

CopyAction executed. Surfit Wave 2. ID: x-12790e2f. (x / post_tweet)

Wave 2 means the action passed risk evaluation and was logged + executed. The ID is your reference for the audit log.

CopyAction held for human approval. Surfit Wave 5. ID: gmail-21d6667b.
Approver will review and either approve or reject. You will not see the action complete until it is approved.

Wave 5 means the action was risky enough to require explicit human approval. Approvers receive the action in the Surfit dashboard and can approve, reject, or modify it. The agent receives a clear signal that its action is pending — it knows not to retry or proceed.

Wave score reference

• Wave 1 (auto): Routine, fully reversible. Executes without logging beyond standard audit.
• Wave 2 (log): Standard risk. Executes and is logged with full context.
• Wave 3 (check): Elevated risk. Executes, but flagged for proactive review.
• Wave 4 (approve): Sensitive. Held for human approval before execution.
• Wave 5 (approve): Critical. Held with mandatory secondary review.

Scoring incorporates the agent's history, the destination system, the action type, content sensitivity, and any cross-system patterns Surfit detects in real time.

Troubleshooting

Surfit tools don't appear after restart

Check the client's MCP logs for connection errors. The most common causes: (1) the API key is invalid or revoked, (2) the URL is missing the /mcp suffix, (3) the JSON config has a syntax error from a missing comma or trailing comma.

"Authorization error" in tool call response

The bearer token is missing or wrong. Verify the key in your config matches the key shown in your Surfit admin dashboard. Keys can be revoked and re-issued at any time.

Actions are being held when they shouldn't be

Tune your Wave thresholds in the Surfit admin dashboard. Each customer has independent threshold settings. You can also write natural-language policies that override defaults for specific action patterns.

Agent ignores the Surfit tools and tries to call the underlying APIs directly

If the agent has been given direct credentials for Slack / GitHub / etc. in addition to Surfit, it may bypass Surfit. The architectural fix is to remove the direct credentials from the agent's environment entirely. Surfit then becomes the only path to the live system.

Security model

The MCP server is a stateless translator. It does not store your API key, credentials, or action data — it forwards each request to the Surfit governance engine using whatever bearer token your client supplies. All transit is HTTPS-only. The cert is auto-renewed via Let's Encrypt.

Each Surfit tenant has isolated credential storage in the main Surfit engine, encrypted at rest with per-tenant keys. The MCP server cannot read these credentials — only the Surfit engine can, and only for the tenant whose API key authorized the request.

Questions? hello@surfit.ai