> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adgenticplatform.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart Guide
> Run your first calls to the Adgentic MCP Server in minutes.
## Prerequisites
Make sure you have Python 3.11+ and the fastmcp library installed.
* Python 3.11+
* fastmcp client library
```bash theme={null}
pip install fastmcp
```
## Set Your Adgentic API Key
```bash theme={null}
# macOS/Linux
export ADGENTIC_API_KEY=
# Windows
set ADGENTIC_API_KEY=
```
If your MCP server is deployed with ADGENTIC\_API\_KEY in its environment, you can omit api\_key in the call.
## Run the Sample Script
```bash Python highlight={6-9, 13,17,36} lines expandable theme={null}
import asyncio
import json
import os
from fastmcp import Client
MCP_URL = "https://mcp.adgenticplatform.com/mcp/"
API_KEY = "ADGENTIC_API_KEY"
#If it set as an environment variable:
API_KEY = os.environ.get("ADGENTIC_API_KEY")
async def quickstart():
async with Client(MCP_URL) as client:
# List available tools on the MCP server
tools = await client.list_tools()
print("Available tools:", [t.name for t in tools])
# --- Non-shopping example ---
print("\n--- Non-shopping test ---")
response1 = await client.call_tool(
"match_adgentic_products",
{
"prompt": "Write me a poem about summer",
"api_key": API_KEY,
"context": {"country": "US"},
},
)
# Convert the tool's response object into plain text
result1 = (getattr(response1, "text", None)
or (response1.content[0].text if getattr(response1, "content", None) else None)
or str(response1))
# Display it in a clean, readable JSON format
print(json.dumps(json.loads(result1), indent=2))
# --- Shopping example ---
print("\n--- Shopping test ---")
response2 = await client.call_tool(
"match_adgentic_products",
{
"prompt": "Iโm training for a marathon and need a waterproof GPS smartwatch under $300.",
"api_key": API_KEY,
"context": {"country": "US"},
},
)
result2 = (getattr(response2, "text", None)
or (response2.content[0].text if getattr(response2, "content", None) else None)
or str(response2))
print(json.dumps(json.loads(result2), indent=2))
if __name__ == "__main__":
asyncio.run(quickstart())
```
It is recommended to run this script using uv run for consistent dependency management and environment isolation.
```json title="Commercial Intent" theme={null}
{
"response": true,
"products": [
{
"basic_identity": {
"product_title": "Classic Red Sneakers",
"product_description": "Red running shoes for men and women",
"product_link": "https://shop.example.com/products/987",
"product_image_link": "https://cdn.example.com/products/red-shoes.jpg",
"currency": "USD",
"price": 89.0,
"availability": "In Stock",
"brand": "Example Brand"
},
"physical_characteristics": {
"color": "Red",
"size": "US 9",
"weight": "0.8 kg",
"material": "Synthetic Mesh"
},
"technical_specs": {
"sku": "SNK-RED-987",
"dimensions": "30 x 10 x 12 cm"
},
"functional_features": {
"water_resistant": false,
"breathable": true,
"slip_resistant": true
},
"compatability": {
"gender": ["Men", "Women"],
"sports": ["Running", "Casual Wear"]
},
"performance_metrics": {
"durability_score": 8.5,
"comfort_rating": 9.2
},
"content_and_packaging": {
"box_contents": ["1 Pair Sneakers"],
"packaging_material": "Recyclable Cardboard"
},
"warrant_and_certification": {
"warranty_period": "12 months",
"certifications": ["ISO 9001"]
},
"sustainability": {
"eco_friendly_materials": true,
"recyclable": true
},
"review_metrics": {
"average_rating": 4.6,
"review_count": 254
},
"user_context_tags": {
"ideal_use_case": "Daily running and casual wear",
"persona_fit": "Active lifestyle, fashion-conscious",
"lifestyle_alignment": "Urban, sporty"
},
"advertiser_info": {
"advertiser_name": "Example Shop",
"advertiser_website": "https://shop.example.com",
"advertiser_logo": "https://cdn.example.com/logo.png",
"advertiser_category": "Footwear & Apparel"
},
"monetization_info": {
"commission_rate": "12%",
"referral_period": "30 days"
}
}
]
}
```
```json title="Non-commercial Intent" theme={null}
{
"response": false,
"products": []
}
```
## Error Handling
| Error | Cause / Fix |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **401 Unauthorized** | Missing or invalid `ADGENTIC_API_KEY`. Set env var correctly or pass `api_key` in the tool call. |
| **400 Bad Request** | Malformed request (e.g. missing prompt or invalid context). Ensure payload contains `prompt` and valid JSON. |
| **500 Server Error** | Temporary issue on the Adgentic MCP server. Retry; if persists, contact support: [support@adgenticplatform.com](mailto:support@adgenticplatform.com) |
| **Timeouts & Connection Errors** | Network instability or unreachable server. Verify connectivity and endpoint: [https://mcp.adgenticplatform.com/mcp/](https://mcp.adgenticplatform.com/mcp/) |