# Serply MCP Server

Serply hosts a remote [Model Context Protocol](https://modelcontextprotocol.io)
(MCP) server at `https://api.serply.io/mcp`. Point Claude Code, Claude
Desktop, Cursor, or any other MCP client at it with your API key and the
agent gets fourteen tools for searching the live web - Google, Bing, News,
Scholar, Video, Jobs, Maps, product listings, and Reddit - plus a scraper
that returns any public page as markdown. There is nothing to install,
deploy, or keep running: the server is hosted, and a tool call bills against
the same credits as the [REST API](/docs).

## Server address and authentication

| | |
|---|---|
| **Endpoint** | `https://api.serply.io/mcp` |
| **Transport** | Streamable HTTP |
| **Auth** | `X-Api-Key` header |

Get an API key at [app.serply.io/users/sign_up](https://app.serply.io/users/sign_up) -
new accounts include 2,500 free credits, no card required. The same key works
for the REST API and the MCP server interchangeably. See the
[Authentication guide](/docs/guides/authentication) for key handling best
practices.

## Connect Claude Code

One command:

```bash
claude mcp add --transport http serply https://api.serply.io/mcp \
  --header "X-Api-Key: YOUR_API_KEY"
```

That is the whole install. Then just ask - "what shipped in the httpx
changelog this month?" - and Claude picks the right tool.

## Connect Claude Desktop

Claude Desktop's config file does not pass custom headers to remote servers,
so bridge through [mcp-remote](https://www.npmjs.com/package/mcp-remote),
which runs the HTTP connection behind a local stdio server. Add this to
`claude_desktop_config.json` (on macOS:
`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "serply": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://api.serply.io/mcp",
        "--header", "X-Api-Key:YOUR_API_KEY"
      ]
    }
  }
}
```

Restart Claude Desktop and the fourteen tools appear in the tools menu.

## Connect Cursor

Cursor speaks streamable HTTP directly. Add to `.cursor/mcp.json` in your
project (or `~/.cursor/mcp.json` for every project):

```json
{
  "mcpServers": {
    "serply": {
      "url": "https://api.serply.io/mcp",
      "headers": { "X-Api-Key": "YOUR_API_KEY" }
    }
  }
}
```

## Connect any other MCP client

Windsurf, Cline, Zed, and anything else that speaks stdio can use the same
`mcp-remote` bridge shown for Claude Desktop above - the JSON block is
identical, only the config file location changes. Clients with native
remote-MCP support connect to `https://api.serply.io/mcp` directly with the
`X-Api-Key` header.

## The fourteen tools

Every tool name and parameter below is read off the live server via
`tools/list`.

| Tool | Parameters | What it returns |
|---|---|---|
| `google_search` | query, num, start, proxy_location, device | Organic Google results - the default reach for anything factual or recent |
| `bing_search` | query, proxy_location, device | Bing organic results, plus text ads and shopping ads Google does not return |
| `google_news_search` | query, ceid, proxy_location, device | News coverage with publisher and date; `ceid` picks the country edition |
| `google_video_search` | query, num, proxy_location, device | Video results - tutorials, demos, news clips |
| `google_scholar_search` | query, num, proxy_location, device | Peer-reviewed papers with authors and citation counts |
| `google_jobs_search` | query, proxy_location, device | Postings from Google's jobs index, which aggregates LinkedIn and Indeed |
| `google_maps_search` | query, num, hl, gl | Local businesses with address, coordinates, rating, phone, and hours |
| `amazon_product_search` | query, proxy_location, device | Product listings with prices and availability |
| `scrape_url` | url, response_type | Any public page as markdown or raw HTML |
| `reddit_subreddit_posts` | subreddit, limit, sort, t, after | A subreddit's post listing |
| `reddit_subreddit_about` | subreddit | Subscriber count, description, and rules |
| `reddit_user_posts` | username, limit, sort, t, after | One account's post history |
| `reddit_post` | post_id, with_comments, sort, max_depth | A single post with its body; add `with_comments` for the thread underneath |
| `reddit_post_comments` | post_id, sort, max_depth | The comment tree with scores, nested to the depth you ask for |

## What the tools return

Every tool except `google_maps_search` returns rendered markdown rather than
JSON - readable by the model as-is, with no parsing step spending context on
brackets. Maps is the exception twice over: it returns a structured object
with a `places[]` array, and it takes `hl`/`gl` locale parameters instead of
`proxy_location`/`device`.

The Reddit tools take names and ids in whatever form you already have:
`r/python` or `python`, `u/spez` or `spez`, `t3_1vfemi1` or `1vfemi1`. A post
id that does not exist comes back as a plain "No post found" answer, not a
tool error, so an agent should not retry it.

## Credits, caching, and errors

A tool call is one API request: 1 credit per successful, uncached request,
billed to the same balance as the REST API. Most endpoints cache for several
minutes, and cached responses cost nothing - so an agent retrying the same
query during a session is free.

`429` means the rate limit was hit; back off and retry. `502` means the
upstream fetch or parse failed - it is transient, so retry once before giving
up. The full error-response reference is in the [Errors guide](/docs/guides/errors).

## FAQ

### Do I need to run or deploy anything?

No. The server is hosted at `https://api.serply.io/mcp`. Registering it is
one config entry; there is no process to keep alive and nothing to update.

### Which MCP clients work with it?

Any client that implements MCP. Clients with remote-server support (Claude
Code, Cursor) connect directly over streamable HTTP; stdio-only clients
(Claude Desktop, Windsurf, Cline) connect through the `mcp-remote` bridge
shown above.

### What does a tool call cost?

The same as the equivalent REST call: 1 credit per successful, uncached
request. New accounts get 2,500 free credits with no card. See
[pricing](/pricing) for plans beyond that.

### Can I build my own MCP server on the Serply API instead?

Yes - the REST API is fully documented and an MCP wrapper is about thirty
lines. There is a working walkthrough in
[Build an MCP Server for Serply Search, News, and Web Scraping](/blog/mcp-server-serply-search-api).
The hosted server exists so you do not have to.

## Related

- [Agent Skill](/docs/guides/agent-skill) - a `SKILL.md` that teaches Claude
  and other Skill-compatible agents both the REST API and this MCP server,
  installable with `npx skills add serply-inc/skills`
- [API Endpoints](/docs) - the full REST reference behind each tool
- [MCP resources vs tools for search](/blog/mcp-resources-vs-tools-search)
  and [a TypeScript MCP server on the Serply API](/blog/mcp-server-typescript-search-tools)
  from the blog