# MCP Services — Complete Documentation

> Multi-tool MCP server + REST API for AI agents by SKILLS.ws — 29 tools across web scraping, SEO, agent memory, content extraction, domain intelligence, blockchain data, and security toolkit.

Website: https://mcp.skills.ws
GitHub: https://github.com/san-npm/mcp-services
License: MIT | Author: Commit Media SARL

---

## What is MCP Services?

MCP Services is a Model Context Protocol (MCP) server that exposes 29 tools to AI agents via Server-Sent Events (SSE) transport. It also provides the same tools as a standard REST API. The server handles web scraping, site crawling, structured data extraction, SEO analysis (SERP, on-page, keywords), persistent agent memory, screenshots, PDF generation, domain intelligence (WHOIS, DNS, SSL), content extraction (HTML-to-Markdown, OCR), multi-chain EVM blockchain queries, and a security toolkit (URL scanning, wallet risk, contract analysis, email authentication, threat intelligence, header auditing).

## MCP Connection

To connect from Claude Desktop, Cursor, or any MCP-compatible client:

```json
{
  "mcpServers": {
    "mcp-services": {
      "url": "https://mcp.skills.ws/mcp/sse"
    }
  }
}
```

SSE endpoint: `GET https://mcp.skills.ws/mcp/sse`
Message endpoint: `POST https://mcp.skills.ws/mcp/messages?sessionId=<id>`

---

## Tool Reference

### 1. scrape
Scrape a URL and convert to clean Markdown. Returns title, markdown content, word count, and links found.

Parameters:
- `url` (string, required) — URL to scrape

REST: `GET /api/scrape?url=https://example.com`

### 2. crawl
Crawl a website starting from a URL. Follows internal links up to specified depth. Returns markdown for each page.

Parameters:
- `url` (string, required) — Starting URL to crawl
- `depth` (number, default: 1) — Max crawl depth (1-3)
- `maxPages` (number, default: 10) — Max pages to crawl (1-20)

REST: `GET /api/crawl?url=https://example.com&depth=2&maxPages=10`

### 3. extract
Extract structured data from a URL: JSON-LD, Open Graph, meta tags, headings, links, images, tables.

Parameters:
- `url` (string, required) — URL to extract data from

REST: `GET /api/extract?url=https://example.com`

### 4. serp
Scrape Google search results for a keyword. Returns organic results, People Also Ask, featured snippets, and related searches.

Parameters:
- `keyword` (string, required) — Search keyword

REST: `GET /api/serp?keyword=best+mcp+servers`

### 5. onpage_seo
Full on-page SEO analysis of a URL. Scores title, meta description, headings, images, links, schema markup, Open Graph, and more. Returns a score from 0-100 with specific issues.

Parameters:
- `url` (string, required) — URL to analyze

REST: `GET /api/onpage-seo?url=https://example.com`

### 6. keywords_suggest
Get keyword suggestions using Google Autocomplete. Expands seed keyword with A-Z suffixes. Returns up to 100 related keyword ideas.

Parameters:
- `keyword` (string, required) — Seed keyword

REST: `GET /api/keywords?keyword=mcp+server`

### 7. memory_store
Store a memory in persistent storage. Memories are scoped by namespace. Upserts on key conflict.

Parameters:
- `namespace` (string, required) — Memory namespace (e.g., "my-agent", "project-x")
- `key` (string, required) — Memory key (max 256 chars)
- `value` (string, required) — Memory value (max 100KB)
- `tags` (string, optional) — Comma-separated tags

REST: `POST /api/memory` with JSON body `{ "namespace": "...", "key": "...", "value": "...", "tags": ["..."] }`

### 8. memory_get
Retrieve a memory by namespace and key.

Parameters:
- `namespace` (string, required) — Memory namespace
- `key` (string, required) — Memory key

REST: `GET /api/memory?namespace=my-agent&key=my-key`

### 9. memory_search
Search memories by text query within a namespace. Uses full-text search (FTS5).

Parameters:
- `namespace` (string, required) — Memory namespace
- `query` (string, required) — Search query
- `limit` (number, default: 20) — Max results (1-50)

REST: `GET /api/memory/search?namespace=my-agent&query=search+term`

### 10. memory_list
List all memories in a namespace with pagination.

Parameters:
- `namespace` (string, required) — Memory namespace
- `offset` (number, default: 0) — Pagination offset
- `limit` (number, default: 20) — Max items (1-100)

REST: `GET /api/memory/list?namespace=my-agent&offset=0&limit=20`

### 11. memory_delete
Delete a memory by namespace and key.

Parameters:
- `namespace` (string, required) — Memory namespace
- `key` (string, required) — Memory key

REST: `DELETE /api/memory?namespace=my-agent&key=my-key`

### 12. screenshot
Take a screenshot of any URL. Returns base64 PNG/JPEG image.

Parameters:
- `url` (string, required) — URL to screenshot
- `format` (string, default: "png") — "png" or "jpeg"
- `width` (number, default: 1280) — Viewport width (100–3840)
- `height` (number, default: 800) — Viewport height (100–2160)
- `fullPage` (boolean, default: false) — Capture full scrollable page

REST: `GET /api/screenshot?url=https://example.com&format=png&width=1280&height=800&fullPage=false`

### 13. pdf
Generate a PDF of any URL. Returns PDF binary (REST) or base64 data URI (MCP).

Parameters:
- `url` (string, required) — URL to convert to PDF

REST: `GET /api/pdf?url=https://example.com`

### 14. pdf2docx
Convert a PDF file (from URL) to DOCX/Word format. Extracts text and structure from the PDF, reconstructs lines by Y-position grouping, detects headings (short uppercase lines), and builds a properly formatted Word document.

Parameters:
- `url` (string, required) — URL to a PDF file

REST: `GET /api/pdf2docx?url=https://example.com/document.pdf`

### 15. html2md
Fetch a URL and convert the page content to clean Markdown. Removes navigation, ads, and scripts. Extracts the main article content with proper heading, link, list, and code block formatting.

Parameters:
- `url` (string, required) — URL to fetch and convert

REST: `GET /api/html2md?url=https://example.com`

### 16. ocr
Extract text from an image URL using OCR (Tesseract.js). Supports common image formats.

Parameters:
- `url` (string, required) — Image URL to extract text from

REST: `GET /api/ocr?url=https://example.com/image.png`

### 17. whois
Look up WHOIS information for a domain. Returns registrar, creation date, expiry, name servers, and more.

Parameters:
- `domain` (string, required) — Domain name to look up

REST: `GET /api/whois?domain=example.com`

### 18. dns
Look up DNS records for a domain. Supports individual record types or ALL.

Parameters:
- `domain` (string, required) — Domain name
- `type` (string, default: "ALL") — Record type: A, AAAA, MX, NS, TXT, CNAME, SOA, or ALL

REST: `GET /api/dns?domain=example.com&type=ALL`

### 19. ssl
Check SSL certificate details for a domain. Returns issuer, validity dates, expiry countdown, and fingerprint.

Parameters:
- `domain` (string, required) — Domain to check SSL certificate for

REST: `GET /api/ssl?domain=example.com`

### 20. balance
Get native token balance for an address on any of 6 supported EVM chains.

Parameters:
- `address` (string, required) — Wallet address (0x...)
- `chain` (string, default: "ethereum") — Chain: ethereum, base, arbitrum, optimism, polygon, celo

REST: `GET /api/chain/balance?address=0x...&chain=ethereum`

### 21. erc20_balance
Get ERC20 token balance for an address. Returns balance, symbol, and decimals.

Parameters:
- `address` (string, required) — Wallet address
- `token` (string, required) — Token contract address
- `chain` (string, default: "ethereum") — Chain name

REST: `GET /api/chain/erc20?address=0x...&token=0x...&chain=ethereum`

### 22. transaction
Get transaction details by hash. Returns from, to, value, gas used, status, and block number.

Parameters:
- `hash` (string, required) — Transaction hash (0x + 64 hex chars)
- `chain` (string, default: "ethereum") — Chain name

REST: `GET /api/chain/tx?hash=0x...&chain=ethereum`

### 23. url_scan
Scan a URL for phishing, malware, and suspicious indicators. Uses VirusTotal (if API key configured) plus heuristics: typosquatting detection against 23 known brands, homoglyph detection, suspicious TLD check, free hosting detection, IP-as-hostname check, HTTP login page detection.

Parameters:
- `url` (string, required) — URL to scan (must be http/https)

REST: `GET /api/security/url-scan?url=https://suspicious-site.com`

### 24. wallet_check
Assess risk of an Ethereum wallet address. Checks Etherscan contract verification status, transaction patterns, OFAC/SDN sanctions list, and warns about address poisoning. Returns severity (clean/suspicious/malicious) with risk details.

Parameters:
- `address` (string, required) — Ethereum address (0x + 40 hex chars)
- `chain` (string, default: "ethereum") — Chain: ethereum, base, arbitrum, optimism, polygon

REST: `GET /api/security/wallet-check?address=0x...&chain=ethereum`

### 25. contract_scan
Detect honeypot tokens and risky smart contracts. Uses Honeypot.is API for buy/sell tax analysis, plus Etherscan source code analysis checking for: mint functions, blacklist mechanisms, fee manipulation, pausable transfers, proxy patterns, and ownership renouncement.

Parameters:
- `address` (string, required) — Contract address (0x + 40 hex chars)
- `chainId` (number, default: 1) — Chain ID: 1 (Ethereum), 8453 (Base), 42161 (Arbitrum), 10 (Optimism), 137 (Polygon)

REST: `GET /api/security/contract-scan?address=0x...&chainId=1`

### 26. email_headers
Check email authentication configuration for a domain. Queries DNS for SPF, DKIM (checks common selectors: default, google, selector1, selector2, k1, mail, dkim), DMARC policy, and MX records.

Parameters:
- `domain` (string, required) — Domain to check (e.g., "example.com")

REST: `GET /api/security/email-headers?domain=example.com`

### 27. threat_intel
Look up an Indicator of Compromise (IOC) across multiple threat intelligence sources. Queries AbuseIPDB (IPs), VirusTotal (all types), and OTX AlienVault (all types). Returns weighted confidence score combining all sources. Auto-detects IOC type or accepts explicit type.

Parameters:
- `ioc` (string, required) — The IOC value: IP address, domain, URL, MD5/SHA1/SHA256 hash
- `iocType` (string, default: "auto") — IOC type: auto, ip, domain, url, hash_md5, hash_sha1, hash_sha256

REST: `GET /api/security/threat-intel?ioc=8.8.8.8&type=ip`

### 28. header_audit
Audit a website's security headers and produce a score from 0 to 100. Checks: Strict-Transport-Security (HSTS), Content-Security-Policy (CSP), X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy, X-XSS-Protection. Also checks cookie security flags (Secure, HttpOnly, SameSite).

Parameters:
- `url` (string, required) — URL to audit (must be http/https, public host)

REST: `GET /api/security/header-audit?url=https://example.com`

### 29. vuln_headers
Check a website for information-leaking HTTP headers. Detects: Server version disclosure, X-Powered-By, X-AspNet-Version, X-AspNetMvc-Version, debug/trace headers, and CORS misconfiguration (Access-Control-Allow-Origin: *).

Parameters:
- `url` (string, required) — URL to check (must be http/https, public host)

REST: `GET /api/security/vuln-headers?url=https://example.com`

