MCP Server | ExoHub

ExoCLI includes a built-in Model Context Protocol (MCP) server that exposes data management operations as tools for AI agents. This lets agents like Claude, Cursor, or any MCP-compatible client create repositories, sync data, monitor progress, and more — without requiring knowledge of git-annex internals.

Quick Start

Starting the Server

exo mcp start

This starts the MCP server over stdio. You typically don’t run this directly — instead, you register it in your agent’s MCP configuration.

Claude Code Configuration

claude mcp add --transport stdio exo -- exo mcp start

Or add it manually to your .mcp.json or project settings:

{
  "mcpServers": {
    "exo": {
      "command": "exo",
      "args": ["mcp", "start"]
    }
  }
}

Discovering Tools

List all available tools and their descriptions:

exo mcp list

Show full details for a specific tool, including parameters:

exo mcp show sync

Available Tools

Tool	Description
`create_repo`	Initialize current directory as a git-annex repo with S3 remote
`add`	Add files to tracking with automatic content-type detection (text → git, binary → annex)
`status`	Show working tree status: untracked, modified, and staged files
`locate`	Show where git-annex content is physically stored across remotes
`sync`	Download and upload git-annex managed data files to/from remote storage (background)
`sync_status`	Check whether a background sync is still running
`publish`	Orchestrate the full publish workflow: sync content → bundle metadata → sync to catalog → broadcast
`broadcast`	Broadcast git-annex metadata to remotes without transferring file content
`login`	Authenticate via OIDC device flow (non-blocking)
`login_status`	Check whether authentication has completed
`whoami`	Show identity, session, organisation, and AWS credential info for the current login
`heartbeat_record`	Start recording sync progress metrics in the background
`heartbeat_show`	Show the latest sync progress metrics
`init`	Initialize or reconfigure git-annex in an existing repository (run after `git clone`)
`init_remote`	Add a new storage remote to the repository
`info`	Show repository information: configured remotes, annex state, and storage statistics
`docs`	Fetch exo usage documentation (the llms.txt index, or a specific page)
`catalog_search`	Search the ExoHub catalog for datasets and artifacts
`catalog_schemas`	List available document schema names in the catalog
`catalog_download`	Download files, artifacts, or entire projects from the catalog
`catalog_semantic_search`	Semantic (natural language) search over the catalog using vector similarity
`catalog_entities`	Retrieve entity details and relationships from the catalog knowledge graph

Workflows

Creating a Repository

First create a git repository on your git host (e.g., GitLab, GitHub). Then the agent asks for the repository URL and initializes the local directory:

1. login          → authenticate (returns auth URL for you to visit)
2. login_status   → poll until authentication completes
3. create_repo    → initialize current directory with git-annex + S3 remote
4. add            → add files to tracking
5. sync           → push content to remotes

Cloning and Downloading Data

The MCP server does not expose a clone tool — cloning is done via git clone in a terminal. Once cloned, use init to configure git-annex remotes, then sync to download content:

1. login          → authenticate
2. login_status   → poll until authentication completes
                   (then: git clone <url> in a terminal)
3. init           → configure git-annex remotes from .exohub/remotes
4. sync           → download content from remotes

Syncing with Progress Monitoring

The sync tool runs in the background and returns immediately. The agent can monitor progress for you:

1. heartbeat_record   → start background metrics capture
2. sync               → start the sync (runs in background)
3. heartbeat_show     → poll periodically to check progress
4. sync_status        → check if sync has completed

Checking Repository State

1. status    → see untracked/modified/staged files
2. locate    → find which remotes hold specific files

Use info to see configured remotes and their types, or exo info from the CLI. Remotes are defined in the .exohub/remotes manifest file.

Discovering and Downloading Catalog Data

1. catalog_schemas          → discover available schema types
2. catalog_search           → find datasets matching your criteria
3. catalog_semantic_search  → natural language search (e.g. "datasets related to neurodegeneration")
4. catalog_entities         → look up entity details and relationships (genes, diseases, pathways, etc.)
5. catalog_download         → download artifacts found in search results

Tool Details

create_repo

Initialize the current directory as a git-annex data repository with an S3 remote. You must first create a git repository on your git host and provide its URL.

This tool performs the following steps:

git init in the directory
Adds the URL as the origin remote
Initializes git-annex
Creates .exohub/context (parsed from the git URL)
Creates .exohub/remotes with an s3-archive annex remote configuration
Runs exo init --yes to set up the annex remote

The S3 path is derived from the directory name: s3://exohub-sandbox-uat/sandbox/<directory-name>/_annex.

Parameters:

Parameter	Required	Description
`repo_url`	Yes	Git remote URL (you must create this repo on your git host first)
`directory`	No	Local directory to initialize (defaults to current working directory)

