Solenya logoSolenya

MCP

Solenya exposes its catalog search tools over the Model Context Protocol at:

https://api.solenya.ai/v1/mcp

MCP is a standard way for LLM clients (Claude Code, Claude Desktop, LM Studio, Cursor, Postman, and any custom agent) to discover and invoke remote tools. Point a compliant client at the endpoint above with your usual Solenya headers and the model gains a search_catalog tool backed by your index — no bespoke integration required.

Local Testing (Claude Code, LM Studio, Postman)

For quick local exploration, most MCP-aware clients accept an HTTP server entry in a JSON config file. Use your access token and index UUID from the Authentication guide:

{
  "mcpServers": {
    "solenya": {
      "url": "https://api.solenya.ai/v1/mcp",
      "headers": {
        "Authorization": "Bearer eyJh...",
        "Solenya-Index-UUID": "0...",
        "Solenya-Customer-UUID": "00..."
      }
    }
  }
}

Where to put this file:

  • Claude Code — ~/.claude.json (or claude mcp add from the CLI). See the Claude Code MCP docs.
  • Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on Windows/Linux.
  • LM Studio — Program → Install → Edit mcp.json. See the LM Studio MCP guide.
  • Postman — New → MCP Request, paste the URL and headers. See Postman MCP.

Once connected, the client will list search_catalog (and any other tools we've registered) and the model can call it directly.

Security: treat MCP credentials like any other bearer token. Don't commit them, don't ship them to browser clients, and scope tokens to index:read:* when testing.

For production apps we recommend the Vercel AI SDK MCP client — it's the same client we use for our reference storefront chat.

Install:

npm install ai @ai-sdk/mcp
# or: bun add ai @ai-sdk/mcp

Create a per-request client inside a server route (never ship API keys to the browser):

import { createMCPClient } from "@ai-sdk/mcp";
import { streamText, stepCountIs } from "ai";
 
export async function POST(request: Request) {
  const mcpClient = await createMCPClient({
    transport: {
      type: "http",
      url: "https://api.solenya.ai/v1/mcp",
      headers: {
        Authorization: `Bearer ${process.env.SOLENYA_API_KEY}`,
        "Solenya-Index-UUID": process.env.SOLENYA_INDEX_UUID!,
        "Solenya-User-UUID": request.headers.get("Solenya-User-UUID")!,
      },
      redirect: "error", // prevent SSRF via server-supplied redirects
    },
  });
 
  try {
    const tools = await mcpClient.tools(); // auto-discover Solenya tools
 
    const result = streamText({
      model: /* your LLM provider */,
      messages: /* ... */,
      tools,
      toolChoice: "auto",
      stopWhen: stepCountIs(5),
      onFinish: () => mcpClient.close(),
      onAbort: () => mcpClient.close(),
    });
 
    return result.toUIMessageStreamResponse();
  } catch (err) {
    await mcpClient.close();
    throw err;
  }
}

A few conventions worth following:

  • Per-request client. Open the client on each request and close it in onFinish / onAbort. The AI SDK recommends this pattern for short-lived HTTP usage.
  • Explicit schemas (optional). Pass schemas: { search_catalog: { inputSchema, outputSchema } } to mcpClient.tools(...) when you want stricter types and to restrict the model to a subset of tools.
  • redirect: "error". Prevents an upstream redirect from pointing the client somewhere unexpected (SSRF guard).
  • User UUID passthrough. Forward the end user's Solenya-User-UUID so search is personalised and events attribute correctly — see Authentication.

MCP Apps (MCP UI)

New. MCP Apps is a freshly-landed extension to the Model Context Protocol, and Solenya is among the first commerce APIs to ship it in production. If you're integrating today, you're on the leading edge — expect the surface area to evolve alongside the upstream spec.

MCP Apps (sometimes called MCP UI) is an MCP extension that lets a server return a rich, interactive UI snippet — not just text — as a tool result. Instead of the model describing a product card in prose, the server ships an HTML/React fragment that the host renders inline. Read the spec: modelcontextprotocol.io/extensions/apps/overview.

Further Reading