# Sidedoor

**Give your AI agent a side door into any web app you use.**

Use a web app for a couple of minutes. Sidedoor watches the calls it makes to its own API, turns them into tools, and serves them over MCP, so Claude, Codex or Cursor can use the app with your logged-in session. No official API, admin-issued key or hand-written MCP server needed.

[![npm](https://img.shields.io/npm/v/sidedoor-mcp?color=cb3837&logo=npm)](https://www.npmjs.com/package/sidedoor-mcp) [![CI](https://github.com/kemal-arslan/sidedoor/actions/workflows/ci.yml/badge.svg)](https://github.com/kemal-arslan/sidedoor/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Buy Me a Coffee](https://img.shields.io/badge/Buy%20me%20a%20coffee-support-FFDD00?logo=buymeacoffee&logoColor=black)](https://buymeacoffee.com/kemalarslan)

<img src="docs/terminal.png" alt="sidedoor record turns five API calls into four read tools and one write tool, then adds them to Claude Code" width="760" />

## Quick start

Requires Node.js 20+ and Google Chrome (or Edge, or `npx playwright install chromium`).

```bash
# 1. Open the app, log in, and use the features you want your agent to have. Close the window when done.
npx sidedoor-mcp record https://app.example.com

# 2. See how to add it to your agent
npx sidedoor-mcp setup example

# 3. For Claude Code, that prints something like:
claude mcp add sidedoor-example -- npx -y sidedoor-mcp serve example
```

Then ask your agent things like *"list my open projects"* or *"what changed in issue ENG-142?"*.

## How it works

<img src="docs/how-it-works.svg" alt="Record: you use the app and Sidedoor watches its API calls. Infer: calls become typed tools. Serve: your agent uses them over MCP with your session." width="760" />

1. **Record.** `sidedoor record <url>` opens a real browser window with its own persistent profile, so you log in once. Every `fetch`/XHR call the app makes is recorded. You can also export a HAR file from your usual browser and run `sidedoor import`.
2. **Infer.** Calls are grouped into endpoints: `/projects/42` and `/projects/43` become `GET /projects/{projectId}`. Query parameters, request bodies and responses are turned into JSON Schemas from the real traffic. GraphQL operations become one tool each (`Viewer`, `CreateIssue`), including batched and persisted queries. Analytics, telemetry, pages and assets are dropped. Tools get readable names: `list_projects`, `get_project`, `create_project`, `close_issue`.
3. **Serve.** `sidedoor serve <app>` is an MCP server (stdio). Each tool call replays the request against the app's API with your cookies and auth headers, and returns the response to the agent. Cookies the server rotates are saved, so sessions keep working.

`sidedoor generate` is deterministic, and `~/.sidedoor/apps/<app>/openapi.json` gives you an OpenAPI 3.1 document of everything that was found.

## Safety and privacy

- **Read-only by default.** Tools that change data (POST, PUT, PATCH, DELETE, GraphQL mutations) are only exposed with `--allow-writes`, and are marked as destructive or not for your MCP client.
- **Credentials stay on your machine.** Cookies and auth-like headers (`Authorization`, CSRF tokens, API keys) are stored in `~/.sidedoor/apps/<app>/session.json` with `600` permissions, and never in the capture, the tool specs or the OpenAPI file. Sidedoor only talks to the app itself.
- **No bot-protection bypass.** The recording browser is a normal automated browser. If a site refuses it, or blocks sign-in (some Google logins do), export a HAR from your own browser instead.
- **App content is data, not instructions.** The server tells the agent to treat responses that way. Still, only connect apps whose content you trust your agent to read.
- **Your accounts, your responsibility.** Use Sidedoor with accounts you own, for your own automation, and respect each service's terms. Private APIs can change without notice; run `sidedoor refresh <app>` to record again.

Your agent's model provider sees tool descriptions and responses, as with any MCP server.

## Commands

| Command | What it does |
| --- | --- |
| `sidedoor record <url> [--name app]` | Browse and record; logins persist in the app's profile |
| `sidedoor import <file.har> [--name app] [--url start-url]` | Build tools from a HAR exported from your browser |
| `sidedoor refresh <app>` | Log in again or record more features; keeps what you have |
| `sidedoor tools <app>` | List tools and their descriptions |
| `sidedoor setup <app> [--allow-writes]` | Print config for Claude Code, Codex, Cursor and other MCP clients |
| `sidedoor serve <app> [--allow-writes] [--only a,b]` | Run the MCP server over stdio |
| `sidedoor generate <app>` | Rebuild tools from what was recorded |
| `sidedoor list` / `sidedoor remove <app>` | Manage recorded apps |

Options: `--browser auto|chrome|msedge|chromium`, `--all-hosts` (keep API calls to other domains too), `SIDEDOOR_HOME` to move the data directory.

### Importing a HAR file

In Chrome or Edge: open DevTools → **Network**, reload the app and use it, then right-click a request → **Save all as HAR (with sensitive data)**. The "sensitive data" part includes your cookies, which the tools need. Then:

```bash
npx sidedoor-mcp import ~/Downloads/app.example.com.har --name example
```

Delete the HAR file afterwards: it contains your session.

## Limitations

- HTTP APIs only: WebSockets, server-sent events and streaming responses are not replayed.
- Requests signed per call (HMAC, timestamps, rotating nonces) and very short-lived tokens refreshed by app code won't replay. `sidedoor refresh` helps with the second.
- File uploads, CAPTCHAs and multi-step flows are out of scope.
- Endpoint grouping is heuristic. If two things got merged or split oddly, record a bit more and run `sidedoor generate`.

## Development

```bash
npm install
npx playwright-core install chromium   # for the end-to-end tests
npm test            # unit tests, plus end-to-end tests that log into a local app in Chromium,
                    # record it, and drive the MCP server with a real MCP client
npm run typecheck
npm run build
npm run dev -- --help
```

## Support

Sidedoor is free and open source. If it saved you from writing an MCP server, you can [buy me a coffee](https://buymeacoffee.com/kemalarslan).

## License

[MIT](LICENSE)