Petstore MCP Server

This is a Next.js project bootstrapped with create-next-app.

Getting Started

First, run the development server:

npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

Open http://localhost:3000 with your browser to see the result.

Related MCP server: mcp_sdk_petstore_api_44

Environment Variables

Set the following environment variables before running:

# Required for Calculator Basic API (Bearer token auth)
export CALCULATOR_BEARER_TOKEN=your-secret-token

OpenAPI Specifications

This server hosts multiple OpenAPI specifications:

List All Available Specs

curl http://localhost:3000/api/openapi

Get a Specific Spec

curl http://localhost:3000/api/openapi/calculator-basic

MCP Registry (v0.1)

MCP Registry–style APIs compatible with Consuming Registry Data and GitHub Copilot MCP registry. Data is read from static files at the project root:

• registry-index.json — index of all servers (name, version, and which file holds the server JSON)

• Single-server files (e.g. server.json, server-truefoundry.json) — one MCP ServerDetail object per file

• Collection files (e.g. truefoundry-registry-servers.json) — a registry list response ({ "servers": [{ "server": ..., "_meta": ... }] }) holding many servers in one file; the matching server is looked up by name + version and its _meta is preserved in API responses

Note: If serverName contains a slash (e.g. io.github.example/calculator-mcp), URL-encode it: io.github.example%2Fcalculator-mcp. Double-encoded names (e.g. com.example%252Fmy-server) are also accepted.

List all servers

curl "http://localhost:3000/v0.1/servers?limit=10"

List all versions of a server

curl "http://localhost:3000/v0.1/servers/io.github.example%2Fcalculator-mcp/versions"

Returns { "servers": [{ "server": ..., "_meta": ... }], "metadata": { "count": n } } sorted newest version first, or a 404 if the server is not in the registry.

Latest version of a server

curl "http://localhost:3000/v0.1/servers/io.github.example%2Fcalculator-mcp/versions/latest"

Specific version

curl "http://localhost:3000/v0.1/servers/io.github.example%2Fcalculator-mcp/versions/1.0.0"

TrueFoundry gateway servers

