SDK Documentation

Unbrowse uses the Model Context Protocol (MCP) to integrate with AI assistants. This page covers advanced configuration and usage.

What is MCP?

The Model Context Protocol is an open standard that allows AI assistants to interact with external tools and services. Instead of writing custom integrations for each AI platform, Unbrowse provides a single MCP server that works across:

• Claude Desktop

• Continue.dev

• Cline

• Any MCP-compatible AI tool

Installation

Automated (Smithery)

The easiest way to install:

npx @smithery/cli install @lekt9/unbrowse-mcp --client claude

This automatically configures your Claude Desktop with the Unbrowse MCP server.

Manual Configuration

Claude Desktop

Location: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

{
  "mcpServers": {
    "unbrowse": {
      "command": "npx",
      "args": ["-y", "@lekt9/unbrowse-mcp"],
      "env": {
        "UNBROWSE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Continue.dev

Location: ~/.continue/config.json

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "name": "unbrowse",
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@lekt9/unbrowse-mcp"]
        },
        "env": {
          "UNBROWSE_API_KEY": "your_api_key_here"
        }
      }
    ]
  }
}

Cline (VS Code Extension)

Add to Cline's MCP settings:

{
  "unbrowse": {
    "command": "npx",
    "args": ["-y", "@lekt9/unbrowse-mcp"],
    "env": {
      "UNBROWSE_API_KEY": "your_api_key_here"
    }
  }
}

Environment Variables

Configure the MCP server with these environment variables:

# Required
UNBROWSE_API_KEY=your_api_key_here

# Optional
UNBROWSE_BASE_URL=https://api.unbrowse.ai  # Custom API endpoint
UNBROWSE_TIMEOUT=30000                      # Request timeout (ms)
UNBROWSE_MAX_RETRIES=3                      # Auto-retry failed requests

Available Tools

The Unbrowse MCP server exposes these tools to AI assistants:

unbrowse_search

Search for abilities by natural language query.

Input Schema:

{
  query: string;      // Natural language description
  limit?: number;     // Max results (default: 10)
  category?: string;  // Filter by category
}

Output:

{
  abilities: [
    {
      id: string;
      name: string;
      description: string;
      category: string;
      parameters: {
        [key: string]: {
          type: string;
          description: string;
          required: boolean;
        }
      };
      cost: number;  // Execution cost in USD
    }
  ]
}

Example:

{
  "query": "search flights",
  "category": "travel",
  "limit": 5
}

unbrowse_execute

Execute a specific ability with parameters.

Input Schema:

{
  ability_id: string;
  params: Record<string, any>;
  timeout?: number;  // Optional execution timeout
}

Output:

{
  success: boolean;
  data: any;           // Structured result from ability
  execution_time: number;  // Milliseconds
  cost: number;        // USD charged for this execution
}

Example:

{
  "ability_id": "united_search_flights_v2",
  "params": {
    "origin": "NYC",
    "destination": "LAX",
    "departure_date": "2025-01-15",
    "passengers": 1
  }
}

unbrowse_list_categories

List all available ability categories.

Input: None

Output:

{
  categories: [
    {
      name: string;
      slug: string;
      ability_count: number;
      description: string;
    }
  ]
}

Advanced Usage

Chaining Multiple Abilities

AI assistants can automatically chain Unbrowse abilities:

User: "Research Snowflake's competitors and post a summary to Slack"

AI Assistant:
1. unbrowse_search("competitor research") → finds SpyFu ability
2. unbrowse_execute("spyfu_competitor_search", {domain: "snowflake.com"})
3. [Process results, generate summary]
4. unbrowse_search("post to Slack") → finds Slack ability
5. unbrowse_execute("slack_post_message", {channel: "#research", text: "..."})

Error Handling

The MCP server returns detailed error information:

{
  success: false,
  error: {
    code: "RATE_LIMIT_EXCEEDED",
    message: "Daily execution limit reached (100/100)",
    suggestions: [
      "Upgrade to Pro tier for 1,000 executions/day",
      "Try again tomorrow",
      "Contact support for temporary limit increase"
    ],
    retry_after: 43200  // Seconds until retry allowed
  }
}

Caching

The MCP server automatically caches ability search results for 5 minutes to reduce costs and latency.

Cache behavior:

• Search queries are cached by query string

• Ability definitions cached by ID

• Cache invalidated on any execution error

• Can be disabled with UNBROWSE_DISABLE_CACHE=true

Monitoring Usage

Track your Unbrowse usage in the dashboard:

agent.unbrowse.ai/dashboard

Metrics available:

• Total searches performed

• Total abilities executed

• Cost breakdown by ability

• Success/failure rates

• Most-used abilities

Security

API Key Protection

Never commit API keys to version control.

Best practices:

• Use environment variables

• Store in OS-specific secure storage (Keychain, etc.)

• Rotate keys regularly

• Use separate keys for dev/prod

Request Signing

All MCP requests are signed with your API key. The server validates:

• API key authenticity

• Request timestamp (prevents replay attacks)

• Request integrity (prevents tampering)

Debugging

Enable debug logging:

UNBROWSE_DEBUG=true npx @lekt9/unbrowse-mcp

This logs:

• All search queries

• Ability executions

• API responses

• Error details

• Performance metrics

Debug output:

[Unbrowse MCP] Search: "post to LinkedIn"
[Unbrowse MCP] Found 3 abilities in 45ms
[Unbrowse MCP] Execute: linkedin_post_v3
[Unbrowse MCP] Success in 324ms (cost: $0.001)

Performance

Typical latencies:

• Ability search: 20-50ms (cached: <5ms)

• Ability execution: 200-500ms

• Total workflow: <1 second

Optimization tips:

• Use specific queries ("LinkedIn post with image" vs "social media")

• Reuse ability IDs instead of searching repeatedly

• Execute abilities in parallel when possible

Troubleshooting

"MCP server not found"

Solution:

# Reinstall the MCP server
npx @smithery/cli install @lekt9/unbrowse-mcp --client claude --force

"Invalid API key"

Solution:

• Verify API key at agent.unbrowse.ai/settings

• Check environment variable is set correctly

• Ensure no extra spaces or quotes in config

"Rate limit exceeded"

Solution:

• Check usage at agent.unbrowse.ai/dashboard

• Upgrade to Pro tier

• Wait for daily limit reset (midnight UTC)

"Ability execution failed"

Solutions:

• Check ability parameters match requirements

• Verify you have necessary credentials/subscriptions

• Try a different ability variant

• Report persistent failures to support

Next Steps

• Integration Examples - Detailed use cases

• API Reference - REST API docs (for custom integrations)

• Authentication - Auth methods and security

---

Questions? Join our Discord or visit Smithery