Surface README

Surface — preflight a URL before your agent opens it

Surface is a remote MCP server and HTTP API. It unwraps short or unknown links (t.co, bit.ly, lnkd.in, youtu.be) and tells your agent whether to open them: next: "fetch" or next: "skip". It never returns the page body.

This repo contains:

• Remote MCP endpoint (Streamable HTTP): https://nova-otter-delta-cloud.grok.me/mcp
• Tool: preflight_url { "url": "https://..." }
• Official MCP Registry: me.grok.nova-otter-delta-cloud/surface
• Docs: https://nova-otter-delta-cloud.grok.me/docs · OpenAPI: https://nova-otter-delta-cloud.grok.me/openapi.json

Quick start (remote, no install)

Claude Code

claude mcp add --transport http surface https://nova-otter-delta-cloud.grok.me/mcp

Cursor (.cursor/mcp.json)

{ "mcpServers": { "surface": { "url": "https://nova-otter-delta-cloud.grok.me/mcp" } } }

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_API_KEY: optional. This is a surf_live_… key (the public demo key uses surf_demo_…), sent as Authorization: Bearer …. Without a key, calls bill the shared demo meter.
• 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)

# REST
curl -s "https://nova-otter-delta-cloud.grok.me/v1/preflight?url=https://bit.ly/example"

# MCP
curl -s https://nova-otter-delta-cloud.grok.me/mcp \
  -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"}}}'

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

• Official MCP Registry: me.grok.nova-otter-delta-cloud/surface
• Smithery: https://smithery.ai/servers/canada-site-ops/surface
• CuratedMCP: https://www.curatedmcp.com/marketplace/surface
• AllMCPs: https://allmcps.com/mcp/surface
• AI Agents Listing:
• MCPizy: https://mcpizy.com/directory/surface
• MCPRush: https://mcprush.com/grok/surface-mcp

Operator, privacy, license

• Operator: Canada Site Ops (canada.site.ops@gmail.com)
• Privacy policy: https://nova-otter-delta-cloud.grok.me/privacy (summary in PRIVACY.md)
• Support: open an issue or email canada.site.ops@gmail.com
• License: MIT