petfinder

This MCP server provides a single-file Petfinder integration that exposes MCP tools over an HTTP server powered by Bun. It handles OAuth token management automatically, caches tokens per client, and enables you to search for adoptable pets and organizations via the Petfinder v2 API. Tools are accessed through the MCP protocol by POSTing to /mcp with a payload that specifies the tool name (e.g., pets.search) and the input parameters (such as location, type, breed, or IDs). Clients can supply Petfinder credentials as query parameters on the server URL for authentication, and the server will inject Bearer tokens when calling Petfinder endpoints. Typical usage involves starting the server, then invoking MCP tools like pets.search or organizations.search through a standard MCP client (e.g., MCP Inspector) or by direct HTTP requests. The server includes endpoints for health checks and returns JSON with results from Petfinder, including pet details, organization data, and available animal types.

Key capabilities include:

• OAuth token management with automatic refresh (per client-id) using the client credentials flow
• Search for adoptable pets by type, breed, location, distance, and status
• Retrieve details for specific pets and organizations
• List and detail animal types and breeds
• All responses include CORS headers for browser access

Prerequisites:

• Petfinder API credentials (Client ID and Client Secret)
• Bun installed (version 1.2.19 or newer) or an environment that can run Bun scripts

Installation steps:

1. Clone or download the repository containing simple-mcp-server.ts and the README.
2. Install dependencies ( Bun handles dependencies, no npm install required ):

bun install

3. Start the MCP server:

bun run simple-mcp-server.ts

4. (Optional) If you use the MCP Inspector, start it with your server URL including credentials:

npx @modelcontextprotocol/inspector "http://localhost:3000/mcp?client-id=your-client-id&client-secret=your-client-secret"

Configure your credentials by passing them as query parameters when connecting to the MCP server, for example:

http://localhost:3000/mcp?client-id=your-client-id&client-secret=your-client-secret

Notes and tips:

• Authentication is done entirely via query parameters on the MCP URL; no environment variables are required for credentials.
• The server caches access tokens in memory per client, with tokens expiring after 3600 seconds and auto-refreshing when needed.
• Use the MCP Inspector or direct HTTP requests to test tools like pets.search, pets.get, organizations.search, and organizations.get.
• Ensure your Petfinder API credentials have the necessary permissions (Client Credentials flow) and that your Bun environment is configured to allow outbound HTTP requests to api.petfinder.com.
• If you encounter CORS issues when calling from a browser, the server enables Access-Control-Allow-Origin: * on all responses.
• The repository’s single-file server approach may be sensitive to various deployment environments; for Docker deployments, you can adapt the Bun-based entrypoint accordingly.