Surface
Preflight a short or unknown URL before your agent fetches it. Returns next: fetch or skip.
Installation
Ajoutez ceci à la configuration MCP de votre client (Claude Desktop : claude_desktop_config.json ; Cursor : .cursor/mcp.json ; VS Code et les autres utilisent la même forme « mcpServers »).
claude mcp add --transport http surface 'https://nova-otter-delta-cloud.grok.me/mcp'{
"mcpServers": {
"surface": {
"type": "http",
"url": "https://nova-otter-delta-cloud.grok.me/mcp"
}
}
}Documentation
Tirée du README du projet sur GitHub, actualisée chaque semaine. Les liens ouvrent GitHub.
Sommaire
Surface: check a short link before your agent opens it
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
| Product | What it does | Price after free tier (per 1k, USD) |
|---|---|---|
| Preflight | Unwrap a short link, then say fetch or skip. Also the MCP tool preflight_url. | $0.25 |
| Hop | A tracked redirect link: shorteners, affiliate hops, campaign links. | $0.40 |
| Pixel | A 1×1 image that email clients, ad servers and page tags load on their own. | $0.15 |
| Inspect | Tell 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:
| Path | What it is |
|---|---|
src/client.js | Zero-dependency JS client: REST preflight(), remote-MCP mcpPreflight(), and a minimal Streamable-HTTP McpHttpClient |
src/stdio-server.js + bin/surface-mcp.js | Local stdio MCP server exposing preflight_url, which forwards to the remote endpoint (for clients that only run commands) |
bin/surface-preflight.js | CLI: surface-preflight <url> prints fetch/skip (exit 0 = fetch, 2 = skip) |
examples/ | Python (stdlib only) and Node examples, plus client configs |
action.yml | GitHub 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.yaml | Registry and discovery metadata |
- 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)
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 --jsonOr without cloning:
{ "mcpServers": { "surface": { "command": "npx", "args": ["-y", "github:Surface-ops/surface"] } } }Environment:
SURFACE_KEY: optional. Your freesurf_…key fromPOST /v1/keysor /start#key, sent asAuthorization: Bearer ….SURFACE_API_KEYis still accepted. Without a key, calls use the shared keyless tier (60 per minute).SURFACE_BASE_URL: optional. It defaults tohttps://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-Agentheader (for exampleUser-Agent: my-agent/1.0). Python's built-inurllibdefault agent can be blocked at the edge;requests,httpxandcurlwork 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
- awesome-remote-mcp-servers: punkpeye/awesome-remote-mcp-servers
- ToolSDK MCP Registry: toolsdk-ai/toolsdk-mcp-registry (
@toolsdk-remote/surface-preflight)
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
Questions fréquentes
Qu'est-ce que Surface ?
Preflight a short or unknown URL before your agent fetches it. Returns next: fetch or skip.
Comment installer Surface ?
Il fonctionne comme serveur distant. Dans Claude Code : claude mcp add --transport http surface 'https://nova-otter-delta-cloud.grok.me/mcp'. Pour les autres clients, collez la configuration JSON de cette page dans leurs réglages MCP.
Faut-il une clé API pour Surface ?
Son entrée au registre n'indique aucune clé ni secret obligatoire. Certaines fonctions peuvent tout de même demander un compte auprès du service auquel il se connecte.
Surface est-il open source ?
Oui. Son code est sur GitHub sous licence MIT.
Qui maintient Surface ?
Il est publié par Surface-ops. AI.tn le référence sans le maintenir ni le recommander.
Issu du registre MCP officiel. Être listé n'est pas une recommandation : vérifiez le code et les permissions d'un serveur avant de lui donner accès à vos données.