# mdapi-mcp — MCP server for https://md.fastdb.in

Exposes the paid mdapi endpoints as MCP tools, with x402 pay-per-call
($0.005 in USDC on Base, no signup, no API key):

| Tool | What it does | Price |
|---|---|---|
| `html_to_markdown` | URL or raw HTML → clean, LLM-ready Markdown. `render: true` executes the page in a real headless browser first (JS-rendered SPAs). | $0.005 |
| `extract_page` | URL or raw HTML → structured JSON: title, byline, excerpt, links, images, meta. | $0.005 |
| `service_info` | Service + pricing details. | free |

Failed calls are never charged — settlement happens only after the tool succeeds.

## Two ways to use it

### 1. Remote MCP server (recommended)

Streamable HTTP endpoint: **`https://md.fastdb.in/mcp`**
Listed in the official MCP registry as **`in.fastdb.md/mdapi`**.

Payments are in-protocol x402 v2 (the official `@x402/mcp` pattern): an unpaid
`tools/call` returns the payment requirements; an x402-aware MCP client signs a
USDC `transferWithAuthorization` and retries with the payment in `_meta`.
No ETH needed — the facilitator sponsors gas.

```js
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
import { createx402MCPClient } from "@x402/mcp";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const client = createx402MCPClient({
  name: "my-agent", version: "1.0.0",
  schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(privateKeyToAccount(process.env.EVM_PRIVATE_KEY)) }],
  autoPayment: true,
});
await client.connect(new StreamableHTTPClientTransport(new URL("https://md.fastdb.in/mcp")));
const result = await client.callTool("html_to_markdown", { url: "https://example.com" });
```

`server.js` is this remote server. It runs conversion in-process (same `../lib`
as the HTTP API) and verifies/settles via the Coinbase CDP facilitator.
Deployed as systemd unit `biz-mdapi-mcp` on 127.0.0.1:8403 behind nginx `/mcp`.

### 2. Local stdio server (Claude Desktop and other vanilla MCP clients)

`stdio.js` runs on your machine with **your** wallet key and wraps the live paid
HTTP API: it answers the HTTP 402 challenge for you (x402 v1 `X-PAYMENT` flow
via `x402-fetch`). Install straight from the tarball we host:

```jsonc
// Claude Desktop / any MCP client config
{
  "mcpServers": {
    "mdapi": {
      "command": "npx",
      "args": ["-y", "https://md.fastdb.in/mcp/mdapi-mcp.tgz"],
      "env": { "EVM_PRIVATE_KEY": "0x..." } // wallet holding USDC on Base
    }
  }
}
```

Env: `EVM_PRIVATE_KEY` (required), `MDAPI_BASE_URL` (optional override).
Per-call spend is hard-capped at 0.01 USDC in the client wrapper.

## Discovery

- Official MCP registry: `in.fastdb.md/mdapi` (remote, streamable-http)
- x402 Bazaar (Coinbase CDP discovery layer): `https://md.fastdb.in/md` and
  `/extract` are indexed; agents using the Bazaar MCP server
  (`https://api.cdp.coinbase.com/platform/v2/x402/discovery/mcp`) can find and
  call them there too.
- Machine-readable catalog: `GET https://md.fastdb.in/` (JSON for non-browsers)

## Repo layout

- `server.js` — remote MCP server (x402 v2 in-protocol payments, CDP facilitator).
  Reference: it imports mdapi's core `../lib`, which lives in the main mdapi
  codebase and is not vendored here — `stdio.js` is the fully self-contained entry.
- `stdio.js` — local stdio MCP server (pays the HTTP API with your key)
- `server.json` — MCP registry manifest