---
id: nsip-docs-mcp
type: semantic
created: 2026-02-07T23:47:38-05:00
namespace: nsip/docs
modified: '2026-08-11T19:29:43.700Z'
title: "NSIP MCP Server Reference"
diataxis_type: reference
provenance:
'@type': Provenance
agent: claude-code/claude-sonnet-5
wasGeneratedBy:
'@id': urn:mif:activity:claude-code-session:f2ea9348-10db-44af-9ccb-a37844b8c1f2
'@type': prov:Activity
trustLevel: user_stated
agentVersion: 2.1.227
---
# NSIP MCP Server Reference
The `nsip` binary ships a built-in [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that exposes the full NSIP Search API surface -- plus analytics-powered breeding intelligence -- to any MCP-compatible client (Claude Desktop, Claude Code, Cursor, etc.).
**Capabilities:** 13 tools, 5 static resources, 4 resource templates, 7 guided prompts, [elicitation](#elicitation) (client-negotiated), [cursor-based pagination](#pagination)
**Protocol version:** `2025-11-25` (MCP LATEST)
**Transports:** stdio, streamable HTTP (SSE)
---
## Table of Contents
- [Installation](#installation)
- [Configuration](#configuration)
- [Tool Reference](#tool-reference)
- [Resource Reference](#resource-reference)
- [Prompt Reference](#prompt-reference)
- [Elicitation](#elicitation)
- [Pagination](#pagination)
- [Analytics Reference](#analytics-reference)
- [EBV Trait Glossary](#ebv-trait-glossary)
---
## Installation
### From crates.io
```bash
cargo install nsip
```
### From source
```bash
git clone https://github.com/zircote/nsip.git
cd nsip
cargo install --path .
```
### Binary download
Pre-built binaries are available from [GitHub Releases](https://github.com/zircote/nsip/releases):
| Platform | Binary |
|----------------|-----------------------------------|
| Linux x86_64 | `nsip-<VERSION>-linux-amd64` |
| Linux ARM64 | `nsip-<VERSION>-linux-arm64` |
| macOS x86_64 | `nsip-<VERSION>-macos-amd64` |
| macOS ARM64 | `nsip-<VERSION>-macos-arm64` |
| Windows x86_64 | `nsip-<VERSION>-windows-amd64.exe` |
### MCP Bundle (Claude Desktop / Claude Code)
Download the universal `nsip-<VERSION>.mcpb` bundle from [GitHub Releases](https://github.com/zircote/nsip/releases). It contains all platforms in a single file.
**Claude Desktop:** Drag `nsip-<VERSION>.mcpb` into Settings > Extensions, or double-click it.
**Claude Code:** Install via the extensions UI.
The bundle auto-selects the correct binary for your platform (macOS ARM64, Linux x86_64, Windows x86_64).
### Docker
```bash
docker pull ghcr.io/zircote/nsip
docker run --rm -i ghcr.io/zircote/nsip mcp
```
The Docker image uses a distroless base for minimal attack surface.
---
## Configuration
### Claude Code (`.mcp.json`)
Place at your project root or `~/.mcp.json`:
```json
{
"mcpServers": {
"nsip": {
"command": "nsip",
"args": ["mcp"]
}
}
}
```
### Claude Desktop (`claude_desktop_config.json`)
```json
{
"mcpServers": {
"nsip": {
"command": "nsip",
"args": ["mcp"]
}
}
}
```
On macOS the config file is at `~/Library/Application Support/Claude/claude_desktop_config.json`.
### HTTP Transport
For network-accessible deployments, use the streamable HTTP transport:
```bash
nsip mcp --transport http --host 127.0.0.1 --port 8080
```
This serves a single MCP endpoint at `/mcp` supporting JSON-RPC over POST and SSE via GET, with session management (`Mcp-Session-Id` header) and CORS headers.
> **Security note:** The HTTP endpoint binds to `127.0.0.1` (localhost) by default and restricts CORS to localhost origins. Do **not** expose it on a public interface without protection. For remote access, place the server behind an authenticated reverse proxy or enable `--auth` for OAuth bearer token authentication. See [OAuth Authentication](how-to/OAUTH-AUTHENTICATION.md) and [MCP Security](explanation/MCP-SECURITY.md).
### Docker transport
```json
{
"mcpServers": {
"nsip": {
"command": "docker",
"args": ["run", "--rm", "-i", "ghcr.io/zircote/nsip", "mcp"]
}
}
}
```
### Verification
After configuring, verify the server starts:
```bash
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | nsip mcp
```
### Tool Sets
By default all 13 tools are exposed. Use `--tools` to enable only specific sets:
```bash
nsip mcp --tools search,breed
```
| Set | Tools |
|-----|-------|
| `search` | `search`, `details`, `lineage`, `progeny`, `profile` |
| `analytics` | `compare`, `rank`, `inbreeding_check`, `mating_recommendations` |
| `flock` | `flock_summary`, `database_status` |
| `breed` | `breed_groups`, `trait_ranges` |
Server instructions are dynamically generated to match the enabled tool sets.
### Authentication
The HTTP transport supports optional OAuth 2.1 + PKCE authentication with GitHub as the identity provider. Enable with `--auth`:
```bash
export NSIP_GITHUB_CLIENT_ID="..."
export NSIP_GITHUB_CLIENT_SECRET="..."
export NSIP_AUTH_SECRET="..." # HMAC-SHA256 secret for JWT signing
export NSIP_AUTH_BASE_URL="http://localhost:8080"
nsip mcp --transport http --port 8080 --auth
```
When enabled, the server exposes OAuth protocol endpoints (`/register`, `/authorize`, `/callback`, `/token`, `/.well-known/oauth-authorization-server`, `/.well-known/oauth-protected-resource`) and requires a `Bearer` token on the `/mcp` endpoint.
**GitHub PAT shortcut:** Clients can bypass the OAuth flow by passing a GitHub Personal Access Token directly as `Authorization: Bearer ghp_...`. The server validates the PAT via the GitHub API and caches the result for 5 minutes.
Authentication is ignored for stdio transport.
### Telemetry
When compiled with `--features telemetry`, the server uses a custom JSON log format that includes W3C trace context (`trace_id`, `span_id`) on every log line:
```bash
cargo install nsip --features telemetry
nsip mcp --transport http --port 8080
```
The telemetry feature adds an `OpenTelemetry` tracing layer. An OTLP exporter can be layered on by extending the tracer provider configuration.
Without the `telemetry` feature (the default), standard text-based tracing to stderr is used.
---
## Tool Reference
All tools return JSON results as text content. Errors use standard MCP error
codes and additionally carry an RFC 9457 `application/problem+json` envelope in
the JSON-RPC error `data` field (`type`, `title`, `status`, `detail`,
`instance`, `exit_code`, `suggested_fix`, `retry_after`, `docs_url`), so an
agent consumer gets the same machine-readable contract as the CLI. See
[`reference/ERROR-ENVELOPE.md`](reference/ERROR-ENVELOPE.md) and the
[error catalog](reference/errors/).
### search
Search for animals in the NSIP database with filters for breed, gender, status, date range, flock, and sorting.
| Parameter | Type | Required | Default | Description |
|------------------|----------|----------|---------|---------------------------------------------------|
| `breed_group_id` | integer | no | | Breed group ID to filter by |
| `breed_id` | integer | no | | Breed ID to filter by |
| `status` | string | no | | `"CURRENT"`, `"SOLD"`, or `"DEAD"` |
| `gender` | string | no | | `"Male"`, `"Female"`, or `"Both"` |
| `born_after` | string | no | | Only animals born after this date (`YYYY-MM-DD`) |
| `born_before` | string | no | | Only animals born before this date (`YYYY-MM-DD`) |
| `proven_only` | boolean | no | false | Only return proven animals |
| `flock_id` | string | no | | Flock ID to filter by |
| `sort_by` | string | no | | Trait abbreviation to sort by (e.g. `"WWT"`) |
| `reverse` | boolean | no | | Reverse the sort order |
| `page` | integer | no | 0 | Page number (0-indexed) |
| `page_size` | integer | no | 15 | Results per page (1-100) |
**Example:**
```json
{
"tool": "search",
"arguments": {
"breed_id": 486,
"gender": "Male",
"status": "CURRENT",
"sort_by": "WWT",
"page_size": 10
}
}
```
---
### details
Get detailed EBV data, breed, contact info, and status for a specific animal by LPN ID.
| Parameter | Type | Required | Description |
|-------------|--------|----------|------------------------------------------|
| `lpn_id` | string | yes | LPN ID or registration number |
**Example:**
```json
{
"tool": "details",
"arguments": {
"lpn_id": "430735-0032"
}
}
```
---
### lineage
Get pedigree / ancestry tree for a specific animal including parents and grandparents.
| Parameter | Type | Required | Description |
|-------------|--------|----------|-------------------------------|
| `lpn_id` | string | yes | LPN ID of the animal |
**Example:**
```json
{
"tool": "lineage",
"arguments": {
"lpn_id": "430735-0032"
}
}
```
---
### progeny
Get paginated list of offspring for a specific animal.
| Parameter | Type | Required | Default | Description |
|-------------|---------|----------|---------|-------------------------------|
| `lpn_id` | string | yes | | LPN ID of the animal |
| `page` | integer | no | 0 | Page number (0-indexed) |
| `page_size` | integer | no | 10 | Results per page |
**Example:**
```json
{
"tool": "progeny",
"arguments": {
"lpn_id": "430735-0032",
"page": 0,
"page_size": 20
}
}
```
---
### profile
Get complete profile for an animal: details, pedigree, and offspring in one call.
| Parameter | Type | Required | Description |
|-------------|--------|----------|-------------------------------|
| `lpn_id` | string | yes | LPN ID of the animal |
**Example:**
```json
{
"tool": "profile",
"arguments": {
"lpn_id": "430735-0032"
}
}
```
---
### breed_groups
List all breed groups and individual breeds in the NSIP database.
No parameters.
**Example:**
```json
{
"tool": "breed_groups",
"arguments": {}
}
```
---
### trait_ranges
Get min/max EBV trait ranges for a specific breed -- useful for understanding breed norms.
| Parameter | Type | Required | Description |
|------------|---------|----------|--------------------|
| `breed_id` | integer | yes | Breed ID to query |
**Example:**
```json
{
"tool": "trait_ranges",
"arguments": {
"breed_id": 486
}
}
```
---
### compare
Compare 2-5 animals side-by-side on their EBV traits. Optionally filter to specific traits.
| Parameter | Type | Required | Description |
|--------------|-----------------|----------|-------------------------------------------------------|
| `lpn_ids` | array\<string\> | yes | LPN IDs to compare (2-5 items) |
| `traits` | string | no | Comma-separated trait filter (e.g. `"BWT,WWT,YWT"`) |
**Example:**
```json
{
"tool": "compare",
"arguments": {
"lpn_ids": ["430735-0032", "430735-0041", "430735-0058"],
"traits": "BWT,WWT,YWT,PEMD"
}
}
```
---
### rank
Rank animals within a breed by weighted EBV traits. Specify trait weights to prioritize breeding goals.
| Parameter | Type | Required | Default | Description |
|------------|---------------------------|----------|---------|--------------------------------------------------------|
| `breed_id` | integer | yes | | Breed ID to search within |
| `weights` | object\<string, number\> | yes | | Trait weights (e.g. `{"BWT": -1.0, "WWT": 2.0}`) |
| `gender` | string | no | | `"Male"`, `"Female"`, or `"Both"` |
| `status` | string | no | | Animal status filter (e.g. `"CURRENT"`) |
| `top_n` | integer | no | 10 | Number of top-ranked results to return |
**Example -- terminal sire selection (prioritize growth, penalize birth weight):**
```json
{
"tool": "rank",
"arguments": {
"breed_id": 486,
"weights": {
"BWT": -1.0,
"WWT": 2.0,
"YWT": 1.5,
"PEMD": 1.0
},
"gender": "Male",
"status": "CURRENT",
"top_n": 5
}
}
```
**Example -- maternal sire selection:**
```json
{
"tool": "rank",
"arguments": {
"breed_id": 486,
"weights": {
"NLB": 2.0,
"NLW": 2.0,
"MWWT": 1.5,
"BWT": -0.5
},
"gender": "Male",
"top_n": 10
}
}
```
---
### inbreeding_check
Calculate Wright's coefficient of inbreeding (COI) for a potential sire-dam mating. Returns COI value, traffic-light rating (Green/Yellow/Red), and shared ancestors.
| Parameter | Type | Required | Description |
|-----------|--------|----------|---------------------------|
| `sire_id` | string | yes | LPN ID of the sire |
| `dam_id` | string | yes | LPN ID of the dam |
**Example:**
```json
{
"tool": "inbreeding_check",
"arguments": {
"sire_id": "430735-0032",
"dam_id": "430735-0089"
}
}
```
**Example response:**
```json
{
"coefficient": 0.03125,
"rating": "Green",
"shared_ancestors": [
{
"lpn_id": "410220-0015",
"sire_depth": 2,
"dam_depth": 2
}
]
}
```
---
### mating_recommendations
Find optimal mates for an animal: searches the breed for candidates, checks inbreeding, and ranks by trait complementarity.
| Parameter | Type | Required | Default | Description |
|-----------------|---------|----------|---------|----------------------------------------------------------|
| `lpn_id` | string | yes | | LPN ID of the animal to find mates for |
| `breed_id` | integer | yes | | Breed ID to search for potential mates |
| `target_traits` | string | no | | Traits to optimize (comma-separated, e.g. `"WWT,NLB"`) |
| `max_results` | integer | no | 5 | Maximum number of recommendations |
When `target_traits` is omitted, defaults to `WWT` (weight 1.0), `BWT` (weight -0.5), and `NLB` (weight 0.5).
Traits where lower is preferred (`BWT`, `WFEC`, `PFEC`, `YFD`) automatically receive negative weights.
**Example:**
```json
{
"tool": "mating_recommendations",
"arguments": {
"lpn_id": "430735-0032",
"breed_id": 486,
"target_traits": "WWT,PEMD,NLB",
"max_results": 3
}
}
```
**Example response:**
```json
[
{
"mate_lpn_id": "430735-0089",
"rank_score": 18.42,
"coi": {
"coefficient": 0.015,
"rating": "Green"
},
"predicted_offspring_ebvs": {
"BWT": 0.15,
"WWT": 11.3,
"PEMD": 1.8,
"NLB": 0.12
}
}
]
```
---
### flock_summary
Summarize a flock's animals: count, gender breakdown, and average EBV traits.
| Parameter | Type | Required | Description |
|------------|---------|----------|--------------------------------------|
| `flock_id` | string | yes | Flock ID to summarize |
| `breed_id` | integer | no | Breed ID to filter within the flock |
**Example:**
```json
{
"tool": "flock_summary",
"arguments": {
"flock_id": "430735",
"breed_id": 486
}
}
```
**Example response:**
```json
{
"flock_id": "430735",
"total_count": 87,
"sample_size": 87,
"males": 12,
"females": 75,
"trait_averages": {
"BWT": 0.32,
"WWT": 8.45,
"YWT": 12.10,
"NLB": 0.08,
"PEMD": 0.95
}
}
```
---
### database_status
Get NSIP database last-updated date and available animal statuses.
No parameters.
**Example:**
```json
{
"tool": "database_status",
"arguments": {}
}
```
---
## Resource Reference
Resources provide static and dynamic data that MCP clients can read directly via URI.
### Static Resources
| URI | Name | MIME Type | Description |
|----------------------------|-------------------|-------------------|---------------------------------------------------------|
| `nsip://glossary` | EBV Trait Glossary| text/markdown | Definitions of all 16 NSIP EBV traits with units, interpretation, and selection direction |
| `nsip://breeds` | Breed Directory | application/json | Live directory of all breed groups and breeds |
| `nsip://guide/selection` | Selection Guide | text/markdown | How to use EBVs for breeding decisions -- selection steps, objectives, trade-offs |
| `nsip://guide/inbreeding` | Inbreeding Guide | text/markdown | COI thresholds, inbreeding depression effects, avoidance strategies |
| `nsip://status` | Database Status | application/json | Live NSIP database status with last update date |
### Resource Templates
Resource templates use URI parameters to fetch dynamic data from the NSIP API.
| URI Template | Name | MIME Type | Description |
|---------------------------------------|-------------------|-------------------|--------------------------------------------------|
| `nsip://animal/{lpn_id}` | Animal Profile | application/json | Full profile for a specific animal by LPN ID |
| `nsip://animal/{lpn_id}/pedigree` | Animal Pedigree | application/json | Pedigree / lineage tree for a specific animal |
| `nsip://animal/{lpn_id}/progeny` | Animal Progeny | application/json | Offspring list for a specific animal |
| `nsip://breed/{breed_id}/ranges` | Breed Trait Ranges| application/json | Min/max trait value ranges for a specific breed |
**Template examples:**
```
nsip://animal/430735-0032 -> Full profile for animal 430735-0032
nsip://animal/430735-0032/pedigree -> Pedigree tree
nsip://animal/430735-0032/progeny -> Offspring list
nsip://breed/486/ranges -> Trait ranges for breed 486
```
---
## Prompt Reference
Prompts are guided workflows that fetch live data from the NSIP API and construct structured context for an LLM to provide breeding advice. Each prompt returns one or more `PromptMessage` objects with pre-fetched data embedded.
### evaluate-ram
Evaluate a ram's breeding value. Fetches the animal's EBVs and constructs a comprehensive assessment emphasizing growth traits (WWT, YWT, PEMD) and carcass quality (PFAT). Considers value as terminal sire vs. maternal sire.
| Argument | Required | Description |
|----------|----------|----------------------------|
| `lpn_id` | yes | LPN ID of the ram |
---
### evaluate-ewe
Evaluate a ewe's breeding value. Emphasizes maternal traits (NLB, NLW, MWWT) and moderate birth weight (BWT). Considers prolificacy, lamb-rearing ability, and longevity potential.
| Argument | Required | Description |
|----------|----------|----------------------------|
| `lpn_id` | yes | LPN ID of the ewe |
---
### compare-breeding-stock
Compare multiple animals side-by-side with trait-by-trait analysis. Fetches details for all animals and produces a structured comparison highlighting differences, relative strengths/weaknesses, and suitability for different breeding goals.
| Argument | Required | Description |
|--------------|----------|-----------------------------------------------------|
| `lpn_ids` | yes | Comma-separated LPN IDs of animals to compare (2-5) |
Once the required arguments resolve, this prompt sends a follow-up `ComparePreferences` [elicitation](#elicitation) request asking which traits to focus on. It is optional -- see [Elicitation](#elicitation) for the schema and what happens if the client or user doesn't respond.
---
### plan-mating
Plan a specific mating. Fetches details and lineage for both sire and dam, calculates COI and trait complementarity, and produces a mating assessment with inbreeding safety check, predicted offspring quality, and an overall recommendation (proceed/caution/avoid).
| Argument | Required | Description |
|-----------|----------|-----------------------|
| `sire_id` | yes | LPN ID of the sire |
| `dam_id` | yes | LPN ID of the dam |
After fetching sire/dam data and computing COI, this prompt sends a follow-up `MatingConstraints` [elicitation](#elicitation) request asking for a max COI and breeding objective. It is optional -- see [Elicitation](#elicitation).
---
### flock-improvement
Analyze a breed or flock for trait gaps and improvement opportunities. Fetches current animals and breed trait ranges, then identifies where the group falls below or exceeds breed average with prioritized improvement recommendations.
| Argument | Required | Description |
|------------|----------|----------------------------------------|
| `breed_id` | yes | Breed ID to analyze |
| `flock_id` | no | Optional flock ID to narrow analysis |
After fetching the breed/flock sample and trait ranges, this prompt sends a follow-up `FlockContext` [elicitation](#elicitation) request asking for the breeding objective and flock size. It is optional -- see [Elicitation](#elicitation).
---
### select-replacement
Find top replacement candidates within a breed. Searches by gender and sorts by a target trait to identify the best replacements, with trade-off analysis and selection criteria summary.
| Argument | Required | Description |
|----------------|----------|-------------------------------------------------|
| `breed_id` | yes | Breed ID to search within |
| `gender` | yes | Gender of replacement animals (`"Male"` or `"Female"`) |
| `target_trait` | yes | Primary trait to optimize (e.g. `"WWT"`, `"NLB"`) |
Before searching, this prompt sends a follow-up `SelectionCriteria` [elicitation](#elicitation) request asking for a minimum accuracy and priority traits. It is optional -- see [Elicitation](#elicitation).
---
### interpret-ebvs
Plain-language EBV explanation. Fetches the animal's details and the full EBV glossary, then produces a farmer-friendly interpretation of each trait -- avoiding jargon and using practical terms like "heavier lambs at weaning" instead of "higher WWT EBV."
| Argument | Required | Description |
|----------|----------|--------------------------------|
| `lpn_id` | yes | LPN ID of the animal |
---
## Elicitation
Four of the seven guided prompts -- [`compare-breeding-stock`](#compare-breeding-stock), [`plan-mating`](#plan-mating), [`flock-improvement`](#flock-improvement), and [`select-replacement`](#select-replacement) -- send a follow-up [MCP elicitation](https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation) request once their required arguments resolve, asking the user for optional extra context that steers the analysis. Where in the prompt the request is sent varies -- `compare-breeding-stock` and `select-replacement` elicit before fetching any data, while `plan-mating` and `flock-improvement` elicit after their API calls complete. Each prompt's entry under [Prompt Reference](#prompt-reference) states which.
Elicitation is a **client** capability, not a server one: `get_info()` only declares `tools`, `prompts`, and `resources` in `ServerCapabilities`. The server issues an `elicitation/create` request over the existing session, and it only reaches the user if the client declared the `elicitation` capability at initialize.
### Degradation is silent, never an error
If the client didn't declare elicitation support, or the user declines or cancels the request, the affected prompt proceeds **without** the extra context. This is not an error -- the prompt still returns a result built from its required arguments alone. All of the following collapse to "proceed without elicited data":
| Condition | Result |
|-------------------------------------------------------|------------------------------|
| Client did not declare the `elicitation` capability | Prompt proceeds without it |
| User declines the request | Prompt proceeds without it |
| User cancels/dismisses the request | Prompt proceeds without it |
| Client returns no content | Prompt proceeds without it |
Any other failure while eliciting (a transport error, a response that fails to parse) is logged server-side and also degrades to "proceed without it" -- an elicitation failure never surfaces as a tool/prompt error to the caller.
### Schemas
Each prompt elicits one flat JSON object with every field optional; an empty submission (`{}`) is valid for all four.
#### `ComparePreferences` -- used by `compare-breeding-stock`
Elicitation message: *"Which traits should the comparison focus on?"*
| Field | Type | Required | Description |
|----------|--------|----------|--------------------------------------------------------------------------|
| `traits` | string | no | Comma-separated trait abbreviations to focus on (e.g. `"WWT,YWT,NLB"`) |
#### `MatingConstraints` -- used by `plan-mating`
Elicitation message: *"Any breeding constraints for this mating? (max COI, breeding objective)"*
| Field | Type | Required | Description |
|-----------------------|--------|----------|---------------------------------------------------------|
| `max_coi` | number | no | Maximum acceptable coefficient of inbreeding (0.0-1.0) |
| `breeding_objective` | string | no | `"Growth"`, `"Maternal"`, or `"Dual"` |
#### `FlockContext` -- used by `flock-improvement`
Elicitation message: *"Tell us about your flock goals (breeding objective, flock size)"*
| Field | Type | Required | Description |
|-----------------------|---------|----------|----------------------------------------------------|
| `breeding_objective` | string | no | `"Growth"`, `"Maternal"`, or `"Dual"` |
| `flock_size` | integer | no | Approximate flock size (number of breeding ewes) |
#### `SelectionCriteria` -- used by `select-replacement`
Elicitation message: *"Any selection criteria? (minimum accuracy, priority traits)"*
| Field | Type | Required | Description |
|-------------------|---------|----------|-----------------------------------------------------|
| `min_accuracy` | integer | no | Minimum accuracy percentage to require (0-100) |
| `priority_traits` | string | no | Comma-separated priority traits (e.g. `"WWT,NLB"`) |
Elicited values, when provided, reach the LLM in one of two ways. `plan-mating`, `flock-improvement`, and `select-replacement` fold them into a `user_constraints` / `user_context` / `user_criteria` key in the JSON block alongside the fetched animal data; `compare-breeding-stock` instead appends the requested traits to its instruction text as a "Focus especially on these traits" line, with no `user_*` key. Either way they only steer the LLM's analysis -- they never change which API calls the prompt itself makes.
---
## Pagination
Three list operations use cursor-based pagination: [`prompts/list`](#prompt-reference), [`resources/list`](#resource-reference), and `resources/templates/list` (the wire method name for [resource templates](#resource-templates)). `tools/list` does **not** paginate -- it always returns the complete, current tool set (filtered only by `--tools`, see [Tool Sets](#tool-sets)) in a single response with `nextCursor` absent, regardless of any `cursor` sent with the request.
- **Page size:** fixed at 25 items per page, not configurable.
- **Cursor:** an opaque token returned as `nextCursor` on a page that has more results after it. Treat it as opaque -- pass it back verbatim on the next request; never construct, parse, or edit one yourself.
- **First page:** omit `cursor` (or send no pagination params at all) to start from the beginning.
- **Last page:** `nextCursor` is absent once the final page has been returned.
- **Invalid cursor:** a cursor the server can't accept -- malformed, or pointing past the end of the result set -- is rejected with the [`mcp/invalid-cursor`](reference/errors/mcp/invalid-cursor.md) error; see the [Error Envelope reference](reference/ERROR-ENVELOPE.md) for the full response shape.
At the server's current counts (13 tools, 5 static resources, 4 resource templates, 7 prompts), every list fits inside one 25-item page, so `nextCursor` is always absent today. Clients should still implement cursor-following: these counts grow as the server adds tools, resources, and prompts, and a client that assumes a single page will silently miss later results once a list operation actually needs a second page.
This is separate from the `page` / `page_size` **tool parameters** on `search` and `progeny` (see [Tool Reference](#tool-reference)), which paginate the NSIP API's own animal result sets, not the MCP list-operations described here.
---
## Analytics Reference
The MCP server includes built-in analytics computed locally (no additional API calls beyond data retrieval).
### Coefficient of Inbreeding (COI)
Calculates Wright's coefficient of inbreeding from pedigree data:
```
COI = Sigma [(0.5)^(n1 + n2 + 1)]
```
Where:
- `n1` = path length (in generations) from sire to common ancestor
- `n2` = path length (in generations) from dam to common ancestor
- The sum is taken over all paths through all common ancestors
**Traffic-light thresholds:**
| Rating | COI Range | Interpretation |
|----------|---------------|----------------------------------------------|
| Green | < 6.25% | Acceptable -- proceed with mating |
| Yellow | 6.25% - 12.5% | Elevated inbreeding -- consider alternatives |
| Red | > 12.5% | High inbreeding -- generally avoid |
**Reference values:**
- 6.25% is equivalent to mating half-siblings
- 12.5% is equivalent to mating full siblings or parent-offspring
- 25% is equivalent to mating identical twins
### Weighted Trait Ranking
Animals are ranked by a weighted composite score:
```
Score = Sigma (trait_value * weight * accuracy / 100)
```
For each trait where both a weight and a value exist:
- `trait_value` is the animal's EBV for that trait
- `weight` is the user-specified importance (negative weights penalize higher values)
- `accuracy` is the trait's accuracy percentage (0-100), used as a confidence scaler
Animals are sorted in descending order by composite score.
### Trait Complementarity
Predicts midparent EBV values for potential offspring:
```
predicted_offspring_EBV = (sire_EBV + dam_EBV) / 2
```
Only traits present in both sire and dam are included. This provides a first-order estimate of the genetic merit expected in offspring.
---
## EBV Trait Glossary
Quick reference for the NSIP Estimated Breeding Value traits returned by the Search API.
| Abbreviation | Name | Unit | Selection Direction | Description |
|--------------|------------------------|---------|--------------------------------------|--------------------------------------------------------------------------|
| BWT | Birth Weight | lbs | Lower is generally preferred | Predicted difference in birth weight. Lower values reduce dystocia risk. |
| WWT | Weaning Weight | lbs | Higher is preferred | Predicted difference in weight at weaning (60 days). |
| PWWT | Post-Weaning Weight | lbs | Higher is preferred | Predicted difference in post-weaning weight. |
| YWT | Yearling Weight | lbs | Higher is preferred | Predicted difference in yearling weight (365 days). |
| MWWT | Maternal Weaning Weight| lbs | Higher is preferred | Predicted difference in lamb weaning weight from the dam's milk/mothering.|
| NLB | Number of Lambs Born | lambs | Higher is preferred (with caution) | Predicted difference in lambs born per lambing. |
| NLW | Number of Lambs Weaned | lambs | Higher is preferred | Predicted difference in lambs weaned per lambing. |
| PEMD | Post-Weaning Eye Muscle Depth | mm | Higher is preferred | Ultrasound loin eye muscle depth measured post-weaning. |
| PFAT | Post-Weaning Fat | mm | Moderate preferred (breed-dependent) | Ultrasound subcutaneous fat depth measured post-weaning. |
| YEMD | Yearling Eye Muscle Depth | mm | Higher is preferred | Ultrasound loin eye muscle depth measured at yearling age. |
| YFAT | Yearling Fat | mm | Moderate preferred (breed-dependent) | Ultrasound subcutaneous fat depth measured at yearling age. |
| WFEC | Weaning Fecal Egg Count| % | Lower is preferred | Fecal worm egg count at weaning (parasite resistance). |
| PFEC | Post-Weaning Fecal Egg Count | % | Lower is preferred | Fecal worm egg count post-weaning (parasite resistance). |
| YFD | Yearling Fibre Diameter| micron | Lower is generally preferred | Wool fibre diameter at yearling age (finer is generally more valuable). |
| YGFW | Yearling Greasy Fleece Weight | % | Higher is preferred (wool breeds) | Greasy fleece weight at yearling age. |
| YSL | Yearling Staple Length | mm | Higher is preferred (wool breeds) | Wool staple length at yearling age. |
### Common Breeding Objectives
- **Terminal sire:** Emphasize WWT, YWT, PEMD, PFAT (moderate). Use negative BWT weight.
- **Maternal flock:** Emphasize NLB, NLW, MWWT with moderate BWT.
- **Dual purpose:** Balance growth (WWT, YWT) with maternal traits (NLB, NLW).
- **Parasite resistance:** Emphasize WFEC and PFEC (lower is better).