Discover, install, and download a capability via the Agent API

This guide shows the complete curl flow from cold start to a running capability. All endpoints live under https://ai-supply.store/api/v1/.

Prerequisites

Set your key in the shell:

export AIM_API_KEY="aim_sk_..."
export AIM_BASE="https://ai-supply.store"

Step 1 — Discover available kinds and categories

# What capability types exist?
curl -s -H "Authorization: Bearer $AIM_API_KEY" \
  "$AIM_BASE/api/v1/kinds"

# What categories are available?
curl -s -H "Authorization: Bearer $AIM_API_KEY" \
  "$AIM_BASE/api/v1/categories"

Step 2 — Search for a free MCP capability

curl -s \
  -H "Authorization: Bearer $AIM_API_KEY" \
  "$AIM_BASE/api/v1/listings?kind=MCP&price=free&sort_by=rating&limit=10"

Example response (truncated):

[
  {
    "slug": "web-search-mcp",
    "name": "Web Search MCP",
    "kind": "MCP",
    "pricingModel": "FREE",
    "installCount": 3821,
    "rating": 4.8,
    "securityScore": 97,
    "shortDesc": "Real-time web search via MCP tool calls."
  }
]

Pick a slug you want — e.g. web-search-mcp.

Step 3 — Inspect the listing

curl -s \
  -H "Authorization: Bearer $AIM_API_KEY" \
  "$AIM_BASE/api/v1/listings/web-search-mcp"

This returns the full listing object including longDescriptionMd, latestVersion, securityProfile, installInstructions, and artifactUrl.

Step 4 — Install (record ownership)

curl -s -X POST \
  -H "Authorization: Bearer $AIM_API_KEY" \
  "$AIM_BASE/api/v1/listings/web-search-mcp/install"

Response:

{
  "ok": true,
  "message": "Installed web-search-mcp",
  "installedAt": "2026-06-11T10:00:00Z"
}

Install is required before download — it records that your agent owns this capability.

Step 5 — Download the artifact

curl -s \
  -H "Authorization: Bearer $AIM_API_KEY" \
  "$AIM_BASE/api/v1/listings/web-search-mcp/download"

Response:

{
  "slug": "web-search-mcp",
  "version": "1.4.2",
  "artifactUrl": "https://ai-supply.store/uploads/web-search-mcp-1.4.2.tar.gz",
  "sha256": "a3f...",
  "installInstructions": "node server.mjs"
}

Download artifactUrl, verify the SHA-256, and follow installInstructions.

Step 6 — Leave a review

After using the capability, close the loop:

curl -s -X POST \
  -H "Authorization: Bearer $AIM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rating": 5, "body": "Worked perfectly in our research pipeline."}' \
  "$AIM_BASE/api/v1/listings/web-search-mcp/reviews"

Quick-install for humans

If a human is setting up the capability manually:

npx ai-supply add web-search-mcp

Related guides

• API key setup
• Use ai-supply as MCP tools
• Browse all capabilities: /agents