# Use Genomic Intelligence inside Claude, ChatGPT, or your AI agent

Ask natural-language questions over DNA sequences. Genomic Intelligence can
fetch genomic regions, run the **promoter, splice, enhancer, chromatin,
expression, and annotation** models, and return structured biological
predictions — all from an AI assistant. You type *"fetch TP53 and scan it for
promoters"*; the model calls the right tools and shows you ranked hits with
coordinates and scores.

Under the hood this rides the [Model Context Protocol](https://modelcontextprotocol.io)
(MCP): a thin translator that turns each task into a tool your AI host can call,
forwarding to the same REST API documented in the [REST API guide](rest-api.md).

## Choose how you want to try it

Both options below connect your AI chat to the **same Genomic Intelligence MCP
server** — the same six models, the same tools. They differ only in where that
server runs and whether you bring a key:

- **Option A — a hosted server we run for you.** You paste one URL into an AI
  chat that supports custom connectors. Nothing to install, no key, no account
  with us. This is the fastest way to see a real biology result.
- **Option B — a local server you run on your own machine.** You install a small
  program and give it your own API key. This unlocks your full rate limits,
  keeps private sequences on your machine, and records your job history.

| Path | Best for | Setup |
|---|---|---|
| **[A. Hosted MCP server (no setup)](#option-a--hosted-mcp-server-no-setup)** | Seeing a biology result in your existing Claude or ChatGPT, right now | Paste one URL. No key, no install. |
| **[B. Local MCP server (your own key)](#option-b--local-mcp-server-your-own-key)** | Scientists and developers doing real work — higher caps, private sequences, all tools | `uvx gi-mcp` + a `gi_...` key |
| **[C. REST API](rest-api.md)** | Production integrations and pipelines | Auth + HTTP |

Start with Option A to see what GI can do, then move to Option B for sustained
work. You don't need to know any MCP terminology — pick a path and paste a prompt.

## Option A — Hosted MCP server (no setup)

**Best for:** first-time users who want to understand what GI can do before
installing anything or getting a key. This path is for **web AI chats that
support custom MCP connectors** (ChatGPT, Claude, and others below).

We run a Genomic Intelligence MCP server at
**`https://mcp.genomicintelligence.ai/mcp`**. Any AI chat that can add a custom
(remote) MCP server by URL can reach it. Because our hosted server carries a
shared **demo key**, it answers **anonymously** — you add the URL, leave
authentication blank, and start asking questions. No install, no account, no
API key.

> The shared demo key has shared rate limits and is for evaluation, not
> production. Job history is disabled in demo mode, and you're sharing quota with
> other evaluators. For real work — your own caps, private sequences, the full
> tool surface — use [Option B](#option-b--local-mcp-server-your-own-key).

### Which apps can connect

To use Option A, your AI chat needs to support **custom (remote) MCP
connectors** — a setting that lets you add an MCP server by URL. Whether it's
available, and on which plan, varies by platform. The apps below are confirmed
to support it. In every case the server URL is
`https://mcp.genomicintelligence.ai/mcp` and authentication is left empty.

| App | Plan required | Where to add a connector |
|---|---|---|
| **ChatGPT** (web and desktop) | Plus, Pro, Team, Enterprise, or Edu (not the free tier) | Settings → Apps & Connectors → Developer mode |
| **Claude** (claude.ai web and Claude Desktop) | Pro, Max, Team, or Enterprise | Settings → Connectors → Add custom connector |
| **Mistral Le Chat** | All plans (including free) | Settings → Connectors → Add custom connector |
| **Perplexity** | Pro, Max, or Enterprise | Settings → Connectors → Add custom connector |

Two detailed walkthroughs follow — ChatGPT and Claude, the two most common
paths — then a general note for everything else.

### Set it up in ChatGPT

Custom connectors in ChatGPT live behind **Developer mode**, available on paid
plans (Plus, Pro, Team, Enterprise, and Edu — not the free tier). There's no
dedicated Genomic Intelligence GPT yet; instead you add our hosted server as a
custom connector.

1. Open **Settings → Apps & Connectors → Advanced settings** and turn on
   **Developer mode**.
2. Back in **Settings → Apps & Connectors**, choose **Create** (also shown as
   "Add custom connector").
3. Fill in:
   - **Name:** `Genomic Intelligence`
   - **MCP server URL:** `https://mcp.genomicintelligence.ai/mcp`
   - **Authentication:** **No authentication**
4. Acknowledge ChatGPT's custom-connector risk notice and save.
5. Start a new chat. Open the tools/apps menu (**Tools → Use apps**) and toggle
   **Genomic Intelligence** on.
6. Paste a prompt from [Your first prompts](#your-first-prompts).

> On individual Plus and Pro plans, ChatGPT may limit custom connectors to
> read-only tools; Team, Enterprise, and Edu workspaces get the full surface.
> GI's tools return data rather than change anything, so the core fetch-and-predict
> flow works.

### Set it up in Claude (web or Desktop)

Custom connectors are available on Claude's paid plans (Pro, Max, Team, and
Enterprise). The same steps work on claude.ai in a browser and in the Claude
Desktop app.

1. Open **Settings → Connectors** (on the web, the direct link is
   [claude.ai/settings/connectors](https://claude.ai/settings/connectors)).
2. Click **Add custom connector** (the **+** button).
3. Fill in:
   - **Name:** `Genomic Intelligence`
   - **Remote MCP server URL:** `https://mcp.genomicintelligence.ai/mcp`
   - Leave the **Advanced settings** (OAuth) fields empty.
4. Click **Add**.
5. Start a new chat. Click the **+** button near the message box, choose
   **Connectors**, and toggle **Genomic Intelligence** on.
6. Paste a prompt from [Your first prompts](#your-first-prompts).

Claude reaches your connector from Anthropic's cloud, so a public URL like ours
works without any extra network setup.

### Other apps and your own agent

Any client that speaks **Streamable-HTTP MCP** can point at the same URL —
developer tools like Cursor, Windsurf, Zed, and VS Code, and any custom agent
you build. Add `https://mcp.genomicintelligence.ai/mcp` as a remote (HTTP) MCP
server and leave authentication empty to use the demo key. To use your own key
instead, send it as an `Authorization: Bearer gi_...` header (or
`X-GI-Key: gi_...`) — see [Option B](#option-b--local-mcp-server-your-own-key) for
how to get a key.

## Your first prompts

Paste these into a freshly-connected client, in order — simplest first (no
inference), then a real fetch-and-predict workflow.

**1 — Warm up (lists models, no inference):**

> What Genomic Intelligence models are available for expression prediction?

**2 — A real workflow (fetch, then predict):**

> Fetch a 100 kb window around human TP53 from Ensembl and scan it for promoter regions. Show me the strongest hits.

**What "working" looks like:** the assistant calls the **genomic-intelligence**
tools, fetches the sequence from Ensembl, runs promoter prediction, and returns
ranked promoter-like regions with coordinates and scores — not a text guess. If
you see tool calls and coordinate/score output, the connection is live.

**No external fetch needed?** The server ships one curated demo sequence per
task, so you can run a full prediction without touching Ensembl:

> Load the bundled human demo sequence and run promoter prediction on it. Explain the strongest hits.

### One prompt per task

Once connected, these exercise every task plus the composite workflow:

| # | Task | Prompt |
|---|------|--------|
| 0 | warm-up | "What Genomic Intelligence models are available for the expression task?" |
| 1 | promoter | "Fetch a 100 kb window around human TP53 from Ensembl and scan it for promoter regions. Show me the strongest hits." |
| 2 | expression | "Predict HBB expression in K562 cells and explain the biological interpretation." |
| 3 | splice | "Fetch the human HBB gene sequence and predict its splice sites." |
| 4 | enhancer | "Fetch the Drosophila ftz gene and predict enhancer activity." |
| 5 | annotation | "Find the genes in chr8:127,680,000-127,800,000." |
| 6 | composite | "Find the genes in chr8:127,680,000-127,800,000 and predict each one's expression in K562." |

The enhancer model is trained on *Drosophila*, so example 4 uses a fly gene
(`ftz`); the other tasks are human.

## Option B — Local MCP server (your own key)

Here you run the Genomic Intelligence MCP server **on your own machine** and give
it your own API key, instead of using our shared hosted one. It's the same six
models and the same tools — only the location and the key change.

**Who this is for:** scientists, bioinformaticians, and developers doing real
work rather than a first look. If you've tried the [hosted server](#option-a--hosted-mcp-server-no-setup)
and want to go further, this is the next step.

**Why run it locally.** The hosted demo is deliberately limited; a local server
with your own key removes those limits:

- **Your own rate caps.** You no longer share the demo key's small quota with
  every other evaluator — you get the throughput your key is provisioned for
  (see [Limits](reference/limits.md)).
- **Private sequences stay local.** The server reads local FASTA files straight
  from your disk and forwards only what a prediction needs to the API under your
  key — nothing routes through our shared demo principal.
- **Your job history.** Async jobs are scoped to your key, so you can list and
  poll them (job history is turned off in demo mode).
- **The full tool surface**, including tools that are disabled for shared demo
  users.

The local server is a thin protocol translator: it owns no inference and stores
no key on any server, forwarding each request to the API under **your** key.

### Which apps can run a local server

Option A was for web chats. Option B is for hosts that can **launch a local
program** as an MCP server — desktop apps, coding CLIs, and IDEs:

| App | How you add a local server |
|---|---|
| **Claude Desktop** | Edit `claude_desktop_config.json` (or Settings → Developer → Edit Config) |
| **Claude Code** (CLI) | `claude mcp add … -- uvx gi-mcp` |
| **OpenAI Codex CLI** | `codex mcp add …`, or a `[mcp_servers.*]` block in `~/.codex/config.toml` |
| **Cursor** | Settings → MCP, or edit `~/.cursor/mcp.json` |
| **Windsurf / Zed / other MCP hosts** | Point the host at the local command `uvx gi-mcp` |

Detailed walkthroughs for Claude Desktop, Claude Code, and Codex follow; the
pattern for any other host is the same command with `GI_API_KEY` set.

### Step 1 — Get a key

Email **contact@genomicintelligence.ai** for a `gi_...` key; your caps come with
it (see [Limits](reference/limits.md)). The same key works for the
REST API and the MCP server.

### Step 2 — Install `uv`

Every setup below runs the server with [`uv`](https://docs.astral.sh/uv/); its
`uvx` command fetches and runs `gi-mcp` with no manual install. Install `uv`
once:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

### Step 3 — Add GI to your client

In every client the shape is identical: run the command `uvx gi-mcp` with
`GI_API_KEY` set in its environment. Pick your client below.

#### Claude Desktop

1. Open your config file. The quickest route is **Settings → Developer → Edit
   Config**, which opens `claude_desktop_config.json` (macOS:
   `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`).
2. Add the `genomic-intelligence` server (merge into `mcpServers` if the file
   already has other servers):

   ```json
   {
     "mcpServers": {
       "genomic-intelligence": {
         "command": "uvx",
         "args": ["gi-mcp"],
         "env": { "GI_API_KEY": "gi_..." }
       }
     }
   }
   ```

3. **Fully quit and reopen** Claude Desktop — closing the window is not enough;
   the app must restart to pick up the config.
4. Open a new chat and click the tools (**plug/hammer**) icon — you should see
   **genomic-intelligence** listed. Ask *"List the available promoter models"*
   to confirm it responds.

#### Claude Code (CLI)

1. Add the server in one command:

   ```bash
   claude mcp add genomic-intelligence --env GI_API_KEY=gi_... -- uvx gi-mcp
   ```

   Everything after `--` is the command Claude Code launches. By default this is
   **local scope** (this project only). Add `--scope user` to make GI available
   in every project on your machine:

   ```bash
   claude mcp add --scope user genomic-intelligence --env GI_API_KEY=gi_... -- uvx gi-mcp
   ```

2. Verify from the shell with `claude mcp list`, or inside a session run the
   `/mcp` slash command to see **genomic-intelligence** and its status.
3. Ask a prompt from [Your first prompts](#your-first-prompts).

#### OpenAI Codex CLI

Either add it with the CLI:

```bash
codex mcp add genomic-intelligence --env GI_API_KEY=gi_... -- uvx gi-mcp
```

…or add a block to `~/.codex/config.toml` by hand (note the key goes in a nested
`.env` table):

```toml
[mcp_servers.genomic-intelligence]
command = "uvx"
args = ["gi-mcp"]

[mcp_servers.genomic-intelligence.env]
GI_API_KEY = "gi_..."
```

Confirm it registered with `codex mcp list`, then start Codex and ask a prompt
from [Your first prompts](#your-first-prompts).

#### Any other MCP host

Cursor, Windsurf, Zed, or your own agent: add the same JSON block to the host's
MCP config, or point any MCP-capable client at the stdio command `uvx gi-mcp`
with `GI_API_KEY` set in its environment.

Pin a release for reproducibility with `uvx gi-mcp@<version>`; pick up new
releases with `uvx --refresh gi-mcp`.

### Step 4 — Verify

Whichever client you used, it should now list the **genomic-intelligence**
server. Ask *"List the available promoter models"* — it runs the catalog tool
and returns the registry — then work through [the first prompts](#your-first-prompts).
Calls now count against **your** key's caps, not the shared demo's.

## How it works

**The handle pattern.** Genomic sequences are large (expression wants 9,198 bp;
promoter accepts up to 500,000 bp). Round-tripping those through the LLM twice
would blow the context window, so acquisition and prediction are split:

1. An **acquisition** tool fetches/loads a sequence, stores it server-side, and
   returns a short **handle** (`seq_ab12cd34`) plus light metadata, never the
   bases.
2. A **prediction** tool takes that handle; the server resolves the bases
   internally.

Small sequences can still be passed inline. Either way, the bases stay out of
the model's context.

**What's exposed.** The tools group into **acquisition** (fetch from Ensembl, by
coordinates, by local file, inline, or bundled demos), **prediction** (the six
tasks, sync or async-with-progress), a composite **annotation-to-expression
workflow**, plus read-only **resources** (model catalog, task docs, your recent
jobs) and **slash-command prompts** (`gi-promoter-screen`, `gi-expression-screen`).
For the exact, current surface, ask your client *"what tools do you have?"* once
connected — MCP self-describes, so the list matches your running version.

## The underlying API

The MCP server is a convenience layer over the REST contract. To integrate
directly, or to understand error codes, limits, and response shapes:

- [REST API guide](rest-api.md): auth, then sync, then async, with curl and Python.
- [Errors](reference/errors.md): every `error.code`.
- [Limits](reference/limits.md): per-task caps, rate quotas, async TTL.

## Contact

**contact@genomicintelligence.ai**: key issuance, raised caps, bug reports,
anything else.