{"name":"Throwly MCP Server","description":"API for AI agents to interact with the Throwly marketplace - a sustainable, point-based marketplace for college students. Includes secure authentication system for agents to register, login, and perform authenticated actions.","version":"3.0.0","documentation":{"openapi":"https://mcp.throwly.co/openapi.json","ai_plugin":"https://mcp.throwly.co/.well-known/ai-plugin.json","tool_discovery":"https://mcp.throwly.co/mcp/tools"},"authentication":{"description":"Agents should register or login to get an auth_token. This token proves account ownership and is required for secure actions like creating listings.","flow":["1. check_username_available - verify username is free","2. register_agent - create account, receive auth_token","3. Store auth_token securely","4. Use auth_token in create_listing and other authenticated calls","OR: login_agent - if account already exists, get new auth_token"],"token_info":{"format":"64-character hex string","expiration":"30 days","storage":"Agent should store token securely (e.g., environment variable)","refresh":"Call login_agent to get a new token"}},"available_tools":[{"name":"check_username_available","endpoint":"POST /mcp/tools/check_username_available","description":"Check if username is available for registration","parameters":{"username":"string (required) - username to check"},"example":{"username":"my_agent_bot"}},{"name":"register_agent","endpoint":"POST /mcp/tools/register_agent","description":"Create a new agent account. Returns auth_token for authenticated actions.","parameters":{"email":"string (required) - email address","password":"string (required) - minimum 6 characters","username":"string (required) - unique username","firstName":"string - optional","lastName":"string - optional","city":"string - optional location"},"example":{"email":"agent@example.com","password":"secure123","username":"my_agent"}},{"name":"login_agent","endpoint":"POST /mcp/tools/login_agent","description":"Login to existing account. Returns auth_token.","parameters":{"email":"string - use this OR username","username":"string - use this OR email","password":"string (required)"},"example":{"email":"agent@example.com","password":"secure123"}},{"name":"logout_agent","endpoint":"POST /mcp/tools/logout_agent","description":"Invalidate current auth_token","parameters":{"auth_token":"string (required)"}},{"name":"get_my_profile_auth","endpoint":"POST /mcp/tools/get_my_profile_auth","description":"Get your profile using auth_token","parameters":{"auth_token":"string (required)"}},{"name":"list_listings","endpoint":"POST /mcp/tools/list_listings","description":"Browse marketplace listings with optional filters","parameters":{"limit":"number (default: 20) - max results to return","categoryId":"string - filter by category ID (use get_categories to see IDs)","type":"'all' | 'free' | 'paid' - filter by listing type","latitude":"number - for location-based search","longitude":"number - for location-based search","radiusMiles":"number (default: 10) - search radius"},"example":{"limit":5,"type":"free"}},{"name":"nearby_listings","endpoint":"POST /mcp/tools/nearby_listings","description":"Find listings near a city - just enter a city name!","parameters":{"city":"string (required) - city name (e.g. 'Austin', 'San Francisco', 'Ames')","limit":"number (default: 20) - max results","categoryId":"string - optional category filter","type":"'all' | 'free' | 'paid' - listing type filter","radiusMiles":"number (default: 25) - search radius"},"example":{"city":"Austin","limit":10,"type":"free"}},{"name":"search_listings","endpoint":"POST /mcp/tools/search_listings","description":"Search listings by title or keywords","parameters":{"query":"string (required) - search terms","limit":"number (default: 10) - max results"},"example":{"query":"desk chair","limit":5}},{"name":"get_listing","endpoint":"POST /mcp/tools/get_listing","description":"Get full details of a specific listing including seller info","parameters":{"id":"string (required) - the listing ID"},"example":{"id":"abc123"}},{"name":"get_categories","endpoint":"POST /mcp/tools/get_categories","description":"Get all available marketplace categories with their IDs","parameters":{}},{"name":"get_user_profile","endpoint":"POST /mcp/tools/get_user_profile","description":"Get a user's profile by their user ID","parameters":{"userId":"string (required) - the user's ID"}},{"name":"check_username","endpoint":"POST /mcp/tools/check_username","description":"Check if a Throwly username exists and get basic user info","parameters":{"username":"string (required) - username to check"},"example":{"username":"elvis"}},{"name":"get_my_listings","endpoint":"POST /mcp/tools/get_my_listings","description":"Get all listings for a specific user","parameters":{"username":"string - Throwly username (or use userId)","userId":"string - user ID","includesSold":"boolean (default: false) - include sold items"},"example":{"username":"elvis"}},{"name":"upload_images","endpoint":"POST /mcp/tools/upload_images","description":"Upload images for creating a listing. Returns URLs.","parameters":{"imageBase64Array":"array (required) - array of base64 encoded image strings"}},{"name":"estimate_price","endpoint":"POST /mcp/tools/estimate_price","description":"Get AI price estimate for an item. Uses images to suggest price, title, and category.","parameters":{"imageUrls":"array (required) - array of image URLs","description":"string - item description","city":"string - city name for local pricing context","username":"string (required) - Throwly username for API access"},"example":{"imageUrls":["https://..."],"description":"Vintage lamp","city":"Austin","username":"elvis"}},{"name":"create_listing","endpoint":"POST /mcp/tools/create_listing","description":"Create a new listing. AI determines title, category, and price from images. Fails if images cannot be analyzed.","authentication":"auth_token recommended (proves you own the account)","parameters":{"auth_token":"string (RECOMMENDED) - your auth_token from login/register","imageUrls":"array (required) - clear, well-lit image URLs of the item","city":"string (required) - city name for location","description":"string - item description (helps AI determine price)","price":"number (default: 0) - price in dollars (0 = free/points-based)","categoryId":"string - category override (AI determines if not provided)","size":"string - size override: Small/Medium/Large (AI estimates if not provided)"},"example":{"auth_token":"your_token_here","imageUrls":["https://..."],"city":"Austin"}},{"name":"edit_listing","endpoint":"POST /mcp/tools/edit_listing","description":"Edit an existing listing. You can only edit your own listings.","authentication":"auth_token required","parameters":{"auth_token":"string (required) - your auth_token","listing_id":"string (required) - ID of listing to edit","title":"string - new title","description":"string - new description","price":"number - new price (0 for free)","categoryId":"string - new category ID","size":"string - Small, Medium, or Large","city":"string - new city location"},"example":{"auth_token":"your_token_here","listing_id":"abc123","title":"Updated Title","price":15}},{"name":"delete_listing","endpoint":"POST /mcp/tools/delete_listing","description":"Delete a listing. You can only delete your own listings. Requires confirmation.","authentication":"auth_token required","parameters":{"auth_token":"string (required) - your auth_token","listing_id":"string (required) - ID of listing to delete","confirm":"boolean - set to true to confirm deletion"},"example":{"auth_token":"your_token_here","listing_id":"abc123","confirm":true}},{"name":"submit_feedback","endpoint":"POST /mcp/tools/submit_feedback","description":"Submit feedback to the Throwly team","parameters":{"description":"string (required) - feedback message","username":"string - optional Throwly username"},"example":{"description":"Great app!","username":"elvis"}},{"name":"get_faq","endpoint":"POST /mcp/tools/get_faq","description":"Get Throwly FAQ - learn how the app works","parameters":{}},{"name":"get_curbside_alerts","endpoint":"POST /mcp/tools/get_curbside_alerts","description":"Get recent curbside alerts (free items spotted on the street)","parameters":{"limit":"number (default: 10) - max results"}}],"available_resources":[{"name":"categories","endpoint":"GET /mcp/resources/categories","description":"All marketplace categories as JSON"},{"name":"stats","endpoint":"GET /mcp/resources/stats","description":"Current marketplace statistics (active listings, total users)"}],"quick_start":{"step1":"GET /mcp/resources/categories to see available categories","step2":"POST /mcp/tools/list_listings with {\"limit\": 10} to browse items","step3":"POST /mcp/tools/search_listings with {\"query\": \"your search\"} to find specific items","step4":"POST /mcp/tools/get_listing with {\"id\": \"listing_id\"} to get full details"},"example_requests":{"list_furniture":{"method":"POST","url":"https://mcp.throwly.co/mcp/tools/list_listings","body":{"limit":5,"categoryId":"OBXXqTPp4mOlSsITTrIG"}},"search_for_desk":{"method":"POST","url":"https://mcp.throwly.co/mcp/tools/search_listings","body":{"query":"desk","limit":3}}},"about_throwly":{"website":"https://throwly.co","app_store":"https://apps.apple.com/us/app/throwly/id1615326703","play_store":"https://play.google.com/store/apps/details?id=com.Gutter","description":"Throwly is the #1 point-based marketplace for college students. Give stuff, earn points, get what you need - with built-in delivery."}}