---
title: MCP server
description: Expose the platform to AI agents as callable tools over the Model Context Protocol.
tags:
  - mcp
  - agent
  - integration
  - api
---

The **`ivybloom` MCP server** gives an AI agent the platform's tools over the Model Context Protocol. An agent in Claude Code, Claude Desktop, or your own MCP client can submit jobs, search compounds, manage sessions, and generate passports.

It runs on the same backend and job history as [Chat](/docs/chat) and the [ivybloom CLI](/docs/cli), so agent work shows up next to everything else. The [CLI's MCP guide](/docs/cli/mcp) has the full tool catalog and client configs.

## What MCP is

The [Model Context Protocol](https://modelcontextprotocol.io) is an open standard for connecting AI agents to external tools. An MCP server advertises a set of tools an agent can call; the agent picks tools, sends arguments, and reads results back — all over a structured JSON-RPC channel.

## Connecting

The MCP server is part of the [ivybloom CLI](/docs/cli). Once the CLI is installed and authenticated, start the server over stdio:

```bash
# authenticate once
ivybloom auth login --browser

# start the MCP server over stdio (core toolset)
ivybloom mcp serve

# expose every tool domain
ivybloom mcp serve --toolset all
```

The server speaks JSON-RPC over standard input/output and is meant to be launched by an agent or IDE rather than used interactively. To wire it into Claude Desktop, add it to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "ivybloom": {
      "command": "ivybloom",
      "args": ["mcp", "serve"]
    }
  }
}
```

The same `command` / `args` shape works in a Claude Code project `.mcp.json` file, or register it with `claude mcp add ivybloom -- ivybloom mcp serve`. Any other MCP-capable client takes the same command. Add `"--toolset", "all"` to `args` for the full catalog. See the [CLI MCP guide](/docs/cli/mcp) for Python client examples and the full integration walkthrough.

## What is exposed

Tools are named `domain_action` (for example `jobs_submit`, `compounds_search`, `passport_generate`). By default the server advertises the `core` toolset: the jobs, tools, projects, results, storage, stats, suggest and orchestrate domains. `--toolset research`, `--toolset admin` and `--toolset all` widen it, and `--domains jobs,compounds` picks exact domains. Advertising every tool costs an agent roughly 20k tokens of context, which is why `core` is the default.

The catalog differs between CLI versions. Run `ivybloom mcp tools --toolset all` to list what your installed binary advertises. The main families:

| Family | Examples | What it covers |
|--------|----------|----------------|
| **jobs** | `jobs_submit`, `jobs_status`, `jobs_results`, `jobs_cancel` | Submit and manage compute jobs (folding, docking, ADMET) |
| **tools** | `tools_list`, `tools_schema`, `tools_estimate` | Discover and validate the available compute tools |
| **batch** | `batch_submit`, `batch_status`, `batch_results` | High-throughput batch job processing |
| **compounds** | `compounds_search`, `compounds_import`, `compounds_export` | Molecular collection management |
| **chats / sessions** | `chats_create`, `chats_messages`, `sessions_create` | Conversational and stateful agent sessions |
| **campaigns / projects** | `campaigns_create`, `projects_list`, `projects_jobs` | Workspace organization |
| **passports** | `passport_generate`, `passport_compound`, `passport_list` | Compound / target / safety passport generation |
| **workflows** | `workflows_execute`, `workflows_templates` | Automated multi-step pipelines |
| **data / exports / reports** | `data_upload`, `exports_create`, `reports_generate` | Files, exports, and report generation |
| **account** | `account_usage`, `billing_subscription`, `credits_summary` | Account, billing, and usage information |

Agents can also read URI-addressable **resources** (`jobs://{id}`, `projects://list`, `sessions://list` and others; `ivybloom mcp info` lists them) to inspect data without executing a tool, and two guided **prompt templates** — `analyze_protein` and `drug_screening` — walk an agent through common workflows.

## Shared backend and auth

The MCP server is not a separate system. It forwards to the same backend as Chat and the CLI, so it shares one job history, one credit balance, and one set of credentials. Authenticate the CLI once (`ivybloom auth login`) and the server inherits that identity; jobs an agent submits over MCP are the same jobs you see in the web app and the [CLI](/docs/cli).

Because long-running compute (folding, docking) can exceed an agent's request timeout, tools like `jobs_submit` return a job ID immediately — the agent should poll `jobs_status` for completion rather than waiting synchronously.

## Access tier

The MCP server is not gated by plan. It needs the ivybloom CLI, installed and signed in, on any account, including the free Seed plan; there is no anonymous MCP path to the platform tools. The [REST API](/docs/api) needs only an API key from a free account, and the keyless first call is the [guest curl request](/docs/api#guest-curl). Your plan decides the credits, model families and compute tools behind each call; see [Plans & tiers](/docs/plans-and-tiers).

A separate, read-only docs server runs at `https://www.ivybiosciences.com/api/mcp/docs` (JSON-RPC over HTTP, no sign-in). It offers two tools, `search_docs` and `get_doc_markdown`, so an agent can read these docs without installing the CLI.

## Read next