# Surface [Verified] [Health: Active]

**Category:** 🔎 Search & Data Extraction  
**Repository:** https://github.com/Surface-ops/surface  
**GitHub Stars:** 0  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/surface

## Description
Remote MCP (streamable HTTP at https://nova-otter-delta-cloud.grok.me/mcp). Tool preflight_url unwraps short or unknown links (t.co, bit.ly, lnkd.in) before an agent fetches them and returns next: fetch or skip. No page body returned. Usage-priced: Preflight $0.25/1k, Inspect $0.20/1k.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "surface": {
    "command": "npx",
    "args": ["-y","github:Surface-ops/surface"],
    "env": {
      "SURFACE_API_KEY": "",
      "SURFACE_BASE_URL": ""
    }
  }
}
```

**Requires environment variables:** `SURFACE_API_KEY`, `SURFACE_BASE_URL` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What Surface MCP server does

The Surface MCP server evaluates a URL before an agent fetches it. Its main operation, `preflight_url`, accepts a URL and reports whether the agent should continue with `fetch` or avoid opening it with `skip`. This is intended for links whose destination is unclear, especially shortened or unfamiliar URLs.

The result can include the final destination, the source and destination hosts, and whether the address was unwrapped. It also provides a more specific verdict: `fetch`, `dead`, `wall`, or `trap`. Surface does not retrieve or return the target page's body, so another tool or the agent must perform the eventual fetch.

## How it works

The hosted service is available through a Streamable HTTP MCP endpoint. An MCP client calls `preflight_url` with an object such as `{ "url": "https://bit.ly/example" }`. Surface follows the link-preflight process and returns structured data including `next`, `verdict`, `unwrapped`, `from_host`, `final_host`, and `final_url`.

The repository also includes a local stdio MCP process. That process accepts JSON-RPC over standard input and forwards the preflight request to the hosted endpoint, making it suitable for clients that require a command rather than a remote URL. A command-line utility exposes the same decision as `fetch` or `skip`; exit code 0 represents fetch and exit code 2 represents skip.

## Setup and configuration

For remote use, configure an MCP client with `https://nova-otter-delta-cloud.grok.me/mcp`. The repository documents setup for Claude Code, Cursor, VS Code, Codex, and Claude Desktop. Local use requires Node.js 18 or newer and has no package dependencies. The stdio bridge can be started from a clone or through `npx` using the GitHub repository.

`SURFACE_API_KEY` is optional. When supplied, the client sends the `surf_live_...` credential as a bearer token. Without it, requests use the shared demonstration meter. `SURFACE_BASE_URL` is also optional and can replace the default service URL. Offline tests use a local mock and do not call the live meter.

## Tools and capabilities

The Surface MCP server exposes one MCP tool: `preflight_url`. The repository's JavaScript client additionally provides REST and MCP helper functions, including `preflight`, `mcpPreflight`, and `shouldFetch`. REST callers can use the `/v1/preflight` endpoint, while MCP callers use `tools/call`.

The service charges $0.25 per 1,000 preflight calls through REST or MCP. Initialization and tool-list requests are not counted as tool calls. Private hosts and unusual ports are refused, which limits use cases involving internal services or nonstandard network targets.

## Limitations and notes

Surface is a decision and URL-resolution step, not a web-content extraction service. It does not provide the page body, summarize a destination, or replace the fetch operation that follows a `fetch` result. Agents should treat the returned recommendation and destination fields as inputs to their own retrieval policy.

The hosted endpoint, documentation, OpenAPI description, privacy policy, and operator contact are published separately from the repository. The project is distributed under the MIT license.

_Full upstream README: https://allmcps.com/mcp/surface/readme_