# Cats — how to use (mcp.ai)

Connect your Cats account and use 18 tools for images and design straight from your AI agent. Connect with your own API key. An API providing access to a vast collection of cat images, breeds, and facts.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_cats?ms=1787293380000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `cats_create_favourite`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/cats`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/cats/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/cats/create/favourite` — Tool to save an image as a favourite to your account. Use when you want to mark a cat image as a favourite for later retrieval or filtering by user ID.
  - body: { sub_id?: string, image_id: string }
- `POST https://api.mcp.ai/api/cats/create/vote` — Tool to vote on a cat image. Send image_id and value (1 for upvote, 0 for downvote) to register your vote. Optionally include sub_id for user tracking.
  - body: { value: integer, sub_id?: string, image_id: string }
- `POST https://api.mcp.ai/api/cats/delete/favourite` — Tool to delete a favourite from your account by its ID. Use when you need to remove a previously saved favourite image from your Cat API account.
  - body: { favourite_id: string }
- `POST https://api.mcp.ai/api/cats/delete/image` — Delete an uploaded image from your account by its ID. Use this when you need to remove an image you previously uploaded to The Cat API.
  - body: { image_id: string }
- `POST https://api.mcp.ai/api/cats/delete/vote` — Tool to delete a vote from your account by its ID. Use when you need to remove a previously submitted vote for a cat image.
  - body: { vote_id: string }
- `POST https://api.mcp.ai/api/cats/get/breed` — Tool to get detailed information about a specific cat breed by its ID. Use when you need comprehensive details about a particular breed including temperament, origin, characteristics, and URLs.
  - body: { breed_id: string }
- `POST https://api.mcp.ai/api/cats/get/favourite` — Tool to retrieve a specific favourite by its unique ID. Returns full favourite details including user ID, image ID, creation timestamp, and associated image data. Use when you need to fetch a particul
  - body: { favourite_id: string }
- `POST https://api.mcp.ai/api/cats/get/image` — Tool to retrieve a specific cat image by its unique ID. Returns full image details including URL, dimensions, and breed information if available. Use when you need to fetch a particular image's data o
  - body: { image_id: string }
- `POST https://api.mcp.ai/api/cats/get/image/analysis` — Get machine learning analysis results for an uploaded image. Returns labels with confidence scores, bounding boxes for detected objects, and content moderation results from ML vendors. Note: GIF image
  - body: { image_id: string }
- `POST https://api.mcp.ai/api/cats/get/image/breeds` — Tool to retrieve breed information associated with a specific cat image. Use when you need to identify which breed(s) are shown in a particular image from The Cat API.
  - body: { image_id: string }
- `POST https://api.mcp.ai/api/cats/get/portals` — Retrieves a paginated list of cat breeds from The Cat API. Returns comprehensive breed information including name, description, temperament, origin, life span, and weight. Use this to browse available
  - body: { page?: integer, limit?: integer }
- `POST https://api.mcp.ai/api/cats/get/vote` — Retrieves a specific vote by its unique ID from The Cat API. Returns detailed vote information including the image ID, vote value, timestamp, and optional metadata like sub_id and country code. Use th
  - body: { vote_id: string }
- `POST https://api.mcp.ai/api/cats/list/categories` — Retrieves a list of all active image categories from The Cat API. Categories include hats, sunglasses, boxes, sinks, and more. Use category IDs when searching or filtering images by category.
  - body: { page?: integer, limit?: integer }
- `POST https://api.mcp.ai/api/cats/list/favourites` — Tool to get all favourites belonging to your account. Use when you need to retrieve saved cat images, optionally filtered by sub_id. Supports pagination to browse through large collections of favourit
  - body: { page?: integer, limit?: integer, order?: string, sub_id?: string }
- `POST https://api.mcp.ai/api/cats/list/uploaded/images` — Tool to get all images uploaded to your account via /images/upload. Supports pagination and filtering by sub_id or original filename. Use this to retrieve your uploaded images, check if a file already
  - body: { page?: integer, limit?: integer, order?: string, sub_id?: string, original_filename?: string }
- `POST https://api.mcp.ai/api/cats/list/votes` — Tool to retrieve all votes you have created. Returns a paginated list of votes with image IDs, vote values, and metadata. Use this to view voting history, filter by user segment (sub_id), or analyze v
  - body: { page?: integer, limit?: integer, order?: string, sub_id?: string }
- `POST https://api.mcp.ai/api/cats/search/breeds` — Search for cat breeds by name. Use the 'q' parameter with part or all of the breed name to find matching breeds. Returns breed details including temperament, origin, and characteristics.
  - body: { q?: string, attach_image?: integer }
- `POST https://api.mcp.ai/api/cats/search/images` — Search for random cat images with optional filters. Filter by breed availability, size, and file type. Returns an array of image objects with URLs and metadata. Use this to find cat images for display
  - body: { page?: integer, size?: string, limit?: integer, order?: string, format?: string, has_breeds?: boolean, mime_types?: string }

## Example prompts
- "What can I do in Cats?"
- "Show me a summary of my Cats account"

## More
- Page: https://mcp.ai/cats
- Agent spec (llms.txt): https://mcp.ai/cats/llms.txt
- Postman collection: https://mcp.ai/cats/postman.json