Skip to content

Connecting AI Assistants to AbLead via MCP

AbLead provides direct, secure integration with external AI assistants—including Google Spark / Gemini, Anthropic Claude (Claude.ai, Claude Desktop, and Claude Code), and custom LLM agents—using the open Model Context Protocol (MCP) and OAuth 2.0.

Through this integration, your AI assistant connects directly to AbLead's bioinformatics and engineering engine. It can query discovery campaigns, retrieve IMGT-annotated sequences, decompose developability penalties, calculate 3D surface patches, execute humanization algorithms, simulate de-risking mutations, and stage optimized antibody variants—all from natural language conversations.

Data Privacy & AI Client Confidentiality

Data transfer between AbLead and your AI assistant is encrypted and authenticated securely in transit when OAuth 2.0 is used (protecting your connection without exposing static plaintext credentials). However, when connecting external AI assistants (such as Google Spark / Gemini, Anthropic Claude, or custom LLM clients) to AbLead via MCP, antibody sequence data, analytical scores, and project metadata are transmitted to the external AI client to fulfill your queries and design requests.

Before connecting any AI tool or analyzing proprietary campaigns, verify that your AI client and provider's terms of service, enterprise agreements, and privacy configurations keep your data strictly private (e.g., verifying zero data retention and confirming that your proprietary sequences and analytical results are never used for AI model training or retained in logs).

Core Workflow: Adding AbLead to Your AI Assistant

Regardless of which AI client you use, connecting AbLead follows a standard four-step workflow powered by OAuth 2.0:

1. Sign In to AbLead

Ensure you have an active user account and are signed in to AbLead. Your external AI assistant will operate strictly under your personal user permissions and will only be able to view or modify projects that you own or that have been explicitly shared with you.

2. Add the Tool to Your AI Assistant

In your AI assistant's interface, navigate to its Tools, Apps, Extensions, or Integrations configuration menu, choose to add a Model Context Protocol (MCP) server, and provide the AbLead MCP endpoint URL:

https://ablead.ketchemconsulting.com/mcp

3. Authorize via OAuth

When you connect the tool, your AI client initiates a secure OAuth 2.0 authorization handshake:

  1. A browser window or popup will open displaying the branded AbLead Authorization screen.
  2. Confirm the user account you wish to link.
  3. Review the requested permissions (accessing project summaries, running analytical evaluations, and staging candidate designs).
  4. Click Authorize (or Allow).
  5. The authorization server redirects back to your AI assistant with a secure authorization code, establishing a token-authenticated connection.

Alternative (Personal Access Tokens): For developer tools or desktop environments that do not support automated browser-based OAuth redirects, you can generate a Personal Access Token (PAT) from your AbLead User Profile & Settings under AI & Model Context Protocol (MCP) Integrations and supply it as an Authorization: Bearer <token> header.

4. Enable Tools in Your Chat Session

Once authorized, your AI assistant automatically negotiates protocol capabilities and discovers the complete suite of 35 AbLead discovery, library, and engineering tools. Verify that the AbLead tool is toggled Active or enabled for your current chat, workspace, or project session.

Client-Specific Setup Instructions

Google Spark / Gemini

Google Gemini (gemini.google.com/apps) supports automated client onboarding using RFC 7591 Dynamic Client Registration:

  1. Navigate to Google Gemini Apps / Extensions at https://gemini.google.com/apps.
  2. Click Add App or Add Custom Extension.
  3. Select Model Context Protocol (MCP) as the integration type.
  4. Enter the AbLead server URL:
https://ablead.ketchemconsulting.com/mcp
  1. Gemini automatically discovers the authorization endpoints from /.well-known/oauth-authorization-server and registers its credentials with AbLead.
  2. When the AbLead consent screen appears, click Authorize Google Gemini.
  3. The connection completes automatically, enabling AbLead tools directly in your Gemini and Google Spark prompts.

Method B: Pre-Configured Manual Credentials