> **Note:** Security tools (22-28) degrade gracefully without API keys — they use heuristics-only mode. For full coverage, configure VT_API_KEY, ABUSEIPDB_API_KEY, and ETHERSCAN_API_KEY.

---

## Supported Chains

| Chain | Native Token | RPC |
|-------|-------------|-----|
| Ethereum | ETH | ethereum-rpc.publicnode.com |
| Base | ETH | base-rpc.publicnode.com |
| Arbitrum | ETH | arbitrum-one-rpc.publicnode.com |
| Optimism | ETH | optimism-rpc.publicnode.com |
| Polygon | MATIC | polygon-bor-rpc.publicnode.com |
| Celo | CELO | forno.celo.org |

---

## Authentication

### Free Tier (default)
No authentication required. Rate limited to 10 API calls per day per IP address.

Response headers include:
- `X-RateLimit-Limit: 10`
- `X-RateLimit-Remaining: <n>`

When limit is exceeded, returns HTTP 429 with upgrade options.

### API Key ($9/mo)
Unlimited API calls. Send key in header:
```
X-Api-Key: mcp_your_key_here
```

Or as query parameter: `?apikey=mcp_your_key_here`

### x402 Pay-per-call ($0.005/call)
No account needed. Pay with USDC or USDT on Base or Celo. x402-compatible agents handle payment automatically. Transactions are verified on-chain.

Send base64-encoded payment proof in header:
```
X-Payment: <base64-encoded-json>
```

Payment JSON format: `{ "network": "celo", "token": "USDC", "txHash": "0x...", "amount": "0.005", "receiver": "0x..." }`

---

## Health Check

`GET /health` — Returns `{ "status": "ok", "services": [...] }`

---

## Security

- SSRF protection: URL validation + DNS pre-resolution + private IP blocking + Puppeteer request interception
- Domain validation: regex allowlist prevents command injection
- Input sanitization: IOC format validation, address format checks, chain/chainId allowlists
- Rate limiting: IP-based daily limits on free tier
- Resource limits: max 3 concurrent browsers, 50 SSE sessions, 50MB PDF cap, 5MB fetch body limit
- Async SSL: non-blocking openssl via child_process.spawn
- x402 on-chain verification: transaction receipts verified on Base/Celo RPCs
- Memory namespace isolation: API key hashed with SHA-256 for DB scoping

---

## Self-hosted Setup

```bash
git clone https://github.com/san-npm/mcp-services.git
cd mcp-services
npm install
node server.js  # runs on port 3100
```

Requires: Node.js 22+, Chromium (for screenshot/PDF/OCR/html2md/scrape/crawl)

Environment variables:
- `PORT` — Server port (default: 3100)
- `CHROMIUM_PATH` — Path to Chromium binary (default: /usr/bin/chromium-browser)
- `MAX_BROWSERS` — Max concurrent browser instances (default: 3)
- `MAX_SSE_SESSIONS` — Max MCP SSE sessions (default: 50)
- `FREE_DAILY_LIMIT` — Free tier daily call limit (default: 10)
- `API_KEYS` — Comma-separated valid API keys
- `ADMIN_SECRET` — Secret for admin endpoints
- `KEYS_FILE` — Persistent API key storage path (default: ./data/api-keys.json)
- `MEMORY_DB_PATH` — SQLite database path for agent memory (default: ./data/memory.db)
- `STRIPE_SK` — Stripe secret key
- `STRIPE_WEBHOOK_SECRET` — Stripe webhook signing secret
- `DOMAIN` — Base URL for Stripe checkout redirects (default: https://mcp.skills.ws)
- `X402_PRICE_USD` — x402 price per call (default: 0.005)
- `X402_RECEIVER` — x402 payment receiver address
- `VT_API_KEY` — VirusTotal API key (free: 4 req/min, 500/day)
- `ABUSEIPDB_API_KEY` — AbuseIPDB API key (free: 1000 req/day)
- `ETHERSCAN_API_KEY` — Etherscan API key (free: 5 req/sec)