Skip to main content

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

# Sign up at https://api.petstoreapi.com to get your API key
# Or use the test key for development
export PETSTORE_API_KEY="your_api_key_here"

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 URINameDescription
petstore:///petsAll PetsList of all pets in the store
petstore:///pets/availableAvailable PetsPets available for adoption
petstore:///ordersAll OrdersList of all orders

Tools (Actions)

ToolDescription
get_petGet details of a specific pet by ID
search_petsSearch for pets with filters (species, status, breed, age)
create_petCreate a new pet in the store
create_orderCreate 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:
  1. Calls search_pets tool with:
    • species: "DOG"
    • status: "AVAILABLE"
    • maxAge: 24
  2. Receives list of matching dogs
  3. 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:
  1. Calls get_pet tool with id: "019b4132-70aa-764f-b315-e2803d882a24"
  2. Receives full pet details
  3. 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:
  1. 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:
  1. Asks for clarification on product details
  2. 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

npm install @modelcontextprotocol/sdk
npm install typescript tsx

Server Implementation

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import {
  CallToolRequestSchema,
  ListResourcesRequestSchema,
  ListToolsRequestSchema,
  ReadResourceRequestSchema,
} from '@modelcontextprotocol/sdk/types.js';

// Create MCP server
const server = new Server(
  {
    name: 'petstore-mcp-server',
    version: '1.0.0',
  },
  {
    capabilities: {
      resources: {},
      tools: {},
    },
  }
);

// Petstore API client
const PETSTORE_API_BASE = process.env.PETSTORE_API_BASE || 'https://api.petstoreapi.com/v1';
const API_KEY = process.env.PETSTORE_API_KEY;

async function fetchAPI(endpoint: string, options?: RequestInit) {
  const url = `${PETSTORE_API_BASE}${endpoint}`;
  const response = await fetch(url, {
    ...options,
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
      ...options?.headers,
    },
  });

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  return response.json();
}

// List available resources
server.setRequestHandler(ListResourcesRequestSchema, async () => {
  return {
    resources: [
      {
        uri: 'petstore:///pets',
        name: 'All Pets',
        description: 'List of all pets in the store',
        mimeType: 'application/json',
      },
      {
        uri: 'petstore:///pets/available',
        name: 'Available Pets',
        description: 'List of available pets for adoption',
        mimeType: 'application/json',
      },
    ],
  };
});

// List available tools
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: 'get_pet',
        description: 'Get details of a specific pet by ID',
        inputSchema: {
          type: 'object',
          properties: {
            id: {
              type: 'string',
              description: 'Pet ID (e.g., 019b4132-70aa-764f-b315-e2803d882a24)',
            },
          },
          required: ['id'],
        },
      },
      {
        name: 'search_pets',
        description: 'Search for pets with filters',
        inputSchema: {
          type: 'object',
          properties: {
            species: {
              type: 'string',
              enum: ['DOG', 'CAT', 'RABBIT', 'BIRD', 'REPTILE', 'OTHER'],
              description: 'Filter by species',
            },
            status: {
              type: 'string',
              enum: ['AVAILABLE', 'PENDING', 'ADOPTED', 'NOT_AVAILABLE'],
              description: 'Filter by status',
            },
          },
        },
      },
    ],
  };
});

// Handle tool calls
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  switch (name) {
    case 'get_pet': {
      const pet = await fetchAPI(`/pets/${args.id}`);
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(pet, null, 2),
          },
        ],
      };
    }

    case 'search_pets': {
      const params = new URLSearchParams();
      if (args.species) params.append('species', args.species);
      if (args.status) params.append('status', args.status);

      const pets = await fetchAPI(`/pets?${params.toString()}`);
      return {
        content: [
          {
            type: 'text',
            text: `Found ${pets.pagination?.totalItems || 0} pets:\n\n${JSON.stringify(pets, null, 2)}`,
          },
        ],
      };
    }

    default:
      throw new Error(`Unknown tool: ${name}`);
  }
});

// Start server
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error('Petstore MCP server running on stdio');
}

main().catch(console.error);

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:
  1. Check config file syntax (valid JSON)
  2. Verify path to MCP server script is correct
  3. Check API key is set in environment
  4. Restart Claude Desktop completely
  5. Check Claude Desktop logs for errors

API Errors

Symptoms: Tools return error messages Solutions:
  1. Verify API key is valid
  2. Check API base URL is correct
  3. Test API key with curl:
    curl -H "Authorization: Bearer YOUR_KEY" https://api.petstoreapi.com/v1/pets
    

Tools Not Appearing

Symptoms: No Petstore tools shown in Claude Solutions:
  1. Ensure MCP server is running
  2. Check ListToolsRequestSchema handler is implemented
  3. Verify tool schema is valid
  4. Check Claude Desktop logs

Security Best Practices

  1. Never log API keys - Use environment variables only
  2. Validate all inputs - Before passing to API
  3. Implement rate limiting - Protect your API quota
  4. Use HTTPS only - Never expose API keys
  5. Rotate keys regularly - Update your MCP server config