truefoundry-registry-servers.json bundles 10 com.truefoundry.truefoundry/* servers (TrueFoundry MCP gateway remotes) that are indexed in registry-index.json and served through all of the endpoints above, e.g.:

curl "http://localhost:3000/v0.1/servers/com.truefoundry.truefoundry%2Ftest-ci/versions/latest"

Adding servers

Edit registry-index.json to add { "name": "namespace/name", "version": "x.y.z" } entries. Each entry can optionally set "file" to point at its server JSON (defaults to server.json). The file may be either a single ServerDetail object or a collection file as described above; multiple index entries can point at the same collection file.

Calculator APIs

Calculator Basic (Bearer Token Authentication)

Requires Authorization: Bearer <token> header where token matches CALCULATOR_BEARER_TOKEN env var.

All endpoints support multiple HTTP methods: GET, POST, PUT, PATCH, DELETE, and HEAD.

Add two numbers:

Using POST/PUT/PATCH (with JSON body):

curl -X POST http://localhost:3000/api/calculator-basic/add \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-token" \
  -d '{"a": 10, "b": 5}'

Using GET/DELETE (with query parameters):

curl -X GET "http://localhost:3000/api/calculator-basic/add?a=10&b=5" \
  -H "Authorization: Bearer your-secret-token"

Using HEAD (headers only):

curl -X HEAD "http://localhost:3000/api/calculator-basic/add?a=10&b=5" \
  -H "Authorization: Bearer your-secret-token" \
  -v

Response: {"result": 15}

Subtract two numbers:

Using POST/PUT/PATCH (with JSON body):

curl -X POST http://localhost:3000/api/calculator-basic/subtract \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-token" \
  -d '{"a": 10, "b": 3}'

Using GET/DELETE (with query parameters):

curl -X GET "http://localhost:3000/api/calculator-basic/subtract?a=10&b=3" \
  -H "Authorization: Bearer your-secret-token"

Response: {"result": 7}

Update a value with an operation:

Using POST/PUT/PATCH (with JSON body):

curl -X PATCH http://localhost:3000/api/calculator-basic/update \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-token" \
  -d '{"value": 10, "operation": "add", "operand": 5}'

Using GET/DELETE (with query parameters):

curl -X GET "http://localhost:3000/api/calculator-basic/update?value=10&operation=add&operand=5" \
  -H "Authorization: Bearer your-secret-token"

Response: {"result": 15, "previousValue": 10, "operation": "add", "operand": 5}

Supported operations: add, subtract, multiply, divide

Note:

• GET, HEAD, and DELETE methods use query parameters

• POST, PUT, and PATCH methods use JSON request body

• All methods require Bearer token authentication

Calculator OAuth (OAuth 2.0 Authentication)

Requires Authorization: Bearer <oauth-token> header with a valid OAuth token (minimum 10 characters for demo).

Multiply two numbers:

curl -X POST http://localhost:3000/api/calculator-oauth/multiply \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-oauth-token-here" \
  -d '{"a": 6, "b": 7}'

Response: {"result": 42}

Docker Deployment

Build and run with Docker:

# Build the image
docker build -t mcp-poc-app .

# Run the container
docker run -p 3000:3000 -e CALCULATOR_BEARER_TOKEN=your-secret-token mcp-poc-app

Learn More

To learn more about Next.js, take a look at the following resources:

• Next.js Documentation - learn about Next.js features and API.

• Learn Next.js - an interactive Next.js tutorial.

You can check out the Next.js GitHub repository - your feedback and contributions are welcome!

Deploy on Vercel

The easiest way to deploy your Next.js app is to use the Vercel Platform from the creators of Next.js.

Check out our Next.js deployment documentation for more details.

Summary

Petstore - OpenAPI 3.1: This is a sample Pet Store Server based on the OpenAPI 3.1 specification.

Some useful links:

• OpenAPI Reference

• The Pet Store repository

• The source API definition for the Pet Store

For more information about the API: Find out more about Swagger

Table of Contents

• Getting Started

• Learn More

• Deploy on Vercel

• Installation

Installation

Install the MCP server as a Desktop Extension using the pre-built mcp-server.mcpb file:

Simply drag and drop the mcp-server.mcpb file onto Claude Desktop to install the extension.

The MCP bundle package includes the MCP server and all necessary configuration. Once installed, the server will be available without additional setup.

Or manually:

1. Open Cursor Settings

2. Select Tools and Integrations

3. Select New MCP Server

4. If the configuration file is empty paste the following JSON into the MCP Server Configuration:

{
  "mcpServers": {
    "Petstore": {
      "command": "npx",
      "args": [
        "petstore",
        "start",
        "--environment",
        "...",
        "--api-key",
        "..."
      ]
    }
  }
}

claude mcp add petstore npx petstore start -- --environment ... --api-key ...

Refer to Official Windsurf documentation for latest information

1. Open Windsurf Settings

2. Select Cascade on left side menu

3. Click on Manage MCPs. (To Manage MCPs you should be signed in with a Windsurf Account)

4. Click on View raw config to open up the mcp configuration file.

5. If the configuration file is empty paste the full json

{
  "mcpServers": {
    "Petstore": {
      "command": "npx",
      "args": [
        "petstore",
        "start",
        "--environment",
        "...",
        "--api-key",
        "..."
      ]
    }
  }
}

Refer to Official VS Code documentation for latest information

1. Open Command Palette

2. Search and open MCP: Open User Configuration. This should open mcp.json file

3. If the configuration file is empty paste the full json

{
  "mcpServers": {
    "Petstore": {
      "command": "npx",
      "args": [
        "petstore",
        "start",
        "--environment",
        "...",
        "--api-key",
        "..."
      ]
    }
  }
}

You need to do the following

1. Open claude Desktop

2. Open left hand side pane, then click on your Username

3. Go to Settings

4. Go to Developer tab (on the left hand side)

5. Click on Edit Config Paste the following config in the configuration

{
  "mcpServers": {
    "Petstore": {
      "command": "npx",
      "args": [
        "petstore",
        "start",
        "--environment",
        "...",
        "--api-key",
        "..."
      ]
    }
  }
}

npx petstore start --environment ... --api-key ...

For a full list of server arguments, run:

npx petstore --help