Example

Build an MCP server for Swagger Petstore

Use the public Petstore OpenAPI spec to create a safe demo MCP server for search_docs, execute, and read-only endpoint testing.

Jun 25, 20267 min readBeginner

Steps

Use the Petstore raw OpenAPI URL

The public Petstore spec is useful because it is stable, familiar, and safe for demos. It should not be treated as a production API design model.

Example

https://petstore.swagger.io/v2/swagger.json

Generate the server

Create the server from the raw spec. Name it clearly so teammates know it is a demo endpoint.

Example

curl -sS -X POST https://astrail.dev/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "source_type": "openapi_url",
    "source_url": "https://petstore.swagger.io/v2/swagger.json",
    "name": "Petstore MCP demo",
    "generation_mode": "code"
  }'

Find the list pets operation

Use search_docs for intent-based lookup. This mirrors how an agent should discover the right route before calling it.

Example

curl -sS -X POST https://astrail.dev/api/mcp/SERVER_ID \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_docs","arguments":{"query":"list pets by status"}}}'

Execute a read-only call

Use a read-only operation first. This proves endpoint routing, parameter mapping, and response shaping without changing demo state.

Example

curl -sS -X POST https://astrail.dev/api/mcp/SERVER_ID \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "execute",
      "arguments": {
        "code": "async function run(client) { return await client.pet.findByStatus({ status: [\"available\"] }); }"
      }
    }
  }'

Production checks

search_docs finds the expected Petstore operation.

The read-only execute call returns a compact response.

Missing or invalid status values return schema errors.

Demo docs clearly label the endpoint as non-production.

FAQ

Why use Swagger Petstore for MCP demos?

It is public, familiar, and easy to reset mentally. That makes it useful for client connection examples and schema validation tutorials.

Is Petstore a good production API template?

No. Use it for learning the MCP flow, then apply stricter auth, error, and endpoint review practices to real APIs.