MCP Server

Use Orsa as a tool provider for AI assistants via the Model Context Protocol (MCP). Works with Claude Desktop, Cursor, and any MCP-compatible client.

What is MCP?

MCP is an open protocol that lets AI assistants use external tools. With the Orsa MCP server, Claude and other assistants can:

Scrape websites for real-time content (markdown, HTML)
Look up brand data (logos, colors, industries, fonts)
Extract products from a domain via tool-use
Run natural-language queries against any website
Take a screenshot of any domain’s homepage
Match bank transaction descriptors to brands

Under the hood the MCP server is a thin wrapper around the @orsa.dev/sdk TypeScript SDK.

Installation

npm install -g @orsa.dev/mcp-server
# or run without installing:
npx @orsa.dev/mcp-server

Claude Desktop Setup

Add the Orsa MCP server to your Claude Desktop config:

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

{
  "mcpServers": {
    "orsa": {
      "command": "npx",
      "args": ["@orsa.dev/mcp-server"],
      "env": {
        "ORSA_API_KEY": "or_live_your_key_here"
      }
    }
  }
}

Restart Claude Desktop after saving.

Cursor Setup

Add to your Cursor MCP settings (.cursor/mcp.json in your project root):

{
  "mcpServers": {
    "orsa": {
      "command": "npx",
      "args": ["@orsa.dev/mcp-server"],
      "env": {
        "ORSA_API_KEY": "or_live_your_key_here"
      }
    }
  }
}

Available Tools

Once configured, the following tools are available to your AI assistant. Tool names mirror the underlying SDK methods.

Web scraping

Tool	SDK method	Description	Credits
`scrape_html`	`web.scrape({ mode: 'html' })`	Single-page raw HTML	1
`scrape_markdown`	`web.scrape({ mode: 'markdown' })`	Single-page clean markdown	1
`scrape_images`	`web.scrapeImages`	All images with role classification	1
`scrape_sitemap`	`web.scrapeSitemap`	Sitemap URLs + path-grouped buckets	1

Brand intelligence

Tool	SDK method	Description	Credits
`get_brand`	`brand.retrieve`	Full brand data (Context.dev shape)	10
`get_brand_by_name`	`brand.retrieveByName`	Fuzzy company-name lookup	2
`get_brand_by_email`	`brand.retrieveByEmail`	Lookup by business email	10
`get_brand_screenshot`	`brand.screenshot`	Homepage screenshot (inline base64 PNG)	5
`get_brand_styleguide`	`brand.styleguide`	Design tokens + DESIGN.md	15
`get_brand_fonts`	`brand.fonts`	Font families + sources	5
`get_naics`	`brand.naics`	Industry classification	5
`identify_transaction`	`brand.transactionIdentifier`	Match a bank descriptor to a brand	10

AI

Tool	SDK method	Description	Credits
`ai_query`	`ai.query`	Natural-language extraction	20
`extract_products`	`ai.products`	Tool-use enforced product list	15

Usage Examples

Once the MCP server is running, ask Claude naturally:

“What are the brand colors for linear.app?”
“Scrape the pricing page of stripe.com and summarize the plans.”
“Extract all products from shopify.com with their prices.”
“Take a screenshot of github.com.”
“What fonts does vercel.com use?”

Claude will automatically call the appropriate Orsa tool.

Environment Variables

Variable	Required	Description
`ORSA_API_KEY`	Yes	Your Orsa API key
`ORSA_BASE_URL`	No	Custom API base URL (default: `https://api.orsa.dev`)

Troubleshooting

Tools not appearing in Claude

Verify the config file path is correct for your OS.
Ensure ORSA_API_KEY is set (not an empty string).
Restart Claude Desktop completely (quit + relaunch).
Check Claude Desktop logs for MCP connection errors.

”API key invalid” errors

Get your key at orsa.dev/dashboard/api-keys.
Make sure the key is for the correct environment (production vs sandbox).

Timeout errors

Some tools — AI query, styleguide extraction, AI products — can take 30-90 seconds on a cold cache. The MCP server handles timeouts automatically, but if you see frequent timeouts, the target website may be slow or blocking requests.

OpenClaw Zapier