[christabone]

Rewrites the README's "Connect a client" section as a tested Install section, and adds docs/examples.md with tested example questions for every tool. docs/tools.md is untouched.

README

• Install covers Claude Code through the plugin marketplace, Claude Code without it (claude mcp add at local, user, and project scope, a committed .mcp.json, and a one-off claude -p --mcp-config), Codex (codex mcp add and the config.toml table), Claude.ai and Claude Desktop custom connectors, ChatGPT, and any other MCP client (URL, transport, no auth, 23 tools, a bare curl call).
• What you can ask gives five sample questions and links to docs/examples.md.
• Using the public server covers the data release, the FB2023_04 BLAST database set, the per-IP rate limit (about 2 requests/s with a burst allowance, then HTTP 429), and the fact that /health and /metrics are not public.
• Licence points to the MIT LICENSE and to the BSD-3-Clause notice for the bundled coordinate map.
• docs/deployment.md gets one sentence that points to the examples as a post-redeploy spot check.

How it was tested

Examples. All 47 tool calls in docs/examples.md were run against https://mcp.flybase.org/mcp with JSON-RPC tools/call on 2026-10-13 (FB2026_03). Every one of the 23 tools is covered. Each description quotes an ID or a count from the real response.

Family	Calls run
Identify	resolve, search (gene names, references by year, stock number), validate_ids, list_species
Reports	get_report (gene default, gene sections, allele, stock), batch_download (TSV, plus the field catalogue), get_sequence (protein, upstream flank, region)
Genome	map_features (region, padded ID), cytosearch (subdivision, band), convert_coordinates
Vocabularies	search_vocabulary (anatomy, disease), get_term, entities_for_term (GO genes, DOID alleles, FBbt alleles)
Homepage data	get_orthologs (human, mouse plus zebrafish), get_interactions (physical, genetic), get_gene_groups_and_pathways (x2), get_disease_models (x2), get_stocks (GAL4, provider, balancer symbol)
Expression	rnaseq_profile_search (options, FlyAtlas2, modENCODE development), rnaseq_similar_genes (x2)
BLAST	blast_submit (options, blastp, blastn megablast, tblastn across 3 species), blast_status, blast_results

BLAST job tokens are shown as placeholders.

End-to-end runs with claude -p --strict-mcp-config --mcp-config <http server> --allowedTools "mcp__flybase__*". In all five runs the assistant chose the expected tool.

Prompt	Tools used
"Which human genes are the best orthologs of Drosophila wingless?"	resolve, then get_orthologs species: ["Hsap"]. Answer: WNT1, score 12
"Find fly genes that are highly expressed in adult testis but basically off in the ovary, according to FlyAtlas2."	rnaseq_profile_search with list_options, then with testis ≥ 100 and ovary ≤ 1
"What genes and aberrations are in cytological band 89D?"	cytosearch location: "89D", paged
"I want a GAL4 driver line for wingless. Which stocks can I order?"	resolve, then get_stocks gal4_only: true. Answer: Bloomington 4918
"BLAST this protein fragment against the D. melanogaster polypeptides and tell me what it is: …"	blast_submit, then blast_status, then blast_results. Answer: FBpp0079060 (wg-PA)

Install routes tested, each in an isolated config directory:

• claude plugin marketplace add FlyBase/flybase-ai-tools and claude plugin install flybase@flybase both work non-interactively, and claude mcp list shows the plugin server as Connected. Without SSH keys the clone falls back to HTTPS. The in-session /plugin forms are the documented equivalents and were not run interactively.
• claude mcp add --transport http works at local, user, and project scope. Project scope writes the .mcp.json shown in the README, and the server sits at "Pending approval" until a user approves it.
• codex mcp add flybase --url … writes the [mcp_servers.flybase] url table that the README shows. codex exec called resolve and returned FBgn0284084. It only did so with default_tools_approval_mode = "approve". Without it, exec mode refuses the call ("MCP tool call requires approval, but approval policy is never").
• The README's claude -p command was run as written. --allowedTools is variadic, so the prompt has to come before it. The README says so.
• A single 30-request burst returned 21 × 200 and 9 × 429, which matches the documented limit. /health and /metrics return 404.

Not tested. The Claude.ai, Claude Desktop, and ChatGPT steps follow the vendors' current help pages, which are linked; the UIs were not driven.

markdownlint-cli2 reports no issues for README.md and docs/examples.md with line length and table style off, since the repo wraps at about 110 columns. Every relative link resolves.