# MCP Server Setup Guide

## Overview

ai4gh includes a Model Context Protocol (MCP) server that exposes GA4GH operations as tools for AI coding assistants. This guide covers setup for Claude Code, Cursor, and generic MCP clients.

## Starting the Server

```bash
ai4gh mcp serve
```

The server uses stdio transport and speaks the MCP protocol.

## Claude Code

Add to your Claude Code MCP configuration (`.claude/settings.json` or equivalent):

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

If using `uv` in a project:

```json
{
  "mcpServers": {
    "ai4gh": {
      "command": "uv",
      "args": ["run", "ai4gh", "mcp", "serve"]
    }
  }
}
```

## Cursor

Add to `.cursor/mcp.json`:

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

## Generic MCP Clients

Any MCP client supporting stdio transport can connect:

```bash
# The server reads MCP JSON-RPC from stdin and writes to stdout
ai4gh mcp serve
```

## Available Tools

| Tool | Description |
|------|-------------|
| `drs_get_object` | Get a DRS object by ID |
| `beacon_query` | Query a Beacon v2 server |
| `htsget_reads` | Get read data from htsget |
| `refget_sequence` | Get reference sequence by checksum |
| `vrs_compute_id` | Compute VRS identifier |
| `phenopacket_validate` | Validate a Phenopacket document |
| `wes_submit_run` | Submit workflow to WES server |
| `tes_create_task` | Create task on TES server |
| `trs_search_tools` | Search TRS tool registry |
| `data_connect_search` | Query via Data Connect |
| `passport_decode` | Decode GA4GH Passport JWT |
| `duo_match` | Check DUO data use compatibility |
| `pedigree_validate` | Validate pedigree structure |

## Available Resources

- `ga4gh://specs` - Index of all supported GA4GH specifications
- `ga4gh://specs/{spec_id}` - Metadata for a specific spec (beacon, drs, htsget, refget, phenopackets, vrs, wes, tes, trs, data_connect, passports, duo, crypt4gh, pedigree)

## Available Prompts

| Prompt | Description |
|--------|-------------|
| `find_variants` | Search for genetic variants across Beacon networks |
| `patient_summary` | Generate clinical summary from Phenopacket data |
| `rare_disease_search` | Search federated rare disease data sources |
| `workflow_submit` | Submit bioinformatics workflow to WES/TES |
| `compliance_report` | Generate compliance report for a GA4GH server |
