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 instead of clicking through the app. 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 rather than sharing one.

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 notes, 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 there is no way to make one that lasts forever. When a key expires, create a new one and paste it into your AI assistant.

You will not be caught off guard. Conspecta emails you two weeks before a key expires and again the day before, and the key's row under Settings → AI & API keys shows Expires soon for its last two weeks. You also get an email whenever a key is created or revoked on your account, so a key you did not make never goes unnoticed.

You can also revoke a key at any time from Settings → AI & API keys. Revoking takes effect immediately, everywhere the key was in use.

Turn off API access for a whole team

If you own or administer a team, Settings → AI & API keys also 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 members and by outside collaborators on its projects.

Nothing is deleted and nothing is revoked. Everyone keeps their keys, the keys keep working in other teams, and turning the switch back on restores everything as it was. Members of a switched-off team see a note in the same place 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 also lists, for each team you own or administer, every key that can currently reach it: whose key it is, whether it can write or only read, whether it reaches all projects or specific ones, and when it was last used. A key limited to another team's projects never appears here, and the secret itself is never shown to anyone.

Revoke next to a key stops it immediately, everywhere it was in use. The key's owner gets an email naming your team, so a dead key is never a mystery, and they can create a new key at any time. Because a key can reach the team through a single project, you may see keys belonging to outside collaborators who are not team members.

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. Many labs run both, using Claude Science for the computational work and Conspecta for the work at the bench, with the samples, images, and notes behind it in one place.

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 version above rather than adapting the Mac one.

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 also has an Add custom connector screen, and it does not work with Conspecta yet. It asks for a web address and then tries to register itself for sign-in, which fails with a message like "Couldn't register with Conspecta's sign-in service." Nothing is wrong with your key or your account, and adding an OAuth Client ID will not help either.

That screen needs the sign-in button we have not built yet. Use the configuration file above instead, and see Which AI Assistants Work for the full picture of what connects today.

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" }
    }
  }
}

Use the user configuration rather than a file inside a project folder, which is also where VS Code handles keys most reliably. VS Code's MCP configuration reference covers the other settings.

Which AI Assistants Work

Conspecta is a standard MCP server, so it is not limited to the AI assistants listed above. 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, including tools that do not exist yet. 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.

Confirmed working today:

• Claude Desktop and Claude Science, through the configuration file
• Copilot Studio, through its API key setting
• Cursor, Claude Code, and VS Code, through their configuration files

Claude in a web browser and the Claude phone app cannot connect yet. Their setup form accepts a web address but has nowhere to put a key, so there is no way to sign in from them. We plan to add a sign-in button that supports them.

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."
• "Add a task to repeat the viability assay next week."
• "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.

That last question is a different kind. Your AI assistant can read this guide, so when you ask how something in Conspecta works it looks the answer up here instead of going from memory, and it gives you the link to the page it read so you can check the rest.

What It Can and Cannot Do

A read-only key answers questions and nothing else. A read and write key can also add and change your lab's data, including samples, notebook pages, figures, tables, image analysis results, and flow cytometry population statistics. It can also start a cytometry analysis, apply one of your saved gating strategies to a set of files, and cluster one file of an analysis on a server, so you can hand it last night's tubes and get counts back without opening the workspace.

No key, of any kind, can delete a project, remove your team, invite people, change billing, or create more keys. Those actions stay in the browser, where you have to be signed in to perform them.

Reading and writing your records uses nothing, but the work your AI assistant hands to Conspecta's servers draws on your team's compute usage, exactly as it would if you ran it yourself. There are three kinds: running an image analysis, counting the populations in a flow analysis, and clustering a file. Counting populations uses one per file. A clustering run uses 1, or 5 for the two heaviest algorithms (DBSCAN and Graph clustering), whatever the file's size, the same as the same run started from the workspace. Reading a finished run back is free. Applying a gating strategy is also free, because it reads only each file's short header, never the events. 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 as you, not as a separate account. A notebook page it writes or a sample it updates looks exactly like one you created yourself, and it appears under your name in activity and history. Treat what it does as your own work, because that is how your lab will read it.

Notebook pages and figures it creates start with a status of Draft, the same status you would pick yourself in the app. That is a label on the resource, not an approval step, so review what it made before you rely on it.

Your AI Assistant Chooses the Analysis, Conspecta Runs It

When your AI assistant runs an image analysis, counts the populations in a flow analysis, or clusters a file, it decides which one fits and whether the results are worth keeping. The measurements themselves come from the same validated code that runs when you click through the app, so your AI assistant cannot invent a number.

That holds when it saves them too. To write results into your lab record it passes back a reference to the run Conspecta already performed, never the figures themselves, so what lands in the table is what was measured. In flow cytometry that means the counts, percentages, and channel intensities an AI assistant reports match the ones on screen for the same gates, because both come from the same gating engine.

Applying a gating strategy works the same way. Conspecta reads each file's own detectors and works out where every gate belongs, so a strategy drawn on one panel lands correctly on files that order or name their channels differently. A file whose panel has no channel for a gate does not get that gate, and does not get anything below it in the strategy either. Your AI assistant is told exactly which gates were left out of which file, so ask it to tell you before you read the numbers.

Clustering on a server works the same way, with one wrinkle. It takes minutes rather than seconds, so your AI assistant starts the run and then checks back on it. A pause in the chat is the run working, not the connection failing.

What comes back is how many populations the run found and how many events landed in each, plus the channels it actually clustered on. That is a summary rather than a per-event map, so your AI assistant cannot color a plot directly. What it can do is save the run onto the analysis, so the workspace shows which algorithm ran, on which channels, and what it found, and offers a re-run. The re-run is what colors the plot. The sizes count the events the run used and not every event in the file, because these algorithms subsample, so ask whether a run was subsampled before you quote a size as a population count. A run covers one file of a saved analysis and uses that analysis's own compensation, and its channels are named rather than numbered, so a name the file has no channel for stops the run instead of quietly clustering fewer.

This matters more than it sounds. AI assistants that analyze data for you usually do it by writing code and running it on your machine, which means installing tools, approving code you may not be able to check, and getting a slightly different answer each time the model writes the script differently. Conspecta works the other way around. Nothing gets installed, no code needs approving, and the same analysis run twice gives the same answer, because it is the same analysis your colleagues get when they run it by clicking in the app.

Troubleshooting

Everything fails and the AI assistant cannot 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.

Questions work but nothing can be saved

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

Your AI assistant cannot find something you 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 a whole team's projects are missing rather than one, that team may have turned off API access. The same page shows a note when one of your teams has.

It worked yesterday and stopped 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 went quiet, a team admin may have turned off API access for that team. Settings → AI & API keys tells you when that is the case.