Connect Your AI Assistant

Conspecta can be connected to an AI assistant like Claude, so you can ask questions about your lab in plain language. Ask what arrived last week, have it write up a notebook page from your results, or have it run an image analysis and save the numbers to your project.

Your AI assistant reads and writes your lab through your own account. It can never see more than you can see, and everything it does is recorded as your own work.

What You Need

You will also need an AI assistant that can hold a key. See Which AI Assistants Work below before you start.

Create a Key

A key is how your AI assistant proves it is you. Keys are personal, so create your own and keep it to yourself.

1. Open Settings → AI & API keys.
2. Give the key a name you will recognize later, like the name of the computer you are setting up.
3. Choose Read only or Read and write. Read only lets your AI assistant answer questions. Read and write also lets it create and revise notes and image analysis templates, and create figures, tables, samples, and image analysis results.
4. Optionally limit the key to specific projects. A key limited this way can never reach anything else, even if you can.
5. Click Create key.

Treat the key like a password. Anyone holding it can read your lab.

Keys Expire

Every key stops working one year after you create it, and none can be made to last longer. When one expires, create a new key and paste it into your AI assistant.

Conspecta emails you two weeks before a key expires and again the day before, and the key's row shows Expires soon for those two weeks. You also get an email whenever a key is created or revoked on your account.

Revoke a key at any time from Settings → AI & API keys. It stops working immediately, everywhere it was in use.

Turn off API access for a whole team

If you own or administer a team, Settings → AI & API keys shows a Team access card with a switch for each team you manage. Turning a team off immediately blocks every key from that team's projects, including keys held by outside collaborators.

Nothing is deleted or revoked. The keys keep working in other teams, and turning the switch back on restores everything. Members see a note on the same page explaining why their AI assistant stopped answering about that team's work.

See and revoke every key that can reach your team

The same page lists every key that can reach each team you own or administer, with whose it is, whether it can write, which projects it reaches, and when it was last used. The secret itself is never shown. A key can reach a team through a single project, so keys belonging to outside collaborators can appear here.

Revoke stops a key immediately, everywhere it was in use. Its owner gets an email naming your team, and can create a new key at any time.

Set Up Your AI Assistant

Setup instructions with your key already filled in appear right after you create it. They are repeated here for reference. Replace sk_live_YOUR_KEY with your own key.

Claude Desktop

Claude Desktop reads its connection settings from a configuration file, which takes about a minute to edit. Anthropic's guide to local MCP servers on Claude Desktop walks through the same file if you want their version.

Claude Science, Anthropic's desktop workbench for computational biology, connects the same way.

On Mac

The quickest way to open the file is Settings → Developer → Edit Config inside Claude, which creates it if you do not have one yet and opens the folder it lives in.

The file itself is here:

~/Library/Application\ Support/Claude/claude_desktop_config.json

The backslash escapes the space in Application Support, so that path can be pasted into a terminal as it is written.

Add:

{
  "mcpServers": {
    "conspecta": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://api.conspecta.bio/api/v1/mcp",
        "--header", "Authorization: Bearer sk_live_YOUR_KEY"
      ]
    }
  }
}

Fully quit and reopen Claude, because it reads the file only at startup.

On Windows

Open %APPDATA%\Claude\claude_desktop_config.json and add:

{
  "mcpServers": {
    "conspecta": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://api.conspecta.bio/api/v1/mcp",
        "--header", "Authorization:${AUTH}"
      ],
      "env": { "AUTH": "Bearer sk_live_YOUR_KEY" }
    }
  }
}

Fully quit and reopen Claude, because it reads the file only at startup.

Windows puts the key in a separate env setting, and there is no space after the colon in Authorization:${AUTH}. The single-line form used on Mac loses that space on Windows, so copy the Windows version above as written.

On Linux

Open ~/.config/Claude/claude_desktop_config.json and add the same block shown for Mac. Then fully quit and reopen Claude, because it reads the file only at startup.

