**English** · [简体中文](README.zh-CN.md)

# qiao

A single-user, self-hosted bridge that exposes a local **stdio** MCP server to
**ChatGPT and Claude** (web + mobile) over HTTPS with OAuth.

MCP servers that speak stdio can only be used locally. To use one from ChatGPT's
or Claude's web/mobile connectors, it must be a public HTTPS endpoint with the
full OAuth dance those connectors expect. `qiao` is that layer — and nothing
more: it is a **100% passthrough** transport + auth front door.

- **Single user, multiple clients.** One owner; connect as many of your own
  devices/clients as you like. They share one backend process by default;
  `per_client_process` gives each its own.
- **100% passthrough.** Whatever tools your backend exposes, `qiao` forwards
  verbatim. It does not parse, filter, or rewrite payloads.
- **Built on [FastMCP](https://gofastmcp.com).** It doesn't reinvent the OAuth or
  transport machinery.
- **You own what you expose.** `qiao` guarantees only *you* can reach your
  backend; it does not sandbox or vet the backend's tools. See `SECURITY.md`.

`qiao` runs its own OAuth authorization server rather than delegating to an
upstream identity provider — see `SECURITY.md` for what that buys and what it
costs.

> **Only ever using ChatGPT?** OpenAI's own
> [Secure MCP Tunnel](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels)
> reaches a local stdio server without any public endpoint of your own, and is
> simpler — follow their docs. `qiao` is for the case it cannot serve: one
> backend, every client.

## Try it

```bash
qiao init                 # write qiao.toml
qiao hash-password        # paste the result into [auth].password_hash
qiao check                # validate before starting
qiao run                  # serve; put a TLS-terminating proxy in front
qiao backup out.db        # copy the OAuth database; safe while running
```

Use `qiao backup` rather than copying the database file — the copy comes back
empty, without an error.

`base_url` in the config must be the **public** URL clients reach — it is what
the OAuth discovery documents advertise.

The full recipe — reverse proxy, tunnel, systemd, and the one invariant that
produces unexplainable 502s when you get it backwards — is in
`docs/deploying.md`.

## Adding it to a connector

Both providers hide custom connectors behind something, and neither says so
clearly. Verified 2026-08-10:

- **ChatGPT** — enable **developer mode** in settings first; there is no way to
  add a custom connector without it.
- **Claude** — add and remove connectors **on the web**. The mobile app can use
  a connector and complete a login, but offers no way to add or delete one.
- **Either** — a connector is account-level. Add it once on the web and it
  appears on your phone; you do not set it up twice.
- **ChatGPT on mobile** — after connecting you may have to attach the connector
  to the conversation by hand. Until you do, the model can list the tools and
  will not call them, which looks exactly like a broken server.

## If these documents are hard going

That is not you. Deploying this touches DNS, certificates, systemd, a reverse
proxy and a tunnel, and explaining all of that from the ground up would take a
book — one the author is not able to write. What is here assumes background you
may not have, and that is a limitation of the writing, not of the reader.

So bring an assistant. Paste a section of `docs/deploying.md` into Claude, GPT,
GLM, Kimi — even Gemini — and ask what the step is doing, or have it adapt a
command to your own machine. They are good at exactly this, and it will save you
some of the copying and pasting besides.