io.github.CodyWatters/riveter
MCP server for Riveter's enrichment, scraping, and monitoring API
Open source Repository Open in the app JSON README (API)
About
MCP server for Riveter's enrichment, scraping, and monitoring API
Details
- Kind
- MCP servers
- Topic
- Cloud & DevOps
- Publisher
- codywatters
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 0.3.0
- Repository state
- sumiu
- Added
- 2026-08-29 03:01:48
- Updated
- 2026-09-13 03:11:25
- Origin id
io.github.CodyWatters/riveter
README
# Riveter MCP Server
An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that connects AI assistants like Claude and Cursor to the [Riveter API](https://riveterhq.com). Run enrichments, build datasets, scrape webpages, manage monitors, and more — directly from your assistant.
Tools are generated dynamically from Riveter's [OpenAPI spec](https://docs.riveterhq.com/openapi.yaml), so they stay up to date automatically.
Two ways to connect:
- **Hosted** — `https://mcp.riveterhq.com/mcp`. Nothing to install. Works from claude.ai, Claude Desktop, Cowork, Claude mobile, ChatGPT, Claude Code, and Cursor.
- **Local (`npx`)** — this npm package, run on your machine over stdio. Use it when your client cannot reach remote servers.
## Setup
### 1a. Hosted server (no API key needed up front)
Add `https://mcp.riveterhq.com/mcp` as a custom connector and click Connect. A browser window opens on Riveter: sign in and click **Allow**. Riveter creates an API key for that connection; it is listed in [Settings → API keys](https://app.riveterhq.com/settings/api), and revoking it disconnects the client.
**Claude Code:**
```bash
claude mcp add --transport http riveter https://mcp.riveterhq.com/mcp
```
Then run `/mcp` and choose Authenticate.
**Cursor:**
```json
{
"mcpServers": {
"riveter": {
"url": "https://mcp.riveterhq.com/mcp"
}
}
}
```
If the client cannot open a browser, pass a key as a header instead: `Authorization: Bearer sk_riv_your_key_here` (Claude Code `--header "Authorization: Bearer sk_riv_..."`, Cursor `"headers": { "Authorization": "Bearer sk_riv_..." }`).
### 1b. Local server (npx)
Get a Riveter API key at [app.riveterhq.com/settings/api](https://app.riveterhq.com/settings/api).
**Claude Desktop** — open the config file:
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
Add the Riveter server:
```json
{
"mcpServers": {
"riveter": {
"command": "npx",
"args": ["-y", "--prefer-online", "riveter-mcp-server@latest"],
"env": {
"RIVETER_API_KEY": "sk_riv_your_key_here"
}
}
}
}
```
**Cursor / Windsurf** — add the same `riveter` entry to your MCP config (e.g. `~/.cursor/mcp.json`).
**Claude Code:**
```bash
claude mcp add riveter --env RIVETER_API_KEY=sk_riv_your_key_here -- npx -y riveter-mcp-server
```
**Codex:**
```bash
codex mcp add riveter --env RIVETER_API_KEY=sk_riv_your_key_here -- npx -y riveter-mcp-server
```
**Keeping the tools current:** the local server loads the API definition once, when your client starts it, and keeps that process running. After Riveter ships an API change, restart your AI client (or the MCP server from its settings page) to load the new tools. `--prefer-online riveter-mcp-server@latest` makes the same restart also pick up new server versions. The hosted server needs no restart; it reloads the API definition every 10 minutes.
## Environment variables
Local (stdio) server — `dist/index.js`:
| Variable | Required | Default | Description |
| ---------------------- | -------- | ----------------------------------------- | -------------------- |
| `RIVETER_API_KEY` | Yes | — | Your Riveter API key |
| `RIVETER_API_BASE_URL` | No | `https://api.riveterhq.com/v1` | API base URL |
| `RIVETER_OPENAPI_URL` | No | `https://docs.riveterhq.com/openapi.yaml` | OpenAPI spec URL |
Hosted (Streamable HTTP) server — `dist/http.js`, deployed by Riveter:
| Variable | Default | Description |
| -------------------------- | ---------------------------------- | -------------------------------------------------------------------- |
| `PORT` | `8080` | Listen port |
| `MCP_PUBLIC_URL` | `https://mcp.riveterhq.com/mcp` | Public URL, exactly as users enter it (RFC 9728 `resource`) |
| `OAUTH_ISSUER_URL` | `https://app.riveterhq.com` | Authorization server advertised in the protected resource metadata |
| `SPEC_REFRESH_INTERVAL_MS` | `600000` | How often the spec is re-fetched; `0` disables |
| `RIVETER_API_BASE_URL`, `RIVETER_OPENAPI_URL` | as above | |
The hosted server holds no API key. It forwards the caller's `Authorization: Bearer ...` header to the API on every call and answers `401` with a `WWW-Authenticate` challenge when the header is missing.
## How it works
On startup, the server:
1. Fetches the OpenAPI spec from `docs.riveterhq.com/openapi.yaml`
2. Parses each endpoint into an MCP tool with typed parameters and annotations (`readOnlyHint` from `GET`, `destructiveHint` from `DELETE` or the spec's `x-mcp-destructive`, `openWorldHint` from the spec's `x-mcp-open-world`)
3. Uses the spec's `info.x-mcp-instructions` as the short server-level `instructions` (the long API overview stays on the docs site)
4. Serves the tools over stdio (local) or Streamable HTTP (hosted)
When the API docs are updated, the local server picks up the changes the next time your assistant launches, and the hosted server re-fetches the spec every 10 minutes — no rebuild or republish needed.
## Development
This package lives in the `riveter` monorepo under `mcp-server/`. From the repo root:
```bash
pnpm --filter riveter-mcp-server test # build + unit + e2e + spec-contract tests
```
The spec-contract tests parse the repo's real `public/api_docs/openapi.yaml` (and the legacy spec), so a spec change that would break tool generation fails CI. To publish: bump the version in `package.json`, `server.json`, and `src/server.ts`, then run `pnpm publish` from `mcp-server/`.
Run the hosted server locally with `pnpm dev:http` (defaults to port 8080; set `MCP_PUBLIC_URL=http://localhost:8080/mcp`). The hosted service is deployed from `Dockerfile` by Render (`mcp-server` in the root `render.yaml`).
## Support
Questions or issues? See the [Riveter API docs](https://docs.riveterhq.com) or contact [support@riveterhq.com](mailto:support@riveterhq.com).
## License
MIT