If your Gemini interface prompts for explicit OAuth client credentials:

  1. Enter the pre-configured parameters:

  2. Client ID: gemini-mcp

  3. Client Secret: ablead_secret

  4. MCP Server URL: https://ablead.ketchemconsulting.com/mcp

  5. Click Connect and approve the authorization prompt when redirected to AbLead.

Anthropic Claude

AbLead integrates with Claude through Claude.ai Custom Connectors, Claude Desktop, and Claude Code:

Claude.ai Custom Connectors

  1. In Claude.ai, open Settings > Integrations (or Custom Connectors).
  2. Click Add Connector and select Model Context Protocol.
  3. Enter the server URL:
https://ablead.ketchemconsulting.com/mcp
  1. Claude will detect the authentication requirement via AbLead's RFC 9728 WWW-Authenticate challenge and open the OAuth consent screen.
  2. Log in to AbLead and click Authorize.

Claude Desktop

Claude Desktop natively connects to remote HTTP MCP servers and supports automatic browser-based OAuth:

  1. Open your Claude Desktop configuration file:

  2. macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  3. Windows: %APPDATA%\Claude\claude_desktop_config.json

  4. Add the AbLead server under mcpServers using its endpoint URL:

{
  "mcpServers": {
    "ablead": {
      "url": "https://ablead.ketchemconsulting.com/mcp"
    }
  }
}
  1. Launch or restart Claude Desktop.
  2. Claude Desktop connects to AbLead, detects the OAuth 2.0 challenge, and automatically opens your default web browser to the AbLead authorization screen.
  3. Log in (if not already logged in) and click Authorize. Claude Desktop completes the handshake and securely stores the OAuth token in its local credential store.
  4. When starting a conversation, the hammer icon in the prompt input confirms that all 31 AbLead tools are active and ready.

(Optional) If you are operating in a headless or automated scripting environment without a browser, you can alternatively generate a Personal Access Token (PAT) from your AbLead Profile and provide it via an HTTP header:

{
  "mcpServers": {
    "ablead": {
      "url": "https://ablead.ketchemconsulting.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_PERSONAL_ACCESS_TOKEN"
      }
    }
  }
}

Available Tools (All 35 Discovery, Library & Engineering Tools)

Once connected, your AI assistant has access to the full AbLead suite spanning lead ranking, multi-category results inspection, humanness evaluation, liability de-risking, 3D structure modeling, variant staging, and sequencing library workflows:

1. Campaign Navigation & Lead Evaluation

  • list_projects: Lists all discovery campaigns, project IDs, and antibody counts accessible to your account.
  • get_project_summary: Returns complete project metadata, candidate names, measured experimental values (Kd, EC50, expression titers, Tm), precomputed developability scores, and categorized liabilities.
  • evaluate_and_rank_leads: Performs multi-criteria Pareto trade-off optimization balancing target binding affinity against developability flags (OASign humanness, AbLang2 penalties, CDR deamidation, and isomerization).
  • get_candidate_score_breakdown: Breaks down composite KBC developability scores into itemized category points (CDR Lengths, Stability, Surface Properties, Cysteines, Potential PTMs, Humanness, Physical Properties) and individual penalty rules.

2. Multi-Category Results Matrix

  • get_project_results_grid: Returns the full multi-category results matrix across all 12 discovery categories and 66 columns (cell values, background severity colors, and headers), with optional filtering by candidate names or category.