Anthropic's Linux app is newer than the Mac and Windows ones and covers Ubuntu 22.04 and Debian 12 and later. If you'd rather not run it, Claude Code, Cursor, and VS Code connect the same way on Linux as anywhere else, and are covered below.

If You Tried the Add Custom Connector Screen

Claude Desktop's Add custom connector screen does not work with Conspecta yet. It asks for a web address, then fails with a message like "Couldn't register with Conspecta's sign-in service." Your key and account are fine, and an OAuth Client ID will not help. That screen needs a sign-in button we have not built yet, so use the configuration file above.

Copilot Studio

On your agent's Tools page, choose Add a tool → New tool → Model Context Protocol, then fill in:

Server URL       https://api.conspecta.bio/api/v1/mcp
Authentication   API key
Type             Header
Header name      Authorization
API key          Bearer sk_live_YOUR_KEY

The key value includes the word Bearer and a space before your key. Microsoft's guide to adding an existing MCP server covers the rest of the wizard.

Cursor

Add this to ~/.cursor/mcp.json, or see Cursor's own MCP documentation:

{
  "mcpServers": {
    "conspecta": {
      "url": "https://api.conspecta.bio/api/v1/mcp",
      "headers": { "Authorization": "Bearer sk_live_YOUR_KEY" }
    }
  }
}

Claude Code

Run this in a terminal:

claude mcp add --transport http --scope user conspecta \
  https://api.conspecta.bio/api/v1/mcp \
  --header "Authorization: Bearer sk_live_YOUR_KEY"

Check it worked with claude mcp list, which should show conspecta ✓ Connected. Remove it later with claude mcp remove conspecta. Anthropic documents the full command in Connect Claude Code to tools via MCP.

VS Code

Open the Command Palette, run MCP: Open User Configuration, and add:

{
  "servers": {
    "conspecta": {
      "type": "http",
      "url": "https://api.conspecta.bio/api/v1/mcp",
      "headers": { "Authorization": "Bearer sk_live_YOUR_KEY" }
    }
  }
}

Put this in your user configuration, where VS Code handles keys most reliably, and keep it out of files inside a project folder. VS Code's MCP configuration reference covers the other settings.

Which AI Assistants Work

Conspecta is a standard MCP server, so anything that can connect to a remote MCP server over streamable HTTP and let you set an API key or an Authorization header will work. The setup is always the same two things: the address https://api.conspecta.bio/api/v1/mcp, and your key sent as Authorization: Bearer sk_live_YOUR_KEY.

We plan to add a sign-in button that supports Claude in a browser and the Claude phone app.

If your AI assistant is not listed and you are not sure whether it fits, ask us and we will tell you.

What You Can Ask

Once connected, ask in plain language. Some things people ask on the first day:

• "What did I work on last week?"
• "Which samples in the melanoma project are running low?"
• "Summarize my notebook pages about the CRISPR knockouts."
• "What did we order from Thermo last month, and has it arrived?"
• "Measure what fraction of each of these images is covered by stain."
• "What percentage of cells are CD8+ across the twelve tubes in Tuesday's run?"
• "Write up a notebook page from the image analysis I ran yesterday."
• "Write up Tuesday's experiment, link the samples it used, and embed the counts table."
• "Tighten the Results paragraph on Tuesday's page, and change the viability to 88%."
• "Add a task to repeat the viability assay next week."
• "Do we already have this insert? Here is the sequence."
• "Show me bases 1200 to 1500 of pLenti-GFP, and tell me whether the insert is in frame."
• "Find the human TP53 reference sequence in GenBank and add it to this project."
• "What is this contaminating band? Here are the bases I read off the gel."
• "How do I set up a freezer with racks and boxes?"

Your AI assistant works in one project at a time, so tell it which project you mean if you have several. Your lab's storage locations and supplier list are shared across every project.

Your AI assistant can also read this guide. When you ask how something in Conspecta works, as in the last question above, it answers from these pages and gives you the link to the page it read, so you can check the rest.

