MCP Server Documentation

What is MCP?

The Model Context Protocol (MCP) is a standardized protocol for connecting AI assistants and tools. Unlike REST APIs that use HTTP endpoints, MCP uses a tool-based architecture where capabilities are exposed as callable tools with defined schemas.

MCP provides several advantages:

• Structured tool definitions with input/output schemas
• Built-in authentication and authorization via OAuth metadata
• Streamable HTTP transport for efficient real-time communication
• Seamless integration with MCP-compatible clients

Prerequisites

Before connecting to the MCP server, you'll need:

• An MCP-compatible client (e.g., Claude Desktop, custom MCP client, or development tools)
• A Facetize account with an API key. See the API Documentation for account setup instructions.
• Credits in your account. Each tool call costs $0.01. See Pricing for details.

Server Connection

Connect to the Facetize MCP server using the following configuration:

Basic Client Configuration

Configure your MCP client to connect to the Facetize server. Here's an example configuration:

{
  "mcpServers": {
    "facetize": {
      "url": "https://facetize.io/api/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer facetize_xxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Replace facetize_xxxxxxxxxxxxxxxxxxxxx with your actual API key from your API keys page.

Tool-Based Architecture

MCP servers expose capabilities as tools rather than traditional REST endpoints. Each tool has:

• A unique name identifier
• A description of what the tool does
• An input schema defining required and optional parameters
• An output schema defining the response structure

Clients discover available tools through the protocol, then call them with structured parameters. The server validates inputs against the schema and returns structured results.

Streamable HTTP Transport

The Facetize MCP server uses Streamable HTTP as its transport method. This enables efficient, real-time communication between clients and the server:

Streamable HTTP combines the reliability of HTTP with the efficiency of streaming, making it ideal for AI assistants and interactive applications that need responsive, real-time tool execution.

Protocol Communication Flow

Communication follows the MCP protocol over Streamable HTTP:

1. Connection Initialization: Client establishes a Streamable HTTP connection to the server endpoint
2. Tool Discovery: Client requests available tools, receiving their schemas and descriptions
3. Tool Execution: Client sends JSON-RPC 2.0 tool call requests over the stream
4. Streaming Results: Server streams back responses as they become available
5. Connection Management: Connection remains open for multiple tool calls, reducing overhead

All protocol messages use JSON-RPC 2.0 format, ensuring compatibility with standard MCP clients and libraries.

OAuth-Protected Resource Metadata

The MCP server implements OAuth 2.0 protected resource metadata at /.well-known/oauth-protected-resource. This endpoint provides:

• Authentication requirements and supported methods
• Scope definitions and requirements
• Resource server metadata for OAuth clients

MCP clients use this metadata to understand authentication requirements before establishing the Streamable HTTP connection. The Facetize server uses Bearer token authentication with API keys.

Server Endpoint

The MCP server is accessible at /api/mcp using Streamable HTTP. The server supports standard HTTP methods for protocol operations:

• GET: Initialize the Streamable HTTP connection and discover available tools
• POST: Send JSON-RPC 2.0 messages including tool calls, with responses streamed back
• DELETE: Close the connection and cleanup resources

The Streamable HTTP connection allows multiple tool calls over a single persistent connection, improving efficiency and reducing latency compared to traditional request-response patterns.

OAuth Metadata Endpoint

Before making tool calls, MCP clients should query the OAuth metadata endpoint to understand authentication requirements:

GET https://facetize.io/.well-known/oauth-protected-resource

This endpoint returns metadata about the protected resource, including supported authentication methods and required scopes. The Facetize server requires Bearer token authentication with the translate scope.

Bearer Token Authentication

All MCP tool calls require authentication using a Bearer token. Use the same API keys as the REST API:

Authorization: Bearer facetize_xxxxxxxxxxxxxxxxxxxxx

API keys start with the prefix facetize_ and can be created from your API keys page.

Scope Requirements

The MCP server requires the translate scope for all tool calls. This scope is automatically granted when using a valid API key.

When configuring your MCP client, ensure that:

• The API key is included in the Authorization header
• The client requests the translate scope
• Authentication is performed before making tool calls

Authentication Flow

The typical authentication flow for MCP clients:

1. Query the OAuth metadata endpoint to understand requirements
2. Include the Bearer token in the Authorization header
3. Initialize the MCP connection with authentication
4. Discover available tools (the server validates authentication)
5. Make authenticated tool calls

Invalid Authentication

If authentication fails, the server will reject the connection or tool call. The error format depends on the transport method, but typically includes:

• Missing or invalid API key
• Expired or revoked API key
• Missing required scope

See the Error Handling section for details on error formats.

translate

Translates natural language ecommerce queries into structured taxonomy filters. Returns categories, attributes, values, vendors, price ranges, GTINs, model numbers, availability status, tags, collections, and query terms for name-based product search, each with confidence scores where applicable.

{
  "query": string,        // Required: Natural language query (1-255 characters)
  "context": string       // Optional: Context to help disambiguate (max 255 characters)
}

{
  "categories": {
    "gid1": {
      "name": "Apparel",
      "confidence": 0.95
    }
  },
  "attributes": {
    "gid2": {
      "name": "Color",
      "confidence": 0.92,
      "values": {
        "gid3": {
          "name": "Blue",
          "confidence": 0.88
        }
      }
    }
  },
  "vendors": ["Nike", "Adidas"],
  "priceRange": {
    "min": 10,
    "max": 50
  },
  "gtin": ["1234567890123"],
  "modelNumbers": ["SKU-ABC123"],
  "availability": true,
  "tags": ["sale", "new-arrival"],
  "collections": ["Summer"],
  "queryTerms": ["iPhone 15 Pro", "Nike Air Max"],
  "options": [
    {
      "name": "Color",
      "values": ["Blue"]
    }
  ]
}

MCP Tool Call Format

When calling a tool via MCP, the request follows the MCP protocol format. Here's the structure:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "translate",
    "arguments": {
      "query": "blue t-shirts under $50",
      "context": "this is a clothing store"
    }
  }
}

Example Tool Call

Here's a complete example of calling the translate tool:

POST https://facetize.io/api/mcp
Authorization: Bearer facetize_xxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "translate",
    "arguments": {
      "query": "blue t-shirts under $50"
    }
  }
}