3. Sequence Annotation & Repertoire Profiling

  • get_antibody_sequence_details: Returns complete variable domain sequences, IMGT residue numbering, North CDR loop assignments, localized liabilities, closest human germlines, and modifiable framework positions (Light chain preceding Heavy chain).
  • run_alignment: Generates multiple sequence alignments across Light and Heavy chains (LC first) using IMGT, Kabat, Martin, or Aho numbering schemes.
  • run_clading: Performs hierarchical sequence clading/clustering based on CDRs (CDR3 or all CDRs) or Frameworks with identity or BLOSUM62 metrics.
  • get_humanness_analysis: Calculates detailed OASign humanness scores (Fv, VH, VL), top closest human germline V/J genes, CDR/FR boundaries, and RPEMHC peptide immunogenicity scores.
  • get_pfa_analysis: Position-specific Frequency Analysis (PFA) comparing candidate residues to human repertoire prevalence, highlighting rare/atypical residues.
  • get_covariance_analysis: Analyzes correlated residue pair covariance violations against human germline repertoires, identifying incompatible residue pairings.
  • search_plabdab: Searches the Patent and Literature Antibody Database (PLAbDab) for sequence matches, CDR similarities, and patented commercial therapeutics.
  • compare_with_clinical_antibodies: Direct side-by-side benchmarking against 180+ clinical-stage and FDA-approved therapeutics (Jain et al. 5th-95th percentile ranges).

4. Biophysical Properties & Surface Patches

  • predict_biophysical_properties: In silico developability predictions calibrated against 180+ clinical antibodies (AC-SINS self-association, HIC hydrophobicity, BVP polyreactivity, Tm thermal stability, PSR, Heparin).
  • get_physical_properties: Full physicochemical profile: Bjellqvist Isoelectric Point (pI), hybrid folded pI, net charge at pH 5.5, 6.0, and 7.4, molecular weight (kDa), extinction coefficient, aliphatic index, GRAVY, and instability index.
  • get_surface_properties: 3D structural surface patch metrics: hydrophobic patches (SPH), positive electrostatic patches (SPP), negative electrostatic patches (SPN), charge distribution (SPCD), and SASA. Falls back to precomputed pipeline results if no 3D structure is attached.
  • get_solvent_exposures: Computes per-residue relative solvent accessibility (RSA) and exposure classifications (Exposed, Buried, Intermediate) across Light and Heavy chains.

5. Humanization & Optimization

  • get_humanization_analysis: Matches candidate variable domains against human V and J germline databases, calculates framework identity and homology percentages, applies Vernier and Honegger exclusion masks, and lists modifiable non-germline positions.
  • generate_humanized_variants: Automates Germline and Sapiens humanization variant design, registers child antibodies in the project lineage, and queues background analysis.
  • first_pass_optimize: Automated First Pass sequence optimization resolving liabilities, rare PFA residues, covariance violations, and framework humanness defects.

6. In Silico Engineering & Construct Assembly

  • simulate_liability_mutations: Tests specific amino acid substitutions in silico, verifying liability removal and ensuring no new liabilities are introduced.
  • engineer_pi: Evaluates solvent-exposed non-CDR positions to identify charge-altering mutations (Arg, Lys, Asp, Glu) to shift pI higher or lower while minimizing developability risk.
  • repair_junction: Analyzes and restores truncated or mutated V-J framework junctions (e.g. framework 4 / J-region canonical residues).
  • assemble_chains: Assembles variable domains with constant domains (IgG1, IgG4, Kappa, Lambda), linkers, or specialty mutations (LALA, LALAPG, YTE).

7. Structure Modeling & Variant Lifecycle

  • build_models: Queues 3D homology model generation in the analysis queue for unmodeled antibodies directly from the chat session.
  • stage_variant_designs: Stages candidate mutant sequences into a named engineering set in AbLead for visual inspection on the dashboard.
  • get_staged_variants: Inspects active or saved engineering sets and staged mutations in the project.
  • clear_staged_variants: Clears all staged variants or removes a specific named engineering set for an antibody candidate.
  • commit_staged_variants: Formally commits staged variants to the project hierarchy as child Antibody records with lineage tracking.

