> For the complete documentation index, see [llms.txt](https://docs.labatlas.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.labatlas.com/mcp-server.md). # MCP Server Lab Atlas exposes a **Model Context Protocol (MCP) server** so AI tools — Claude Code, claude.ai, and any other AI agent — can browse your projects, studies, assays, notes, and tasks the same way a human collaborator would. The MCP server reuses your existing Lab Atlas **API key** for authentication, so there's no separate signup, no OAuth dance, and no second password to manage. This guide walks through getting a key, connecting an AI tool, and using the tools the MCP server exposes. {% hint style="info" %} Lab Atlas MCP is currently available only to Enterprise customers. {% endhint %} {% hint style="warning" %} The MCP server is currently in beta. Endpoints and entities may change over time. {% endhint %} *** ### What MCP gives you Once you connect an AI tool to the Lab Atlas MCP server it can, on your behalf: * Find projects, studies, and assays you have access to. * Pull the latest content of any electronic-lab-notebook note — whether attached to a project, study, assay, or the organization itself. * Read the task list on a study or assay, including status and due dates. * Read the external links, collaborators, teams, keywords, and study collections in your organization. * See which integrations (S3, SharePoint, Benchling, GitLab, etc.) and storage drives are connected. It does **not** currently create, modify, or delete anything in this release. An agent can summarize, search, and cross-reference, but it cannot change your data. *** ### Prerequisites You need an API key. The MCP server uses the exact same key format as the Lab Atlas REST API, so if you already have one for scripting or integrations you can reuse it. To create one: 1. Sign in to your Lab Atlas tenant. 2. Open the user menu in the top-right corner and choose **Account settings**. 3. Select the **API keys** tab. 4. Click **Create new key**, give it a memorable name (e.g. `claude-code-laptop`), and pick an expiration. 5. Copy the value from the modal. It looks like `lak_.`. **This is the only time the full value is shown** — store it somewhere safe. The key inherits your user's permissions and is scoped to your organization. An agent connecting with your key can see exactly what you can see in the web UI, no more and no less. > If you do not see the **API keys** tab, the feature is not enabled for your tenant — contact your administrator. You also need the MCP server URL for your tenant. The path is always `/mcp` (eg. `https://.labatlas.com/mcp` ). *** ### Connect from Claude Code [Claude Code](https://claude.com/claude-code) is Anthropic's terminal-based AI assistant. It manages MCP servers via the `claude mcp` subcommand. ```bash export LABATLAS_API_KEY=lak_xxxxxxxx.xxxxxxxxxxxxxxxxxxxx claude mcp add --transport http labatlas \ https://your-tenant.labatlas.com/mcp \ --header "X-API-KEY: $LABATLAS_API_KEY" claude mcp list # Expect: labatlas ✓ connected ``` The `--transport http` flag selects the **Streamable HTTP** transport, which is what the Lab Atlas server speaks. The `--header` is forwarded with every request. After this, start a Claude Code session as you normally would (`claude`) and the `labatlas` tools will be available. Try: > "Use the labatlas mcp to list my projects." To remove or refresh the registration: ```bash claude mcp remove labatlas ``` *** ### Connect from claude.ai claude.ai (the web app) supports remote MCP servers via the **Connectors** panel. 1. Open **Settings → Connectors**. 2. Choose **Add custom connector** (the exact label may say "Add custom MCP server"). 3. Fill in: * **URL**: `https://your-tenant.labatlas.com/mcp` * **Transport**: HTTP / Streamable HTTP (whichever option the UI offers) * **Custom header**: name `X-API-KEY`, value `lak_xxxxxxxx.xxxxxxxxxxxxxxxxxxxx` 4. Save. The connector should report **Connected**. Once connected, the Lab Atlas tools appear in the tool picker for any conversation, including Projects. *** ### Connect from the Anthropic API If you are building your own agent against the Anthropic API, configure the MCP server in the `mcp_servers` array on the message request: ```json { "mcp_servers": [ { "type": "url", "url": "https://your-tenant.labatlas.com/mcp", "name": "labatlas", "authorization_token": "lak_xxxxxxxx.xxxxxxxxxxxxxxxxxxxx" } ] } ``` The Anthropic API forwards `authorization_token` as `Authorization: Bearer `. Lab Atlas does **not** accept bearer tokens for API key auth, so if the SDK you use does not let you set a custom header, use the explicit `Authorization: ApiKey ` form via a header field instead. Most SDKs support a `headers` map on the MCP server config: ```json { "mcp_servers": [ { "type": "url", "url": "https://your-tenant.labatlas.com/mcp", "name": "labatlas", "headers": { "X-API-KEY": "lak_xxxxxxxx.xxxxxxxxxxxxxxxxxxxx" } } ] } ``` *** ### Available tools The server registers **52 read-only tools** today, grouped by resource: | Resource | Tools | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Projects | `list_projects`, `get_project` | | Studies | `list_studies`, `get_study`, `list_studies_by_project` | | Assays | `list_assays`, `get_assay`, `list_assays_by_study` | | Assay types | `list_assay_types`, `get_assay_type` | | Notes | `list_organization_notes`, `list_project_notes`, `list_study_notes`, `list_assay_notes`, `get_organization_note`, `get_project_note`, `get_study_note`, `get_assay_note` | | Tasks | `list_study_tasks`, `list_assay_tasks`, `get_task` | | External links | `list_project_external_links`, `list_study_external_links`, `list_assay_external_links` | | Collaborators | `list_collaborators`, `get_collaborator` | | Teams | `list_teams`, `get_team` | | Keywords | `list_keywords`, `get_keyword` | | Study collections | `list_study_collections`, `get_study_collection` | | Study relationships | `list_study_relationships` | | Integrations | `list_integrations`, `get_integration` | | Storage drives | `list_storage_drives`, `get_storage_drive` | | Storage folders | `list_project_storage_folders`, `list_study_storage_folders`, `list_assay_storage_folders` | | Shared storage folders | `list_shared_storage_folders`, `get_shared_storage_folder` | | Organization users | `list_organization_users`, `get_organization_user` | | Users | `list_users`, `get_user` | | Activity | `list_activities`, `get_activity`, `list_activities_by_project`, `list_activities_by_study`, `list_activities_by_assay`, `list_activities_by_user` | Listing tools accept optional `page` (zero-indexed) and `size` (max 100) parameters. Look-up tools take a single UUID parameter. The response shape mirrors the JSON returned by the equivalent `GET /api/v1/...` endpoint — see Public-API-Reference.md for field-level docs. You normally do not pick tools by hand. Ask the agent for what you want and let it choose: > "Find every study tagged with the `metabolomics` keyword and summarize the most recent note on each." The agent will plan a call sequence like `list_keywords` → `list_studies` → `list_study_notes` → `get_study_note` and assemble the answer. *** ### Example prompts A few prompts that exercise the read surface: * *"List my active projects and tell me which ones have studies that were updated this week."* * *"In project CPA, summarize the open tasks across all studies and group by assignee."* * *"Pull the latest note from study TID-101 and extract the experimental conditions table."* * *"For every assay in study PPB-101, list its external links and check whether any point to deprecated tools."* * *"Show me which integrations are configured and what storage drives back the project CPA-100."* *** ### Privacy and scope * **Authentication.** Every request authenticates via your API key. The MCP server has no anonymous mode. * **Authorization.** The agent inherits *your* permissions. It cannot see anything you cannot see in the web UI. Cross-organization reads are not possible — the server rejects them with a 404-equivalent error. * **Audit.** Tool calls run as your user and are visible in the same activity feeds and integration audit logs that other API traffic produces. See integration-audit-logging-guide.md for details. * **Data flow.** Tool responses are JSON. They leave Lab Atlas only over the same HTTPS channel that serves the REST API, and only as part of a response to a request your agent made. * **Revocation.** Revoking the API key in the **Account settings → API keys** tab takes effect immediately and stops the agent in mid-conversation if a request is in flight. If you are giving an agent access for a one-off task — say, a Claude Code session on a borrowed laptop — issue a short-lived key (one to seven days) instead of reusing your long-lived one. *** ### Troubleshooting **`SDK auth failed: HTTP 401: Invalid OAuth error response`** You're connecting with the older SSE transport, which Claude Code's SDK does not forward custom headers to. Use `--transport http` (the Streamable HTTP variant) as shown above. **`401 Unauthorized` on a tool call** The key is missing, malformed, revoked, or expired. Generate a fresh key and reconnect. **Tool returns "X not found"** The record is in another organization, or your user doesn't have view permission. The agent treats this as a normal "not found" — it is not a server error. **Tool list is empty** The MCP server is not enabled in your deployment. Ask your administrator to check the `spring.ai.mcp.server.enabled` flag (see MCP-Configuration.md). **Connection seems slow on large pages** Tool list responses are paginated to a max of 100 items. Ask the agent to scope its queries (e.g. by project) rather than scanning the full org. For deeper issues, capture the agent's stderr or the Lab Atlas server logs and share them with your administrator. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.labatlas.com/mcp-server.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.