PetstoreAPI MCP (Model Context Protocol) Guide

Modern Petstore API provides Model Context Protocol (MCP) support enabling AI assistants like Claude Desktop to directly interact with our API through structured tools and resources. Our MCP server implementation exposes pet queries, order management, and search capabilities as AI-consumable tools, allowing natural language interaction with the Petstore platform for intelligent automation and context-aware assistance.

Quick Start - Claude Desktop Configuration

The fastest way to use PetstoreAPI with MCP is through Claude Desktop. Here's how to configure it:

Step 1: Get Your API Key

Step 2: Find Your Config File

Config file locations:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Linux: ~/.config/Claude/claude_desktop_config.json

Step 3: Add MCP Server Configuration

Open your config file and add the Petstore MCP server:

{
  "mcpServers": {
    "petstore": {
      "command": "node",
      "args": ["/path/to/petstore-mcp-server/dist/index.js"],
      "env": {
        "PETSTORE_API_KEY": "your_api_key_here",
        "PETSTORE_API_BASE": "https://api.petstoreapi.com/v1"
      }
    }
  }
}

Configuration options:

command: Node.js executable

args: Path to the MCP server script

env.PETSTORE_API_KEY: Your API key (required)

env.PETSTORE_API_BASE: API base URL (optional, defaults to production)

Step 4: Restart Claude Desktop

After saving the config file, restart Claude Desktop. The Petstore MCP server will automatically connect.

Step 5: Start Using

Now you can interact with PetstoreAPI using natural language:

You: Show me all available dogs

Claude: [Uses search_pets tool] I found 15 available dogs:
1. Buddy - Golden Retriever, 24 months old
2. Max - German Shepherd, 18 months old
...

You: Create an order for 2 bags of dog food

Claude: [Uses create_order tool] I've created your order:
- Order ID: 019b4141-e5f3-a1b7-c4d8-9f6e2a5b8c1d
- Total: $59.98

Available Tools and Resources

When connected, Claude Desktop can access the following:

Resources (Data Sources)

Resource URI	Name	Description
`petstore:///pets`	All Pets	List of all pets in the store
`petstore:///pets/available`	Available Pets	Pets available for adoption
`petstore:///orders`	All Orders	List of all orders

Tools (Actions)

Tool	Description
`get_pet`	Get details of a specific pet by ID
`search_pets`	Search for pets with filters (species, status, breed, age)
`create_pet`	Create a new pet in the store
`create_order`	Create a new order with items

Usage Examples

Example 1: Search for Pets

User prompt:

Show me all available dogs under 2 years old

Claude actions:

Calls search_pets tool with:

species: "DOG"

status: "AVAILABLE"

maxAge: 24

Receives list of matching dogs

Presents formatted results

Response:

I found 8 available dogs under 2 years old:

1. Buddy - Golden Retriever, 24 months, $150
2. Max - German Shepherd, 18 months, $200
3. Bella - Labrador, 12 months, $175
4. Charlie - Beagle, 20 months, $125
...

Would you like more details about any of these dogs?

Example 2: Get Pet Details

User prompt:

Tell me about 019b4132-70aa-764f-b315-e2803d882a24

Claude actions:

Calls get_pet tool with id: "019b4132-70aa-764f-b315-e2803d882a24"

Receives full pet details

Summarizes key information

Response:

Here are the details for 019b4132-70aa-764f-b315-e2803d882a24:

- Name: Buddy
- Species: DOG
- Breed: Golden Retriever
- Age: 24 months (2 years)
- Status: AVAILABLE
- Adoption Fee: $150.00
- Good with kids: Yes
- Good with dogs: Yes
- Good with cats: No

This friendly Golden Retriever would be great for a family with children!

Example 3: Create a Pet

User prompt:

Add a new cat named Whiskers, she's a Persian, 12 months old, available for $200

Claude actions:

Calls create_pet tool with:

name: "Whiskers"

species: "CAT"

breed: "Persian"

ageMonths: 12

status: "AVAILABLE"

adoptionFee: 200

Response:

I've created a new pet:
- Name: Whiskers
- Species: CAT
- Breed: Persian
- Age: 12 months
- Status: AVAILABLE
- Adoption Fee: $200.00