8. Sequencing Library Discovery & Mutagenesis Import

  • list_library_projects: Lists all evaluated sequencing libraries, NGS datasets, Single-Cell AIRR repertoires, biopanning campaigns, and Deep Mutational Scanning (DMS) projects accessible to your account, with optional filtering by analysis type.
  • get_library_summary: Fetches QC summary metrics (total reads, unique productive clones, warning counts), plate demultiplexing overview, clonotype clustering, and candidate clones with flexible sorting (count, frequency, enrichment) and pagination.
  • import_library_clones_to_project: Transfers selected lead clones or all clonotype lead representatives from an evaluated library dataset directly into an antibody discovery project (either appending to an existing campaign or creating a new project) with full lineage tracking and duplicate protection.
  • link_dms_library_to_candidate: Bridges an evaluated Deep Mutational Scanning (DMS) library run to an antibody candidate in an Engineering workspace, aligning fitness scores to IMGT positions and populating the candidate's mutagenesis matrix.

9. Residue Observations & Notes

  • get_observations: Retrieves all user and agent residue observations, flags, and notes for a project or specific clone.
  • add_observation: Records a residue-level scientific observation note or risk annotation in the AbLead project.

Example Prompts for Your AI Assistant

Once connected, you can interact with your AI assistant using natural language to perform complex discovery, optimization, and engineering tasks:

1. Campaign Overview & Lead Ranking

"List my antibody discovery projects in AbLead and summarize the lead candidates in project 104."

"Run a Pareto trade-off evaluation on project 104 balancing binding affinity (70% weight) against developability liabilities (30% weight). Which candidates make up the Pareto frontier, and what are their primary liabilities?"

"What are the main penalties driving mAb-101's developability score? Give me an itemized score breakdown comparing CDR lengths, stability, and humanness."

2. Sequence Annotation & Liability Analysis

"Retrieve the IMGT-numbered sequence for lead mAb-101. Are there any deamidation, isomerization, or oxidation motifs in the CDR loops?"

"Show me the surface property metrics (SPH, SPP, SPN, SPCD) and solvent exposure for mAb-101. Are there large hydrophobic or positive electrostatic patches in the CDRs?"

"Perform a position-specific frequency analysis (PFA) on mAb-101. Are there any rare or atypical residues in the framework regions compared to the human repertoire?"

3. Humanization & Germline Alignment

"Perform a humanization analysis on mAb-101 against human germlines using Honegger exclusions. What are the top matching human V and J genes for the heavy and light chains, and how many framework residues are modifiable?"

"Generate humanized variants for mAb-101 using the Sapiens language model, and add the generated child antibodies to the project lineage."

4. In Silico Liability De-risking & Mutation Simulation

"mAb-101 has an NG deamidation motif at heavy chain position 55 in CDR-H2. Simulate a G55A substitution and check if the deamidation liability is eliminated without introducing new motifs."

"We need to shift the pI of mAb-101 higher to improve formulation stability. Identify solvent-exposed framework positions where charge-altering mutations can be introduced with minimal risk."

5. Staging Designs & 3D Homology Modeling

"The G55A deamidation fix and S31A stability mutation on mAb-101 look clean. Stage these designs into a new engineering set named 'AI_Spark_Set_1' with rationales so our team can review them on the AbLead dashboard."

"Build 3D homology models for our top unmodeled leads (mAb-101 and mAb-102) so we can inspect their 3D surface patch distributions."

"Assemble mAb-101 into a full-length IgG1 format with a Kappa light chain and LALA mutations for effector silencing."

6. Library Discovery, Clone Import & DMS Linking

"List all my evaluated sequencing libraries in AbLead. What was the unique productive clone count for our biopanning campaign?"

"Inspect library 12 and show me the top 10 clonotype lead clones sorted by read count. What are their heavy and light CDR3 sequences?"

"Import the top 5 lead clones from library 12 into our active project 104 with complete lineage tracking."

"Link our DMS fitness library #8 to mAb-101 in project 104 so we can inspect tolerated and deleterious mutations during engineering."

Security, Token Storage & Revocation

How AbLead Stores Authorizations and Keys

