docs: install instructions for each client and tested examples

README.md

@@ -8,17 +8,141 @@ Tools for using FlyBase data from AI assistants.
 
 The server's tools and their arguments are listed in [docs/tools.md](docs/tools.md).
 
-## Connect a client
+## Install
 
-- Claude Code: `claude mcp add --transport http flybase https://mcp.flybase.org/mcp`
-- Codex: `codex mcp add flybase --url https://mcp.flybase.org/mcp`
-- Claude.ai and Claude Desktop: Settings, Connectors, add a custom connector with the URL above.
-- ChatGPT: Settings, Connectors, add an MCP server with the URL above.
+The server is public at `https://mcp.flybase.org/mcp`. It speaks the Model Context Protocol over Streamable
+HTTP and needs no account, key or login. Pick your client below.
 
-The server's 23 tools cover identifying symbols and IDs, reports, batch downloads, the genome (sequence,
-features in a range, cytology, release 5 to 6 coordinates), controlled vocabularies, homepage data (orthologs,
-gene groups, disease models, stocks, interactions), RNA-seq expression, and BLAST. Each is described in
-[docs/tools.md](docs/tools.md).
+### Claude Code, through the plugin marketplace
+
+Inside a Claude Code session:
+
+```text
+/plugin marketplace add FlyBase/flybase-ai-tools
+/plugin install flybase@flybase
+```
+
+The same two steps work from a shell:
+
+```bash
+claude plugin marketplace add FlyBase/flybase-ai-tools
+claude plugin install flybase@flybase
+```
+
+The plugin installs at user scope and registers the server. `claude mcp list` then shows
+`plugin:flybase:flybase: https://mcp.flybase.org/mcp (HTTP) - ✔ Connected`. Plugin tools are named
+`mcp__plugin_flybase_flybase__<tool>`. Skills will ship in the same plugin later.
+
+### Claude Code, without the plugin
+
+```bash
+claude mcp add --transport http flybase https://mcp.flybase.org/mcp
+```
+
+That adds the server for the current project on your machine only. Add `--scope user` for every project.
+To share it with everyone who clones a project, use `--scope project`, or commit this `.mcp.json` at the
+project root:
+
+```json
+{
+  "mcpServers": {
+    "flybase": {
+      "type": "http",
+      "url": "https://mcp.flybase.org/mcp"
+    }
+  }
+}
+```
+
+Claude Code asks each user to approve a project's `.mcp.json` servers the first time it starts there.
+For a one-off non-interactive run, save the same JSON as `flybase.json` and pass it in. Put the prompt
+before `--allowedTools`, which takes a list and would otherwise swallow it:
+
+```bash
+claude -p "What is the FlyBase ID for wingless?" --mcp-config flybase.json --allowedTools "mcp__flybase__*"
+```
+
+### Codex
+
+```bash
+codex mcp add flybase --url https://mcp.flybase.org/mcp
+```
+
+Or add this to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.flybase]
+url = "https://mcp.flybase.org/mcp"
+```
+
+`codex exec` with an approval policy of `never` refuses MCP tool calls that need approval. The tools only
+read FlyBase data (`blast_submit` starts a search job and nothing else), so for scripted runs you can
+approve them up front. Add this line under the existing `[mcp_servers.flybase]` table, below its `url`
+line (do not repeat the table header):
+
+```toml
+default_tools_approval_mode = "approve"
+```
+
+### Claude.ai and Claude Desktop
+
+Add a custom connector: open Settings, then Connectors, choose "Add custom connector", paste
+`https://mcp.flybase.org/mcp`, and leave the OAuth fields empty. Free plans allow one custom connector. On
+Team and Enterprise plans an owner adds the connector for the organization first, then each member connects. Enable it per chat from the "+" menu under Connectors. See
+Anthropic's [custom connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).
+
+### ChatGPT
+
+Open ChatGPT's Plugins page (chatgpt.com/plugins), choose the plus button, then "Add custom MCP server". Give
+it a name such as FlyBase, choose "Public endpoint" and enter `https://mcp.flybase.org/mcp`, and set no
+authentication. Confirm the warning and choose "Create as a plugin". In a new chat, type `@` and pick it.
+Workspace policies decide whether custom servers are allowed, and older accounts reach the same form through
+developer mode under Settings, Apps. OpenAI's
+[connect from ChatGPT guide](https://developers.openai.com/apps-sdk/deploy/connect-chatgpt) has the current
+steps.
+
+### Any other MCP client
+
+| Setting | Value |
+|---|---|
+| URL | `https://mcp.flybase.org/mcp` |
+| Transport | Streamable HTTP (JSON-RPC over `POST`) |
+| Authentication | none |
+| Tools | 23; they read FlyBase data and never change it |
+
+`initialize` is optional, so a bare `tools/call` works:
+
+```bash
+curl -s https://mcp.flybase.org/mcp \
+  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"resolve","arguments":{"query":"wingless"}}}'
+```
+
+## What you can ask
+
+Ask in plain language. For example:
+
+- "What is the best human ortholog of wingless?"
+- "Which genes are highly expressed in adult testis but off in the ovary?"
+- "What genes and aberrations are in cytological band 89D?"
+- "I want a GAL4 driver for wingless. What can I order?"
+- "BLAST this protein fragment against D. melanogaster polypeptides and tell me what it is."
+
+[docs/examples.md](docs/examples.md) has tested questions for every tool, with the call the assistant makes
+and what comes back. The server's 23 tools cover identifying symbols and IDs, reports, batch downloads, the
+genome (sequence, features in a range, cytology, release 5 to 6 coordinates), controlled vocabularies,
+homepage data (orthologs, gene groups, disease models, stocks, interactions), RNA-seq expression, and BLAST.
+Each is described in [docs/tools.md](docs/tools.md).
+
+## Using the public server
+
+- **Data release.** Every result names the FlyBase release it came from, currently FB2026_03.
+- **BLAST databases.** BLAST searches the archived FB2023_04 database set, so BLAST results can lag the rest of
+  the server. Each `blast_submit` response says so.
+- **Rate limit.** Each client IP gets about 2 requests per second, with a short burst allowance. Requests over
+  the limit get HTTP 429. One assistant session stays well under it. Please be polite with scripts: pause
+  between calls and use `batch_download` for long ID lists.
+- **Only `/mcp` is public.** `/health` and `/metrics` are intentionally not exposed and return 404.
 
 ## BLAST
 
@@ -34,3 +158,10 @@ See `docs/deployment.md` for running the server and `mcp/README.md` for the crat
 
 Private-side handoff: [docs/handoff-private-side.md](docs/handoff-private-side.md) lists what a host must provide
 (database, runtime role, release runbook step, proxy and CDN requirements, and the BLAST job API contract).
+
+## Licence
+
+The code in this repository is under the MIT License; see [LICENSE](LICENSE). The bundled release 5 to 6
+coordinate map, `mcp/data/coordinates/dmel_r5_to_r6.tsv`, is derived from FlyBase's published map and
+carries its BSD-3-Clause notice in
+[mcp/data/coordinates/LICENSE.bulkfile-scripts](mcp/data/coordinates/LICENSE.bulkfile-scripts).

docs/deployment.md

@@ -74,7 +74,8 @@ Each pooled connection sets `default_transaction_read_only = on`, a 10 s `statem
 `search_path` starting with `mcp`. The server has no write path.
 
 For each release: restore the dump, run `migrate`, bump `FLYBASE_RELEASE`, redeploy, and run the live and
-conformance test suites against the new database.
+conformance test suites against the new database. The calls in [examples.md](examples.md) make a quick manual
+spot check after a redeploy; their quoted IDs and counts are from FB2026_03, so expect counts to move.
 
 The integration tests apply migrations only when the startup check fails, or when `FLYBASE_TEST_MIGRATE=1`
 asks for a rebuild. Rebuilding takes exclusive locks, so do not point a test run with that flag at a