Prerequisites: Authentication (login).

add

Add files to tracking with automatic content-type detection. In auto mode (default), text files go to git and binary/data files go to git-annex based on mimetype.

Parameters:

Parameter	Required	Description
`repo_dir`	Yes	Path to the git repository
`paths`	Yes	File paths to add
`mode`	No	`auto` (default), `annex`, or `git`

Prerequisites: git-annex initialized in the repository.

status

Show working tree status including untracked, modified, and staged files. Read-only.

Parameters:

Parameter	Required	Description
`repo_dir`	Yes	Path to the git repository

locate

Show where git-annex managed content is physically stored across remotes. Read-only.

Parameters:

Parameter	Required	Description
`repo_dir`	Yes	Path to the git repository
`paths`	No	Specific file paths to locate (defaults to all annexed files)

Prerequisites: git-annex initialized. Remotes defined in .exohub/remotes.

sync

Download and upload git-annex managed data files to/from remote storage. Runs in the background and returns immediately.

Parameters:

Parameter	Required	Description
`repo_dir`	Yes	Path to the git repository
`with`	No	Remote names to sync with (defaults to all)

Prerequisites: git-annex initialized (exo init). Remotes defined in .exohub/remotes; use exo info to list them.

Background execution: This tool starts the sync process in the background and returns immediately. Use sync_status to check completion and heartbeat_show for progress details.

sync_status

Check whether a background sync is still running for the given repository.

Parameters:

Parameter	Required	Description
`repo_dir`	Yes	Path to the git repository

Returns: running or not_running.

publish

Orchestrate the full publish workflow: sync content to storage remotes, generate bundle metadata, sync to catalog remotes, then broadcast metadata to all remotes.

Parameters:

Parameter	Required	Description
`repo_dir`	Yes	Path to the git repository
`sync`	No	Array of remote names to sync in step 1; overrides auto-discovery when provided

Prerequisites: git-annex initialized. Remotes defined in .exohub/remotes.

broadcast

Broadcast git-annex metadata and tracking information to remotes without transferring file content. Use this instead of git annex sync --no-content.

Parameters:

Parameter	Required	Description
`repo_dir`	Yes	Path to the git repository
`with`	No	Remote names to broadcast to (defaults to all)

Prerequisites: git-annex initialized. Remotes defined in .exohub/remotes.

init

Initialize or reconfigure an existing git-annex repository. Runs exo init --yes to ensure git-annex is set up and all remotes defined in .exohub/remotes are properly configured. Use this after git clone to enable remotes, or any time remote configuration may be stale. This is idempotent — safe to call multiple times.

Parameters:

Parameter	Required	Description
`repo_dir`	Yes	Path to the git repository

init_remote

Add a new storage remote to the repository. Creates an S3 or local remote for storing git-annex data. The remote is saved to .exohub/remotes for reproducible setup across clones.

Parameters:

Parameter	Required	Description
`repo_dir`	Yes	Path to the git repository
`name`	Yes	Remote name (e.g., `s3-annex`, `s3-export`)
`type`	Yes	Remote type: `annex`, `export`, `artifactdb`, or `exospace`
`s3url`	No	S3 URL (required for `annex`, `export`, `artifactdb`). Example: `s3://exohub-sandbox-uat/sandbox/<org>/<repo>/_annex`
`rsyncurl`	No	Rsync URL or local path (required for `exospace`). Example: `rsync://host/path`
`tracking_branch`	No	Tracking branch for export remotes (defaults to current branch)
`grants`	No	Enable fine-grained S3 Access Grants permissions (default: `true`)

info

Show repository information including configured remotes, annex state, and storage statistics. Use this to discover which remotes are available before running sync or broadcast. Read-only.

Parameters:

Parameter	Required	Description
`repo_dir`	Yes	Path to the git repository

Authenticate via OIDC device flow. If valid credentials exist, returns immediately. Otherwise, starts a device flow in the background and returns an auth URL that the agent shows to you.

Parameters:

Parameter	Required	Description
`force`	No	Force re-authentication even if valid credentials exist

Non-blocking: When device flow is needed, returns the auth URL immediately. Poll login_status to check when authentication completes.

Required before: create_repo, sync, broadcast.

login_status

Check the status of an in-progress login or verify existing credentials.

Returns: waiting (device flow pending), ok (authenticated), not_authenticated, or expired.

whoami

Show who you’re logged in as: identity, session expiry, organisation claims, and the AWS profile/credentials exo will use. Read-only. Returns an error if not logged in (call login first). Never returns tokens or AWS secrets.

Parameters:

Parameter	Required	Description
`aws`	No	Also perform a live `sts:GetCallerIdentity` call (network call)