What It Can and Cannot Do

A key can never do more than you can do. If you lose access to a project, every key you hold loses it too, from its next request.

A read-only key answers questions about everything below. Anything that changes your lab, starts a run, or sends a sequence to NCBI needs a read and write key.

Three kinds of request leave Conspecta for public reference databases. Nothing about you, your lab, or your project goes with any of them, and your own sequences stay where they are unless you ask for one to be sent.

• A search sends the words you searched for to NCBI or UniProt.
• Fetching a published record sends its accession number to the database that holds it.
• A BLAST search sends the sequence you give it to NCBI, and it cannot be taken back. Your assistant should ask you first. Give it only the stretch in question. It tells you how many bases it sent. The search takes a few minutes, and your assistant reports it as still running until it finishes.

No key, of any kind, can:

• delete a project or remove your team
• invite people or change billing
• create more keys
• approve a record, sign off on your work, or accept a run

Those stay in the browser, where you have to be signed in.

Reading and writing your records uses nothing. Work your AI assistant hands to Conspecta's servers draws on your team's compute usage at the same rate as when you run it yourself.

Compute usage has the numbers, and Settings → Usage lists each run your AI assistant started under your name.

Everything It Does Is Recorded As Yours

Your AI assistant acts through your own account. A notebook page it writes or a sample it updates appears under your name in activity and history, with a note that it came from your assistant, and your lab will read it as your work.

A figure it creates starts as Draft, and a notebook page it writes reads Draft until it has a published version. Draft is only a label, so review what it made before you rely on it.

A figure it creates is shared with the project. Ask for a private working copy to keep one to yourself, and ask for it to be shared later.

Where the Numbers Come From

Your AI assistant decides which image analysis or flow run fits and whether the results are worth keeping. The measurements come from the same validated code that runs when you click through the app, so it cannot invent a number, and the same run gives the same answer your colleagues get in the app.

Clustering and an image analysis over a set take minutes, so a pause in the chat means the run is still working. A team runs one image set at a time, and an image analysis that uses a neural-network detector runs only as a set.

Before you read its numbers, ask:

• How did the checks come out? A run comes back with the checks the workspace shows, such as which control images landed inside their ranges and how many of your ground truth marks it found. A blank well that counted 40, or a run that found 60 of your 120 cells, tells you what the rest of the numbers are worth.
• Which gates did it leave out of which file? A gating strategy lands correctly on files that order or name their channels differently. A file with no channel for a gate skips that gate and everything below it.
• Was the clustering subsampled? These algorithms subsample, so check before you quote a size as a population count. A clustering run reports how many populations it found and how many events landed in each, and saved onto the analysis, a re-run colors the plot.

Troubleshooting

Why can't my AI assistant reach Conspecta?

Usually the key is wrong, expired, or revoked. It can also mean your plan lapsed or access was turned off for your account. Create a fresh key, and check your plan under Settings → Subscription.

Why can it answer questions but not save anything?

The key was created read only. Create a new one with read and write access, then update your AI assistant's settings.

Why did my AI assistant stop making changes partway through?

An assistant that makes far more changes in an hour than a person would ask for stops and tells you what it changed and what is left, so you can check the work. Everything it saved stays saved, it can still read and answer questions, and it can carry on within the hour.

Why can't my AI assistant find something I know exists?

Check whether the key was limited to specific projects when you created it. Settings → AI & API keys lists which projects each key can reach.

If every project in a team is missing, that team may have turned off API access. The same page shows a note when one of your teams has.

Why did it work yesterday and stop today?

Keys last a year. The expiry date is listed next to each key, an expired key is marked as such in the list, and a key inside its last two weeks shows Expires soon. Check your inbox too, because the expiry warnings Conspecta sends name the key that is about to stop working.

If only one team's projects stopped answering, a team admin may have turned off API access for that team. Settings → AI & API keys shows a note when that is the case.