What an assistant can do with it
Questions like “what UGC came in yesterday?”, “which posts drove the most add-to-carts last month?” or “do we have any content for the linen shirt?” get answered from your account, not from the open web. The server exposes the same tools the dashboard’s AI assistant uses, so it reads the same data the dashboard does.
Read tools (every key)
| Tool | What it returns |
|---|---|
search_posts | Find posts by keyword in the caption, or filter by source (Instagram, TikTok and so on). |
get_top_posts | Your best-performing posts, ranked by likes and engagement. |
get_recent_posts | Posts that came in over a date range, most recent first (the last 24 hours by default). |
search_products | Look up products in your catalogue by name, SKU or category. |
find_ugc_for_product | Posts for a product: the ones tagged with it, plus posts that look similar. |
identify_product_in_post | For one post, the catalogue products it most likely shows, ranked. |
list_albums | Your albums and content feeds. |
list_layouts | Your galleries, whether each is active, and which albums feed them. |
get_conversion_analytics | Attributed revenue, orders, add-to-carts and conversion rates over a date range, overall or by gallery, post, product, platform or media type. |
get_engagement_analytics | Impressions, visitors, clicks, click-through rate and video interactions, with device and location splits. |
get_product_analytics | Product figures: platform breakdown, status, categories and rating stats. |
get_post_analytics | Post figures: sentiment, intent breakdown and moderation stats. |
Write tools (keys with write access only)
| Tool | What it does |
|---|---|
tag_product_on_post | Tag one of your products on a post, with an optional hotspot position. Existing tags are kept. |
untag_product_from_post | Remove one product tag from a post (every slide, or one slide). Other tags are kept. |
publish_gallery | Switch a gallery on or off on your storefront. Its content and settings are unchanged. |
A write does exactly what the same action in the dashboard does: a new tag is merged into the post’s tags, synced to Shopify product metafields and copied to the post’s duplicates, and the widget cache is refreshed; publishing a gallery refreshes its cache too. Post, product and gallery ids must belong to your account, and your plan’s product-tagging allowance applies. Every write attempt, refused ones included, is recorded in the audit log with the key that made it.
Connect today with an API key
- In the Idukki dashboard open Settings, then the AI tools (MCP) tab under Integrations, and create a key. Give it a name you will recognise later, and tick write access only if the assistant should be able to tag and publish.
- Copy the key. It starts with
idk_mcp_and is shown once: Idukki keeps only a hash of it. - Add the server to your client with the URL
https://api.idukki.io/mcpand the headerAuthorization: Bearer <your key>. Examples below.
claude mcp add --transport http idukki https://api.idukki.io/mcp --header "Authorization: Bearer YOUR_IDUKKI_MCP_KEY"{
"mcpServers": {
"idukki": {
"url": "https://api.idukki.io/mcp",
"headers": { "Authorization": "Bearer YOUR_IDUKKI_MCP_KEY" }
}
}
}{
"mcpServers": {
"idukki": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://api.idukki.io/mcp", "--header", "Authorization:${IDUKKI_AUTH}"],
"env": { "IDUKKI_AUTH": "Bearer YOUR_IDUKKI_MCP_KEY" }
}
}
}Keys and access
- A key belongs to one Idukki account and can only reach that account’s data.
- New keys are read-only. Write access is a separate switch per key, which you can turn on or off later.
- The tab lists your keys by name and prefix with when each was last used. Revoke one and it stops working on the next request.
- Make one key per assistant or teammate, so revoking one never cuts off the others and the audit log says which one acted.
For developers
JSON-RPC 2.0 over HTTP (MCP Streamable HTTP), protocol version 2024-11-05, at POST /mcp. Supported methods: initialize, ping, tools/list and tools/call; batches (an array body) are accepted and notifications get no reply. Authenticate with Authorization: Bearer <key> (an x-api-key header also works). A read-only key does not see the write tools in tools/list and gets error -32003 if it calls one. A refusal you can fix, such as an id outside your account, comes back as a tool result with isError: true.
curl -s https://api.idukki.io/mcp \
-H "Authorization: Bearer YOUR_IDUKKI_MCP_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'Not the same as the agent feed MCP
Idukki also runs a public, read-only MCP endpoint per store at POST /agent-feed/{bguid}/mcp, for AI shopping agents rather than for you. It needs no key and serves only rights-cleared content: list_products, search_ugc, get_product_ugc, get_reviews and get_aggregate_rating. The server on this page is the private one, behind your key, with your analytics in it. Agentic commerce covers the public side.