Example Tool Response

The server responds with the tool result in MCP format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"categories\":{\"gid_123\":{\"name\":\"Apparel\",\"confidence\":0.95}},\"attributes\":{\"gid_456\":{\"name\":\"Color\",\"confidence\":0.92,\"values\":{\"gid_789\":{\"name\":\"Blue\",\"confidence\":0.88}}},\"gid_101\":{\"name\":\"Product Type\",\"confidence\":0.85,\"values\":{\"gid_102\":{\"name\":\"T-Shirt\",\"confidence\":0.82}}}},\"vendors\":[],\"priceRange\":{\"max\":50},\"gtin\":[],\"modelNumbers\":[],\"options\":[{\"name\":\"Color\",\"values\":[\"Blue\"]},{\"name\":\"Product Type\",\"values\":[\"T-Shirt\"]}]}"
      }
    ],
    "isError": false
  }
}

The actual translation result is embedded as a JSON string in the text content. Parse this JSON to access the structured data.

Client Configuration Examples

Different MCP clients may have different configuration formats. Here are examples for common clients:

{
  "mcpServers": {
    "facetize": {
      "url": "https://facetize.io/api/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer facetize_xxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

import { Client } from '@modelcontextprotocol/sdk/client/index.js';

const client = new Client({
  name: 'facetize-client',
  version: '1.0.0',
}, {
  transport: {
    type: 'streamable-http',
    url: 'https://facetize.io/api/mcp',
    headers: {
      'Authorization': 'Bearer facetize_xxxxxxxxxxxxxxxxxxxxx'
    }
  }
});

await client.connect();

// Call the translate tool
const result = await client.callTool({
  name: 'translate',
  arguments: {
    query: 'blue t-shirts under $50'
  }
});

console.log(JSON.parse(result.content[0].text));

Tool Error Format

When a tool call fails, the server returns an error in the MCP result format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"error\": \"Error type\", \"message\": \"Error message\"}"
      }
    ],
    "isError": true
  }
}

The isError field indicates an error, and the error details are in the text content as JSON.

Rate Limit Errors

When rate limits are exceeded, the tool returns an error with rate limit information:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"error\": \"Rate limit exceeded\", \"message\": \"Too many requests. Please wait before making another request.\", \"tier\": 1, \"limits\": {\"perMinute\": {\"limit\": 10, \"remaining\": 0, \"reset\": \"2024-01-01T12:01:00Z\"}, \"perHour\": {\"limit\": 100, \"remaining\": 50, \"reset\": \"2024-01-01T13:00:00Z\"}, \"perDay\": {\"limit\": 1000, \"remaining\": 900, \"reset\": \"2024-01-02T00:00:00Z\"}}, \"retryAfter\": 45}"
      }
    ],
    "isError": true
  }
}

Note: Unlike REST API responses, rate limit information is not available in HTTP headers. All information is included in the error response body. See Rate Limits for tier details.

Insufficient Balance Errors

When account balance is too low, the tool returns an insufficient balance error:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"error\": \"Insufficient balance\", \"message\": \"Not enough credits to continue using the API. Please add credits to your account.\"}"
      }
    ],
    "isError": true
  }
}

Add credits from your billing page to continue using the service.

Authentication Errors

If authentication fails, the connection may be rejected or tool calls will fail with an authentication error:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32000,
    "message": "Authentication required",
    "data": {
      "error": "Invalid or expired API key"
    }
  }
}

Validation Errors

If tool arguments don't match the schema, a validation error is returned:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"error\": \"Validation error\", \"message\": \"query: Query is required\"}"
      }
    ],
    "isError": true
  }
}

Handling Errors in Your Client

When implementing error handling in your MCP client:

• Check the isError field in the result
• Parse the error JSON from the text content
• For rate limit errors, respect the retryAfter value
• For authentication errors, verify your API key is valid
• For validation errors, check the error message for specific field issues
• Implement exponential backoff for retries on transient errors