---
title: MCP Integration
description: >-
  Platform tools via Model Context Protocol for AI agent integration with
  Claude, GPT, and custom agents.
tags:
  - mcp
  - agent
  - ai
  - integration
  - claude
---

MCP integration exposes the full platform API to AI agents through a built-in Model Context Protocol server, turning the CLI tool catalog into callable agent tools. Reach for it when you want Claude, GPT, or a custom agent to submit jobs, search compounds, or manage sessions programmatically rather than driving the CLI by hand. The server runs on the same backend and job history as the rest of the CLI, so agent-driven work shows up alongside your terminal and web activity. For the full command set, see the [CLI overview](/docs/cli).

  advanced
  Authenticated CLI (`ivybloom auth login`), Understanding of AI agents and tool use

## MCP Integration _(since v0.8.53)_
Platform tools via Model Context Protocol for AI agent integration with Claude, GPT, and custom agents.

---

## Overview

The **Model Context Protocol** (MCP) is a standard for connecting AI agents to external tools. The ivybloom CLI includes a built-in MCP server that exposes the full platform API as tools across dozens of domains.

- **Protocol version**: `2024-11-05`
- **Transport**: stdio (standard input/output)
- **Tools**: the full catalog across all domains with `--toolset all`; the default `core` toolset advertises the jobs, tools, projects, results, storage, stats, suggest and orchestrate domains
- **Resources**: URI-addressable data (listed under [Resources](#resources))
- **Prompt templates**: 2 (`analyze_protein`, `drug_screening`)

---

## Starting the Server

```bash
# Start the MCP server on stdio (core toolset)
ivybloom mcp serve

# Expose every domain, or pick exact domains
ivybloom mcp serve --toolset all
ivybloom mcp serve --domains jobs,compounds,passport

# Show server capabilities
ivybloom mcp info

# List the tools a given toolset exposes
ivybloom mcp tools --toolset all
```

Toolsets are `core` (default), `research`, `admin` and `all`. The `IVYBLOOM_MCP_PROFILE` and `IVYBLOOM_MCP_DOMAINS` environment variables set the same options. The catalog differs between CLI versions, so check `ivybloom mcp tools` on your installed binary.

The server communicates via JSON-RPC over stdio. It is designed to be launched by an AI agent or IDE, not used interactively.

---

## Integration Examples

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

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

### Claude Code

Register the server from a terminal:

```bash
claude mcp add ivybloom -- ivybloom mcp serve
```

Or add it to `.mcp.json` at your project root:

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

### Python MCP Client

```python
import subprocess
import json

proc = subprocess.Popen(
    ["ivybloom", "mcp", "serve"],
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    text=True
)

# Send JSON-RPC request
request = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
}
proc.stdin.write(json.dumps(request) + "\n")
proc.stdin.flush()

# Read response
response = json.loads(proc.stdout.readline())
```

---

## MCP Architecture

|JSON-RPC over stdio| B[ivybloom mcp serve]
    B -->|HTTP API| C[Platform backend]
    C --> D["Job execution (Modal.com GPU)"]
    C --> E["Data storage (Supabase)"]
    C --> F["File storage (AWS S3)"]`}
  caption="An AI agent speaks JSON-RPC to the MCP server, which calls the platform backend over HTTP."
/>

---

## Tool Catalog

The main tools, organized by domain. Tool names follow the pattern `domain_action` (e.g., `jobs_submit`, `compounds_search`). `ivybloom mcp tools --toolset all` prints the complete list.

### Core

| Domain | Tools | Description |
|--------|-------|-------------|
| **jobs** | `list`, `submit`, `wait`, `stats`, `status`, `results`, `cancel`, `clone`, `search`, `download`, `deprecate`, `undeprecate`, `artifacts`, `logs`, `phase`, `events`, `self_heal` | Job lifecycle management |
| **tools** | `list`, `schema`, `validate`, `estimate`, `defaults`, `example`, `get` | Tool discovery and validation |
| **batch** | `list`, `submit`, `status`, `results`, `cancel`, `pause`, `resume` | Batch job processing |

### Science

| Domain | Tools | Description |
|--------|-------|-------------|
| **compounds** | `collections_list`, `collections_create`, `collections_get`, `search`, `import`, `import_status`, `export`, `delete` | Compound library management |
| **proteinprep** | `run`, `protonate`, `sites`, `status` | Protein structure preparation (PDB2PQR, P2Rank) |
| **benchmarks** | `get`, `run`, `datasets` | Tool benchmarking (`benchmark_compare` and `benchmark_status` use the singular prefix) |
| **passport** | `list`, `generate`, `compound`, `compound_batch` | Compound, target and safety passports |
| **results** | `inspect`, `summarize`, `compare`, `query`, `plot` | Job result analysis |
| **pipelines** | `list`, `get`, `create`, `cancel`, `validate` | Multi-step pipelines |
| **discovery** | `browse`, `stats`, `enrich` | Discovery browsing |

### Conversations

| Domain | Tools | Description |
|--------|-------|-------------|
| **sessions** | `list`, `create`, `get`, `append`, `record_tool_call`, `artifacts_list`, `artifacts_add`, `artifacts_consume` | Session persistence |
| **chats** | `list`, `get`, `create`, `delete`, `messages`, `recent`, `history`, `export` | Chat management |
| **checkpoints** | `list`, `create`, `rollback`, `prune` | Session checkpointing |
| **context** | `get`, `add_file`, `remove_file`, `add_memory`, `clear_memories` | Chat context management |
| **actions** | `list`, `get`, `stats`, `sync` | Tool call action tracking |

### Workspace

| Domain | Tools | Description |
|--------|-------|-------------|
| **projects** | `list`, `get`, `create`, `update`, `delete`, `jobs` | Project management |
| **campaigns** | `list`, `get`, `create`, `update`, `delete` | Campaign management |
| **workflows** | `list`, `get`, `create`, `execute`, `results`, `templates`, `template_get` | Workflow automation |
| **templates** | `list`, `get`, `create`, `delete` | Workflow templates |

### Data

| Domain | Tools | Description |
|--------|-------|-------------|
| **data** | `list`, `get`, `upload`, `delete`, `download`, `sync`, `tag` | File management |
| **exports** | `list`, `create`, `get` | Data export |
| **reports** | `list`, `generate`, `get` | Report generation |
| **attachments** | `list`, `upload`, `get`, `delete`, `url` | Chat file attachments |
| **sync** | `status`, `push`, `pull`, `files` | Project data sync |
| **resources** | `search`, `tree`, `stats`, `recent`, `bulk`, `favorite` | Cross-resource operations |
| **stats** | `overview`, `project` | Usage statistics |
| **storage** | `roots`, `browse`, `presign`, `preview`, `upload` | Workspace storage |

### AI

| Domain | Tools | Description |
|--------|-------|-------------|
| **ai** | `complete`, `models` | AI model completions |
| **models** | `list`, `available`, `entitlements` | Model catalog and plan entitlements |

### Account

| Domain | Tools | Description |
|--------|-------|-------------|
| **account** | `me`, `info`, `usage` | Account information |
| **usage** | `spend`, `summary`, `history`, `cost`, `cost_history`, `quota` | Spend and quota |
| **billing** | `subscription`, `plans`, `invoices`, `tokens`, `portal_url` | Billing management |
| **credits** | `summary`, `stats`, `history`, `trends`, `alerts_show`, `alerts_set`, `export` | Credit tracking |
| **profile** | `show`, `update`, `avatar_upload`, `avatar_delete`, `status` | User profile |
| **settings** | `show`, `update`, `newsletter_show`, `newsletter_update`, `ai_show`, `ai_update` | App settings |
| **auth** | `status`, `whoami`, `verify`, `devices`, `devices_revoke` | Authentication |
| **org** | `list`, `create`, `info`, `update`, `members`, `set_role`, `invitations`, `invite`, `respond_invitation`, `remove_member` | Organizations |
| **apikeys** | `list`, `create`, `info`, `update`, `revoke` | API key management |
| **devices** | `list`, `trust`, `untrust`, `remove` | Device management |
| **alerts** | `list`, `set`, `reset` | Alert configuration |
| **notifications** | `list`, `mark_read`, `update_settings` | Notification management |
| **flags** | `list`, `status`, `enable`, `disable`, `reset` | Feature flags |

### System

| Domain | Tools | Description |
|--------|-------|-------------|
| **health** | `check` | System health |
| **docs** | `list`, `read`, `search`, `trending` | Documentation access |

### Error Handling

Tool failures return a structured result with `isError: true` and a JSON body containing:

```json
{
  "isError": true,
  "code": "ERR_INVALID_INPUT",
  "message": "Invalid protein sequence",
  "hint": "Check the sequence for non-amino-acid characters",
  "http_status": 400,
  "server_code": "INVALID_SEQUENCE",
  "retry_after": null,
  "retryable": false
}
```

The result is not a JSON-RPC error (those are reserved for protocol problems); instead, the tool succeeds with an error body in the result content. This allows agents to handle errors programmatically without losing context.

---

## Resources

MCP resources provide URI-addressable access to platform data:

```
projects://list          projects://{id}
jobs://{id}              tools://{name}
sessions://list          sessions://{id}
campaigns://list         campaigns://{id}
workflows://list         workflows://{id}
compounds://collections  compounds://{collection_id}
chats://list             chats://{id}
batch://list             batch://{id}
org://list               org://{id}
apikeys://list           attachments://{id}
profile://me             settings://current
billing://subscription   notifications://list
```

Agents can read resources to inspect data without executing tools.

---

## Prompt Templates

Two built-in prompt templates guide agents through common workflows:

### `analyze_protein`

Guided protein analysis — walks the agent through structure prediction, quality checking, and binding site detection.

### `drug_screening`

Virtual screening workflow — guides compound library import, ADMET screening, docking, and result aggregation.

---

## Troubleshooting

### Details

Ensure you are authenticated:
```bash
ivybloom auth status
```
If not authenticated, run `ivybloom auth login --browser`.

### Details

Verify the MCP server reports tools:
```bash
ivybloom mcp tools | head -20
```
Check that your agent configuration points to the correct binary path.

### Details

Some tools require specific API key scopes. Check your permissions:
```bash
ivybloom auth status --show-permissions
```

### Details

Long-running tools (protein folding, docking) may exceed agent timeouts. The MCP server returns a job ID immediately — the agent should poll `jobs_status` for completion rather than waiting synchronously.

---

## Read next

- [Agent Mode](/docs/cli/agent-mode) — Structured JSON output for automation
- [Orchestration](/docs/cli/orchestration) — Natural language job submission
- [Sessions](/docs/cli/sessions) — Persistent conversations with checkpointing
- [Commands Reference](/docs/cli/commands) — Full CLI command listing