Security and multi-tenant isolation are fundamental to AbLead's architecture. Whether an AI assistant connects via OAuth 2.0 (such as Claude Desktop, Claude.ai, or Google Spark / Gemini) or a Personal Access Token (PAT), credentials are protected using industry-standard cryptography:

  • Cryptographic SHA-256 Hashing (Zero Plaintext Storage): AbLead never stores plaintext access tokens in its database. When a token is issued during an OAuth code exchange (ablead_oauth_...) or created manually (ablead_pat_...), it is delivered to the client once. AbLead computes a one-way cryptographic SHA-256 hash (token_hash) and stores only the resulting hash in the database.

  • Token Prefix for Safe UI Identification: The database records only the first 12 characters (token_prefix, e.g., ablead_oauth_...), allowing you to recognize, monitor, and distinguish your active connections in your profile management table without exposing the underlying credential.

  • Granular Permission Scopes: Authorizations are bound to explicit permission scopes (e.g. projects:read,analysis:run,projects:write). An assistant cannot perform actions outside its granted scopes.

  • Strict Project & User Isolation: Every MCP tool invocation resolves the user identity from the verified token hash and filters all database queries to the user's explicit projects and affiliations. AI assistants cannot discover, view, or modify data belonging to any other user or organization.

  • Automatic Expiration: OAuth tokens automatically expire after 90 days, while Personal Access Tokens have configurable lifespans (30, 90, or 365 days). Once expired, tokens are rejected immediately.

  • Zero Infrastructure Compute Cost: LLM inference runs exclusively on your external AI provider subscription (Google Gemini, Anthropic Claude, etc.); AbLead executes only the underlying bioinformatics and data retrieval algorithms.

AI Client Privacy & Proprietary Data Protection

While AbLead enforces strict multi-tenant isolation, cryptographic token hashing (SHA-256), and granular permission scopes within its own platform:

  • Secure In-Transit Data Transfer (OAuth 2.0): All data exchange between AbLead and your AI assistant is encrypted in transit using industry-standard TLS. Utilizing OAuth 2.0 ensures that the connection handshake, token generation, and API requests are authenticated securely without exposing static long-lived credentials or passwords.
  • External Data Transmission: When interacting with an AI assistant connected via MCP, your prompt queries and relevant campaign data (such as variable domain sequences, developability metrics, and candidate mutation designs) are transferred directly to your chosen AI assistant to fulfill analytical and engineering tasks.
  • AI Provider Terms & Policies: While data transfer to the AI client is secure, AbLead cannot control how third-party AI clients or LLM service providers store, process, or retain data once received.
  • Verify Client Privacy Policies: Before connecting an external AI assistant to proprietary discovery campaigns, ensure that the AI client and subscription tier you use (such as enterprise plans with Anthropic, Google, or locally hosted private models) guarantee data privacy, offer zero data retention, and do not use your proprietary biotherapeutic data for model training or public logging.

How to Revoke Authorizations and Keys

You retain real-time control over all external AI connections. If an assistant is no longer needed, a session expires, or a device is retired, you can revoke access instantly:

  1. Sign into your AbLead account.
  2. Open your User Profile & Settings (click your user avatar in the top right navigation bar and select Profile).
  3. Scroll down to the AI & Model Context Protocol (MCP) Integrations section.
  4. Locate the connection in the Active Access Tokens & AI Authorizations table (e.g., "Claude Desktop", "Google Gemini Extension", or a custom PAT name).
  5. Click the red Revoke button (trash / ban icon) on the corresponding row.
  6. Confirm the revocation in the dialog prompt.

What Happens Upon Revocation:

  • Instant Database Invalidation: The token's is_revoked flag is set to True in the AbLead database immediately across all application instances.
  • Immediate 401 Rejection: Any active or subsequent request from that AI assistant using the revoked token will fail instantly with HTTP 401 Unauthorized and an OAuth challenge.
  • No Lingering Access: The assistant cannot execute tools, read campaign leads, or retrieve sequence annotations until re-authorized through a brand-new OAuth consent flow.