Pet ID: 019b4132-70aa-764f-b315-e2803d882a24

The pet is now available for adoption!

Example 4: Create an Order

User prompt:

I want to order 2 bags of dog food, ship to my address in San Francisco

Claude actions:

Asks for clarification on product details

Calls create_order tool with items and shipping address

Response:

I've created your order:

Order Details:
- Order ID: 019b4141-e5f3-a1b7-c4d8-9f6e2a5b8c1d
- Items:
  1. Dog Food (Premium) x2 - $29.99 each
- Subtotal: $59.98
- Shipping: San Francisco, CA 94102

Total: $59.98

You'll receive a confirmation email shortly.

Building Your Own MCP Server

If you want to create a custom MCP server for PetstoreAPI, here's a complete implementation:

Prerequisites

Server Implementation

How MCP Works

Claude Desktop                  MCP Server                    Petstore API
    │                               │                             │
    ├──── Initialize ──────────────>│                             │
    │<──── Capabilities ───────────┤                             │
    │                               │                             │
    ├──── List Tools ─────────────>│                             │
    │<──── Tool List ───────────────┤                             │
    │                               │                             │
    ├──── Call Tool (search_pets) ─>│                             │
    │                               │──── REST API ─────────────>│
    │                               │                             │
    │<──── Tool Result ─────────────┤<──── Response ─────────────┤

Key Components:

Resources: Data sources Claude can read (pets, orders)

Tools: Actions Claude can execute (search, create, update)

Prompts: Reusable prompt templates for common tasks

Troubleshooting

Server Not Connecting

Symptoms: MCP tools don't appear in Claude Desktop

Solutions:

Check config file syntax (valid JSON)

Verify path to MCP server script is correct

Check API key is set in environment

Restart Claude Desktop completely

Check Claude Desktop logs for errors

API Errors

Symptoms: Tools return error messages

Solutions:

Verify API key is valid

Check API base URL is correct

Test API key with curl:

Tools Not Appearing

Symptoms: No Petstore tools shown in Claude

Solutions:

Ensure MCP server is running

Check ListToolsRequestSchema handler is implemented

Verify tool schema is valid

Check Claude Desktop logs

Security Best Practices

Never log API keys - Use environment variables only

Validate all inputs - Before passing to API

Implement rate limiting - Protect your API quota

Use HTTPS only - Never expose API keys

Rotate keys regularly - Update your MCP server config

MCP Specification: https://modelcontextprotocol.io

MCP TypeScript SDK: https://github.com/modelcontextprotocol/typescript-sdk

Claude Desktop: https://claude.ai/download

Protocol Overview: All Protocols

REST API Guide: REST Protocol

PetstoreAPI MCP (Model Context Protocol) Guide

Quick Start - Claude Desktop Configuration#

Step 1: Get Your API Key#

Step 2: Find Your Config File#

Step 3: Add MCP Server Configuration#

Step 4: Restart Claude Desktop#

Step 5: Start Using#

Available Tools and Resources#

Resources (Data Sources)#

Tools (Actions)#

Usage Examples#

Example 1: Search for Pets#

Example 2: Get Pet Details#

Example 3: Create a Pet#

Example 4: Create an Order#

Building Your Own MCP Server#

Prerequisites#

Server Implementation#

How MCP Works#

Troubleshooting#

Server Not Connecting#

API Errors#

Tools Not Appearing#

Security Best Practices#

Related Resources#

Quick Start - Claude Desktop Configuration

Step 1: Get Your API Key

Step 2: Find Your Config File

Step 3: Add MCP Server Configuration

Step 4: Restart Claude Desktop

Step 5: Start Using

Available Tools and Resources

Resources (Data Sources)

Tools (Actions)

Usage Examples

Example 1: Search for Pets

Example 2: Get Pet Details

Example 3: Create a Pet

Example 4: Create an Order

Building Your Own MCP Server

Prerequisites

Server Implementation

How MCP Works

Troubleshooting

Server Not Connecting

API Errors

Tools Not Appearing

Security Best Practices

Related Resources