Prerequisites: Authentication (login).

heartbeat_record

Start recording sync progress metrics in the background. Launches a background process that continuously captures annex sync metrics every interval seconds.

Parameters:

Parameter	Required	Description
`repo_dir`	Yes	Path to the git repository
`interval`	No	Recording interval in seconds (default: 2)
`paths`	No	Paths to track (defaults to `["."]` for the entire repo)

Returns immediately after starting the background recorder. Use heartbeat_show to read captured metrics.

heartbeat_show

Show the latest sync progress metrics captured by heartbeat_record. Read-only.

Parameters:

Parameter	Required	Description
`repo_dir`	Yes	Path to the git repository

Returns: Structured data including per-path file counts, storage progress, active downloads/uploads, network transfer rates, and completion percentages.

Prerequisites: heartbeat_record must be running (or have run) to produce metrics.

catalog_search

Search the ExoHub catalog for datasets and artifacts using full-text or field-specific queries.

Parameters:

Parameter	Required	Description
`q`	Yes	Search query. Use `` for all results. Supports dotfield notation (e.g., `_extra.project_id:"myproject"`, `path:.parquet`)
`schema`	No	Filter by schema name (e.g., `exohub-artifact/v1`)
`project`	No	Filter by project ID
`latest`	No	Return only latest versions (default: `true`)
`fields`	No	Comma-separated response fields (default: `_extra,path`)
`sort`	No	Sort order (default: `-_extra.uploaded`, prefix `-` for descending)
`size`	No	Results per page (default: 10, max: 100)

Prerequisites: Authentication (login).

catalog_schemas

List available document schema names from the catalog. Useful for discovering what schema values to pass to catalog_search.

Parameters:

Parameter	Required	Description
`filter`	No	Glob pattern to filter schema names (default: `exohub-*`)

Prerequisites: Authentication (login).

catalog_download

Download data files, artifacts, or entire projects from the catalog.

Parameters:

Parameter	Required	Description
`id`	Yes	Artifact ID (e.g., `myproject:file.txt@v1`), project@version (e.g., `myproject@v1`), bundle ID, or commit ID
`output_dir`	No	Output directory (default: current directory)
`force`	No	Re-download even if file exists with matching size (default: `false`)

Prerequisites: Authentication (login).

catalog_semantic_search

Perform a semantic (natural language) search over the ExoHub catalog using vector similarity. Unlike catalog_search which does full-text keyword matching, this tool embeds the query and retrieves semantically related chunks, entities, and relationships.

Parameters:

Parameter	Required	Description
`q`	Yes	Natural language query (e.g. `"datasets related to cell proliferation"`, `"BRCA1 gene expression studies"`)
`types`	No	Result types to include: `chunks`, `entities`, `relationships` (defaults to all)
`project`	No	Filter results by project ID
`limit`	No	Maximum results per type (default: 10, max: 100)

Prerequisites: Authentication (login).

catalog_entities

Retrieve entity details and relationships from the ExoHub catalog knowledge graph. Entities are extracted from catalog documents (genes, diseases, pathways, datasets, etc.). Use this to explore how a specific entity connects to other entities across the catalog.

Parameters:

Parameter	Required	Description
`name`	Yes	Entity name to look up (e.g. `"BRCA1"`, `"Alzheimer's disease"`, `"RNAseq"`)
`include_relationships`	No	Whether to include related relationships (default: `true`)

Prerequisites: Authentication (login).

docs

Fetch exo usage documentation for agents. Read-only. With no arguments, returns the llms.txt index of available doc pages. Pass page with a link from that index (or a path under the docs base) to fetch that page’s content. If the docs site is unreachable, returns the attempted URL and the error instead of failing.

Parameters:

Parameter	Required	Description
`page`	No	A page link from the llms.txt index, or a path under the docs base

Architecture

The MCP server runs as a child process of your agent, communicating over stdin/stdout via JSON-RPC. When the agent session ends, stdin closes and the server exits cleanly, killing any background processes it spawned (sync, heartbeat recorder, login).

All tool definitions are centralized in a shared registry, ensuring that exo mcp list, exo mcp show, and the running server always expose the same tools and descriptions.

Table of Contents

Quick Start

Starting the Server

Claude Code Configuration

Discovering Tools

Available Tools

Workflows

Creating a Repository

Cloning and Downloading Data

Syncing with Progress Monitoring

Checking Repository State

Discovering and Downloading Catalog Data

Tool Details

create_repo

add

status

locate

sync

sync_status

publish

broadcast

init

init_remote

info

login

login_status

whoami

heartbeat_record

heartbeat_show

catalog_search

catalog_schemas

catalog_download

catalog_semantic_search

catalog_entities

docs

Architecture