MCP API reference
This page is the technical reference for developers integrating with the ScentSell MCP server.
Server details
| Property | Value |
|---|---|
| Base URL | https://mcp.scentsell.com.au |
| MCP endpoint | /api/mcp |
| Transport | Streamable HTTP (MCP spec 2025-11-25) |
| Authentication | OAuth 2.1 with PKCE + Dynamic Client Registration |
| Tools exposed | 62 (13 cabinet/marketplace reads + 13 mutations + 28 SniffBot agent + 8 utility) |
| Version header | serverInfo.version auto-bumps per deploy (1.<git-sha-7>.<10min-bucket>) so clients cache-bust automatically |
Endpoints
| Method | Path | Description |
|---|---|---|
| POST | /api/mcp | Main MCP endpoint — send tool calls here |
| GET | /.well-known/oauth-authorization-server | OAuth metadata (RFC 8414) |
| POST | /oauth/register | Dynamic client registration |
| GET | /oauth/authorize | OAuth authorisation endpoint |
| POST | /oauth/consent | OAuth consent endpoint |
| POST | /oauth/token | OAuth token endpoint |
| GET | /health | Server health check |
Authentication
ScentSell MCP uses OAuth 2.1 with PKCE. The server supports dynamic client registration as per the MCP spec.
Required OAuth scopes
The server grants access to all 62 tools upon successful authorisation. There is no granular scope system — a valid Premium user token grants full read/write access to their own cabinet, shelves, wishlist, wear history, marketplace listings, and SniffBot Oracle.
Token format
Bearer tokens are issued as JWT-style opaque tokens. Include in the Authorization header:
Authorization: Bearer <your_token>
Premium enforcement
Requests from non-Premium accounts receive:
HTTP/1.1 403 Forbidden
{
"error": "premium_required",
"message": "MCP access requires a ScentSell Premium subscription.",
"upgrade_url": "https://scentsell.com.au/subscribe"
}
Rate limiting
| Limit | Value |
|---|---|
| Requests per minute | 100 per user |
| Rate limit header | X-RateLimit-Remaining |
| Throttle response | HTTP 429 with retry_after_ms |
Available tools
See Tools reference for full documentation of all 62 tools.
CORS
The server accepts cross-origin requests from any origin:
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization, Mcp-Session-Id
Next steps: