English Français العربية

Surface

السجل الرسمي الذكاء الاصطناعي والوكلاء

Preflight a short or unknown URL before your agent fetches it. Returns next: fetch or skip.

الشيفرة المصدرية الموقع التوثيق

التثبيت

أضف هذا إلى إعدادات MCP في عميلك (Claude Desktop: claude_desktop_config.json، وCursor: ‏.cursor/mcp.json، ويستخدم VS Code وغيره الصيغة نفسها «mcpServers»).

Remote (streamable-http)
Claude Code 
claude mcp add --transport http surface 'https://nova-otter-delta-cloud.grok.me/mcp'
إعداد JSON (Claude Desktop وCursor وVS Code) 
{
    "mcpServers": {
        "surface": {
            "type": "http",
            "url": "https://nova-otter-delta-cloud.grok.me/mcp"
        }
    }
}

التوثيق

مأخوذ من ملف README للمشروع على GitHub ويُحدَّث أسبوعيًا. تفتح الروابط على GitHub.

المحتويات
  1. Surface: check a short link before your agent opens it
  2. Quick start (remote, no install)
  3. Run locally (stdio bridge)
  4. Use as a library
  5. Raw HTTP (30 seconds)
  6. Pricing
  7. Directory listings
  8. Operator, privacy, license

Your agent gets a t.co, bit.ly, lnkd.in or youtu.be link and has no idea where it goes. Surface follows the hops and says fetch or skip. It never returns the page, so it's one quick round trip. Free for the first 1,000,000 requests every month, no card needed.

Get started · Get a free API key (10 seconds) · Docs · Pricing · Try it in the browser

ProductWhat it doesPrice after free tier (per 1k, USD)
PreflightUnwrap a short link, then say fetch or skip. Also the MCP tool preflight_url.$0.25
HopA tracked redirect link: shorteners, affiliate hops, campaign links.$0.40
PixelA 1×1 image that email clients, ad servers and page tags load on their own.$0.15
InspectTell whether the caller is a bot, a browser or a script.$0.20

Clients: npm install @surfaceapi/surface · pip install surfaceapi

Under the hood, Surface is a remote MCP server and HTTP API (next: "fetch" or next: "skip").

This repo contains:

PathWhat it is
src/client.jsZero-dependency JS client: REST preflight(), remote-MCP mcpPreflight(), and a minimal Streamable-HTTP McpHttpClient
src/stdio-server.js + bin/surface-mcp.jsLocal stdio MCP server exposing preflight_url, which forwards to the remote endpoint (for clients that only run commands)
bin/surface-preflight.jsCLI: surface-preflight <url> prints fetch/skip (exit 0 = fetch, 2 = skip)
examples/Python (stdlib only) and Node examples, plus client configs
action.ymlGitHub Action: preflight every link in your docs (see examples/github-action/)
openapi.json, discovery/OpenAPI spec, A2A agent card, ai-plugin.json
test/Offline tests against a local mock. They never hit the live meter.
mcp-server.json, server-card.json, .well-known/mcp/server-card.json, smithery.yamlRegistry and discovery metadata

Quick start (remote, no install)

Get a free API key (optional, 10 seconds, no card):

curl -s -X POST https://nova-otter-delta-cloud.grok.me/v1/keys
# -> {"key":"surf_..."}
export SURFACE_KEY=surf_...

Or use the sign-up page: https://nova-otter-delta-cloud.grok.me/start#key. Send the key as Authorization: Bearer $SURFACE_KEY (or X-Surface-Key: $SURFACE_KEY). Check your usage with GET /v1/usage. Keyless calls still work, but they are limited to 60 per minute and include a get_key note.

Claude Code

claude mcp add --transport http surface https://nova-otter-delta-cloud.grok.me/mcp --header "Authorization: Bearer $SURFACE_KEY"

Without a key, drop the --header part.

Cursor (.cursor/mcp.json)

{ "mcpServers": { "surface": { "url": "https://nova-otter-delta-cloud.grok.me/mcp", "headers": { "Authorization": "Bearer surf_..." } } } }

The headers block is optional.

See examples/mcp-clients.md for VS Code, Codex and Claude Desktop.

Run locally (stdio bridge)

Requires Node.js 18 or later. No dependencies.

git clone https://github.com/Surface-ops/surface && cd surface
npm test                       # offline tests
node bin/surface-mcp.js        # stdio MCP server (JSON-RPC on stdin/stdout)
node bin/surface-preflight.js https://bit.ly/example --json

Or without cloning:

{ "mcpServers": { "surface": { "command": "npx", "args": ["-y", "github:Surface-ops/surface"] } } }

Environment:

  • SURFACE_KEY: optional. Your free surf_… key from POST /v1/keys or /start#key, sent as Authorization: Bearer …. SURFACE_API_KEY is still accepted. Without a key, calls use the shared keyless tier (60 per minute).
  • SURFACE_BASE_URL: optional. It defaults to https://nova-otter-delta-cloud.grok.me.

Use as a library

import { preflight, mcpPreflight, shouldFetch } from "surface-mcp"; // or "./src/client.js"

const v = await preflight("https://bit.ly/example");
if (shouldFetch(v)) await fetch(v.final_url);

Raw HTTP (30 seconds)

# 1. Get a free key (optional, no card)
export SURFACE_KEY=$(curl -s -X POST https://nova-otter-delta-cloud.grok.me/v1/keys | jq -r .key)

# 2. REST
curl -s "https://nova-otter-delta-cloud.grok.me/v1/preflight?url=https://bit.ly/example" \
  -H "Authorization: Bearer $SURFACE_KEY"

# 3. MCP
curl -s https://nova-otter-delta-cloud.grok.me/mcp \
  -H "Authorization: Bearer $SURFACE_KEY" \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"preflight_url","arguments":{"url":"https://bit.ly/example"}}}'

# Your usage
curl -s https://nova-otter-delta-cloud.grok.me/v1/usage -H "Authorization: Bearer $SURFACE_KEY"

The header is optional: leave it out and calls still work, limited to 60 per minute, with a get_key note in the response.

Python tip: send a normal User-Agent header (for example User-Agent: my-agent/1.0). Python's built-in urllib default agent can be blocked at the edge; requests, httpx and curl work as-is.

Response fields: next (fetch | skip), verdict (fetch | dead | wall | trap), unwrapped, from_host, final_host, final_url. Private hosts and odd ports are refused.

Pricing

Free: the first 1,000,000 requests every month. No card needed.

After that, Surface charges per call, in USD per 1,000 calls: Preflight $0.25 (REST or MCP tools/call), Hop $0.40, Pixel $0.15, Inspect $0.20. POST /v1/event is ingest and is not billed. A flat $50 CAD/month plan is also available (see /billing). initialize and tools/list are not tool calls. Details: https://nova-otter-delta-cloud.grok.me/docs.

Directory listings

Operator, privacy, license

الأسئلة الشائعة

ما هو Surface؟

Preflight a short or unknown URL before your agent fetches it. Returns next: fetch or skip.

كيف أثبّت Surface؟

يعمل كخادم بعيد. في Claude Code: claude mcp add --transport http surface 'https://nova-otter-delta-cloud.grok.me/mcp'. وفي العملاء الآخرين، الصق إعداد JSON من هذه الصفحة في إعدادات MCP الخاصة بهم.

هل يحتاج Surface إلى مفتاح API؟

لا يذكر إدراجه في السجل أي مفتاح أو سر إلزامي. قد تتطلب بعض الميزات حسابًا لدى الخدمة التي يتصل بها.

هل Surface مفتوح المصدر؟

نعم. شيفرته متاحة على GitHub بترخيص MIT.

من يصون Surface؟

ينشره Surface-ops. يدرجه AI.tn لكنه لا يصونه ولا يوصي به.

من سجل MCP الرسمي. الإدراج ليس توصية: راجع شيفرة الخادم وصلاحياته قبل منحه الوصول إلى بياناتك.