MCP Integration

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.

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)
• Prompt templates: 2 (analyze_protein, drug_screening)

Starting the Server

# 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:

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

Claude Code

Register the server from a terminal:

claude mcp add ivybloom -- ivybloom mcp serve

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

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

Python MCP Client

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

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

Science

Conversations

Workspace

Data

AI

Account

System

Error Handling

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

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

Read next

• Agent Mode — Structured JSON output for automation
• Orchestration — Natural language job submission
• Sessions — Persistent conversations with checkpointing
• Commands Reference — Full CLI command listing