# ComOS Federation Gateway MCP server

Multi-tenant MCP gateway for AI commerce. One connection, every store.

## Links
- Registry page: https://www.getdrio.com/mcp/io-github-ronrey-comos-federation
- Repository: https://github.com/ronrey/comos-federation
- Website: https://comos-portal.com

## Install
- Endpoint: https://mcp.comos-gateway.com/mcp
- Auth: Not captured

## Setup notes
- Remote endpoint: https://mcp.comos-gateway.com/mcp

## Tools
- federation_list_tenants - List all available tenants in the federation. Returns tenant IDs, names, and status. Endpoint: https://mcp.comos-gateway.com/mcp
- federation_tenant_info - Get detailed information about a specific tenant. Endpoint: https://mcp.comos-gateway.com/mcp
- federation_help - Get usage instructions for the MCP federation. Call this first to understand how to use the tools correctly. Endpoint: https://mcp.comos-gateway.com/mcp
- federation_catalog_search_multi - Search products (flat — one row per variant) across multiple tenants in parallel. Pass tenant_ids as an array of tenant IDs or "all" for every active tenant. Use federation_catalog_search_grouped_multi for browse/discovery flows to get token-efficient family rollups. Endpoint: https://mcp.comos-gateway.com/mcp
- federation_catalog_search_grouped_multi - Search product FAMILIES (variants of the same product grouped together) across multiple tenants in parallel. Prefer this for discovery — collapses size/color variants into one row per family with a price range and option breakdown. Drop to federation_catalog_search_multi when you need exact variant SKUs. Endpoint: https://mcp.comos-gateway.com/mcp
- federation_list_agents - List all configured agents with their status and next scheduled run. Requires authentication via auth_token. Endpoint: https://mcp.comos-gateway.com/mcp
- federation_run_agent - Manually trigger an agent to run immediately. Requires admin authentication via auth_token. Endpoint: https://mcp.comos-gateway.com/mcp
- federation_get_agent_runs - Get execution history for an agent. Requires authentication via auth_token. Endpoint: https://mcp.comos-gateway.com/mcp
- federation_agent_status - Get current status of all agents and the scheduler. Requires authentication via auth_token. Endpoint: https://mcp.comos-gateway.com/mcp
- federation_list_agent_types - List all available agent types that can be configured. Requires authentication via auth_token. Endpoint: https://mcp.comos-gateway.com/mcp
- catalog_search - Search for products by query, category, or browse all products. Use empty query to list all products. (Federated: requires tenant_id. For cart/orders, pass auth_token from POST /v1/auth/login. Product IDs are MongoDB ObjectIds from catalog_search.) FRESHNESS: Response includes a _meta block with catalog_version and fetched_at. This data is a snapshot — call federation_catalog_version before acting (cart_add_item, etc.) and re-fetch if the version has changed. Endpoint: https://mcp.comos-gateway.com/mcp
- catalog_search_grouped - Search for products grouped by family. Returns one row per product (e.g. 'VnM Cooling Vest') with its variants nested. Prefer this for browsing/discovery; use catalog_search for SKU-level actions. (Federated: requires tenant_id. For cart/orders, pass auth_token from POST /v1/auth/login. Product IDs are MongoDB ObjectIds from catalog_search.) FRESHNESS: Response includes a _meta block with catalog_version and fetched_at. This data is a snapshot — call federation_catalog_version before acting (cart_add_item, etc.) and re-fetch if the version has changed. Endpoint: https://mcp.comos-gateway.com/mcp
- catalog_get_product - Get detailed information about a specific product by its ID (Federated: requires tenant_id. For cart/orders, pass auth_token from POST /v1/auth/login. Product IDs are MongoDB ObjectIds from catalog_search.) FRESHNESS: Response includes a _meta block with catalog_version and fetched_at. This data is a snapshot — call federation_catalog_version before acting (cart_add_item, etc.) and re-fetch if the version has changed. Endpoint: https://mcp.comos-gateway.com/mcp
- catalog_categories - List all product categories with hierarchy information and product counts (Federated: requires tenant_id. For cart/orders, pass auth_token from POST /v1/auth/login. Product IDs are MongoDB ObjectIds from catalog_search.) Endpoint: https://mcp.comos-gateway.com/mcp
- catalog_create_category - Create a new product category (Federated: requires tenant_id. For cart/orders, pass auth_token from POST /v1/auth/login. Product IDs are MongoDB ObjectIds from catalog_search.) Endpoint: https://mcp.comos-gateway.com/mcp
- catalog_update_category - Update an existing product category (Federated: requires tenant_id. For cart/orders, pass auth_token from POST /v1/auth/login. Product IDs are MongoDB ObjectIds from catalog_search.) Endpoint: https://mcp.comos-gateway.com/mcp
- catalog_delete_category - Delete a product category (cannot delete if it has children or products) (Federated: requires tenant_id. For cart/orders, pass auth_token from POST /v1/auth/login. Product IDs are MongoDB ObjectIds from catalog_search.) Endpoint: https://mcp.comos-gateway.com/mcp
- catalog_deals - Find products that are currently on sale or have discounts. Also returns any email signup offer available. (Federated: requires tenant_id. For cart/orders, pass auth_token from POST /v1/auth/login. Product IDs are MongoDB ObjectIds from catalog_search.) FRESHNESS: Response includes a _meta block with catalog_version and fetched_at. This data is a snapshot — call federation_catalog_version before acting (cart_add_item, etc.) and re-fetch if the version has changed. Endpoint: https://mcp.comos-gateway.com/mcp
- cart_view - View the current shopping cart contents and total. REQUIRED: cartId must be provided on every call for cart persistence. Use customer email for authenticated users or a consistent ID like "guest-abc123" for guests. Also requires tenant_id. Endpoint: https://mcp.comos-gateway.com/mcp
- cart_add_item - Add a product to the shopping cart. If the product is already in the cart, its quantity will be increased. REQUIRED: cartId must be provided on every call for cart persistence. Use customer email for authenticated users or a consistent ID like "guest-abc123" for guests. Also requires tenant_id. FRESHNESS: Catalog data may change between turns. Before calling this tool, call federation_catalog_version({tenant_id}) and compare to the catalog_version in your last catalog_search _meta block. If they differ, re-fetch the catalog first — do not act on a stale productId. On SKU_NOT_FOUND, the response includes a current catalog inline; pick a new product from it rather than retrying the same productId. Endpoint: https://mcp.comos-gateway.com/mcp
- cart_update_quantity - Update the quantity of an item in the cart. REQUIRED: cartId must be provided on every call for cart persistence. Use customer email for authenticated users or a consistent ID like "guest-abc123" for guests. Also requires tenant_id. FRESHNESS: Catalog data may change between turns. Before calling this tool, call federation_catalog_version({tenant_id}) and compare to the catalog_version in your last catalog_search _meta block. If they differ, re-fetch the catalog first — do not act on a stale productId. On SKU_NOT_FOUND, the response includes a current catalog inline; pick a new product from it rather than retrying the same productId. Endpoint: https://mcp.comos-gateway.com/mcp
- cart_remove_item - Remove a product from the shopping cart. REQUIRED: cartId must be provided on every call for cart persistence. Use customer email for authenticated users or a consistent ID like "guest-abc123" for guests. Also requires tenant_id. Endpoint: https://mcp.comos-gateway.com/mcp
- cart_clear - Remove all items from the shopping cart. REQUIRED: cartId must be provided on every call for cart persistence. Use customer email for authenticated users or a consistent ID like "guest-abc123" for guests. Also requires tenant_id. Endpoint: https://mcp.comos-gateway.com/mcp
- orders_list - List customer orders with optional status filter (Federated: requires tenant_id. For cart/orders, pass auth_token from POST /v1/auth/login. Product IDs are MongoDB ObjectIds from catalog_search.) Endpoint: https://mcp.comos-gateway.com/mcp
- orders_get - Get detailed information about a specific order (Federated: requires tenant_id. For cart/orders, pass auth_token from POST /v1/auth/login. Product IDs are MongoDB ObjectIds from catalog_search.) Endpoint: https://mcp.comos-gateway.com/mcp
- orders_track - Get tracking information and shipment status for an order (Federated: requires tenant_id. For cart/orders, pass auth_token from POST /v1/auth/login. Product IDs are MongoDB ObjectIds from catalog_search.) Endpoint: https://mcp.comos-gateway.com/mcp
- orders_recent - Get the most recent orders for a customer (shortcut for orders_list with default settings) (Federated: requires tenant_id. For cart/orders, pass auth_token from POST /v1/auth/login. Product IDs are MongoDB ObjectIds from catalog_search.) Endpoint: https://mcp.comos-gateway.com/mcp
- inventory_check - Check stock availability for a product. Returns current stock level and availability status. (Federated: requires tenant_id. For cart/orders, pass auth_token from POST /v1/auth/login. Product IDs are MongoDB ObjectIds from catalog_search.) Endpoint: https://mcp.comos-gateway.com/mcp
- inventory_check_multiple - Check stock availability for multiple products at once (Federated: requires tenant_id. For cart/orders, pass auth_token from POST /v1/auth/login. Product IDs are MongoDB ObjectIds from catalog_search.) Endpoint: https://mcp.comos-gateway.com/mcp
- inventory_is_available - Quick check if a product is available (in stock with at least the requested quantity) (Federated: requires tenant_id. For cart/orders, pass auth_token from POST /v1/auth/login. Product IDs are MongoDB ObjectIds from catalog_search.) Endpoint: https://mcp.comos-gateway.com/mcp
- checkout_start - Start a new checkout process from the user's cart.

**DIGITAL vs PHYSICAL PRODUCTS:**
- **Digital products** (e-books, software, downloads): NO shipping address needed
- **Physical/material products**: Shipping address REQUIRED
- **Mixed orders** (some digital, some physical): Shipping address REQUIRED

The system automatically determines shipping requirements based on the `productType` field in cart items.

**Required Information:**
1. **Email** - Required for order confirmation and digital delivery
2. **Customer Name** - For order records
3. **Shipping Address** - ONLY required if cart contains physical/material products

**Checkout Flow (REAL Payments):**
1. Collect email and name from user
2. If cart has physical products, collect shipping address
3. Call this tool WITHOUT paymentMethodId (creates a pending checkout, returns a sagaId)
4. For physical products: optionally call `checkout_shipping_options` → `checkout_select_shipping`
5. Call `checkout_create_payment_session` with the sagaId → returns a **Stripe payment URL**
6. **Present the Stripe URL to the user** - they click it to enter card details on Stripe's secure page
7. After payment, call `checkout_status` to confirm order completion

**Example Stripe URL:** `https://checkout.stripe.com/c/pay/cs_live_...`

**Testing Only:**
- Pass paymentMethodId: "pm_test_visa" to skip real payment and process immediately

**Guest Checkout:**
- Just provide email - system creates a guest customer automatically

The checkout runs asynchronously. Use `checkout_status` with the sagaId to track progress. (Federated: requires tenant_id. For cart/orders, pass auth_token from POST /v1/auth/login. Product IDs are MongoDB ObjectIds from catalog_search.) Endpoint: https://mcp.comos-gateway.com/mcp
- checkout_status - Get the current status of a checkout saga, including completed steps, errors, and order details.

**When to use:**
- After `checkout_start` to track async saga progress
- After customer completes Stripe payment to verify order completion
- To debug failed checkouts and determine if retry is appropriate

**Saga Status Values:**
| Status | Meaning |
|--------|---------|
| `pending` | Checkout created, cart validated, awaiting processing |
| `in_progress` | Saga actively executing (inventory reservation, order creation, etc.) |
| `payment_pending` | Pre-payment steps complete, awaiting Stripe payment |
| `completed` | Payment successful, order confirmed. Terminal success state |
| `failed` | A step failed. Check `error` field for details |
| `compensated` | Rollback complete (inventory released, refunds issued). Terminal failure state |

**Saga Steps (execution order):**
1. `validate_cart` - Verify cart exists and has items
2. `reserve_inventory` - Place hold on product stock
3. `create_order` - Create order record
4. `process_payment` - Charge payment (or await Stripe session)
5. `confirm_order` - Finalize order, trigger fulfillment
6. `send_confirmation` - Email customer
7. `clear_cart` - Remove purchased items

**Response includes:** completedSteps, currentStep (if in_progress), error details (if failed), compensation info (if rolled back), and order/payment IDs (if created). (Federated: requires tenant_id. For cart/orders, pass auth_token from POST /v1/auth/login. Product IDs are MongoDB ObjectIds from catalog_search.) Endpoint: https://mcp.comos-gateway.com/mcp
- checkout_list - List checkout history for a user with optional status filtering.

**When to use:**
- Show order history to customer
- Find abandoned checkouts (`payment_pending`) for recovery
- Identify failed checkouts that may need retry
- Debug checkout issues for a specific user

**Status Filter Values:**
| Status | Use Case |
|--------|----------|
| `pending` | Recently started, not yet processing |
| `in_progress` | Currently processing (transient state) |
| `payment_pending` | Abandoned carts awaiting payment |
| `completed` | Successful orders |
| `failed` | Failed checkouts (may be retryable) |
| `compensating` | Currently rolling back (transient) |
| `compensated` | Fully rolled back after failure |

**Common Queries:**
- Abandoned carts: filter by `payment_pending`
- Order history: filter by `completed`
- Retryable failures: filter by `failed`, then check each saga's error.retryable field (Federated: requires tenant_id. For cart/orders, pass auth_token from POST /v1/auth/login. Product IDs are MongoDB ObjectIds from catalog_search.) Endpoint: https://mcp.comos-gateway.com/mcp
- checkout_shipping_options - Get available shipping methods and rates for a checkout.

**When to use:** After `checkout_start`, before `checkout_create_payment_session`, to let the customer choose shipping speed/carrier.

**Prerequisites:**
- Checkout must exist (valid sagaId from `checkout_start`)
- Shipping address must be set (provided during `checkout_start`)

**Returns:** List of shipping options with carrier, service, price, and estimated delivery days.

**Important Notes:**
- Rates are calculated based on shipping address, cart weight, and dimensions
- If no options returned, tenant may lack shipping configuration or address is unserviceable
- **This step is OPTIONAL.** If skipped, a default shipping method is automatically applied
- Can be called multiple times (e.g., if address changes)

**After getting options:** Use `checkout_select_shipping` with the desired carrierId and serviceId. (Federated: requires tenant_id. For cart/orders, pass auth_token from POST /v1/auth/login. Product IDs are MongoDB ObjectIds from catalog_search.) Endpoint: https://mcp.comos-gateway.com/mcp
- checkout_select_shipping - Select a shipping method for a checkout.

**When to use:** After `checkout_shipping_options`, when customer has chosen their preferred shipping method.

**Prerequisites:**
- Must call `checkout_shipping_options` first to get valid carrierId/serviceId combinations
- Checkout must be in `pending` or `payment_pending` status

**Behavior:**
- Updates the checkout's shipping method and recalculates total
- Can be called multiple times to change selection (before payment)
- Invalid carrierId/serviceId combinations will error

**Returns:** Selected shipping details and updated order total.

**This step is OPTIONAL.** If skipped entirely (no `checkout_shipping_options` or `checkout_select_shipping`), a default shipping method is applied automatically. (Federated: requires tenant_id. For cart/orders, pass auth_token from POST /v1/auth/login. Product IDs are MongoDB ObjectIds from catalog_search.) Endpoint: https://mcp.comos-gateway.com/mcp
- checkout_create_payment_session - Create a secure Stripe Checkout Session for payment collection. Returns a payment URL where the customer enters card details.

**IMPORTANT: Use this for REAL payments instead of checkout_start with paymentMethodId.**

**Recommended Flow:**
1. Collect shipping address from user via conversation
2. Start checkout with `checkout_start` (without paymentMethodId) → creates pending checkout
3. Optionally: `checkout_shipping_options` → `checkout_select_shipping` for shipping choice
4. Call this tool → returns Stripe payment URL
5. Present URL to user (redirect, link, or embed)
6. After payment, verify with `checkout_status`

**Why this flow?**
- Customer enters card on Stripe's PCI-compliant hosted page
- Card numbers never touch your servers
- Supports all Stripe methods (cards, Apple Pay, Google Pay, etc.)
- Handles 3D Secure authentication automatically

**Webhook Behavior:**
- Order completes automatically when Stripe confirms payment via webhook
- If webhook is delayed: poll `checkout_status` to verify (Stripe eventually delivers)
- If webhook fails: saga remains `payment_pending`; manual intervention may be needed

**Session Notes:**
- URL is single-use; once customer starts, it cannot be reused
- Sessions expire after ~24 hours; create new session if expired
- Returns `payment_pending` status after successful creation (Federated: requires tenant_id. For cart/orders, pass auth_token from POST /v1/auth/login. Product IDs are MongoDB ObjectIds from catalog_search.) Endpoint: https://mcp.comos-gateway.com/mcp
- checkout_retry - Retry a failed or compensated checkout by restarting the saga from the beginning.

**When to use:** When a checkout failed due to a transient issue that has been resolved (service timeout, temporary stock shortage).

**Prerequisites:**
- Saga must be in `failed` or `compensated` status
- Original cart must still exist with items
- Check `checkout_status` first to verify error is `retryable: true`

**Behavior:**
1. Validates saga exists and is in retriable state
2. Re-validates cart still has items
3. Resets saga to `pending` status
4. Clears previous error and compensation records
5. Restarts saga execution from step 1

**CAN retry (transient failures):**
- `INVENTORY_SERVICE_ERROR` - Service was temporarily unavailable
- `PAYMENT_SERVICE_ERROR` - Stripe API had temporary issues
- `ORDER_SERVICE_ERROR` - Order service timeout
- `SAGA_TIMEOUT` - Processing exceeded time limit

**CANNOT retry (permanent failures):**
- `PAYMENT_DECLINED` - Customer needs different payment method
- `INVALID_ADDRESS` - Customer must correct address
- `CART_EMPTY` / `CART_NOT_FOUND` - Cart was cleared or deleted
- `INVENTORY_UNAVAILABLE` - Items still out of stock (check first)

**Cannot retry these statuses:**
- `completed` - Already succeeded (start new checkout instead)
- `in_progress` / `payment_pending` - Still active (Federated: requires tenant_id. For cart/orders, pass auth_token from POST /v1/auth/login. Product IDs are MongoDB ObjectIds from catalog_search.) Endpoint: https://mcp.comos-gateway.com/mcp
- api_call - Call any comAI API endpoint not covered by specific tools.
Use this for: payments, shipping rates, recommendations, returns, user profiles, policies, help articles, and more.
Read the 'api_documentation' resource first to see available endpoints and their parameters.

IMPORTANT: For multi-tenant operations (checkout, cart, orders), you MUST specify the tenant_id parameter.
The tenant_id should match the tenant where the cart/customer data exists (e.g., 'vnm-sport', not 'test-test').

Common endpoints:
- GET /v1/users/{userId} - Get user profile
- GET /v1/recommendations/{userId} - Get personalized recommendations
- GET /v1/shipping/rates - Calculate shipping rates
- POST /v1/checkout - Process checkout (requires tenant_id)
- GET /v1/returns/{returnId} - Check return status
- POST /v1/returns - Request a return
- GET /v1/help - Search help articles
- GET /v1/policies - List store policies
- GET /v1/api-keys - List user's API keys (requires auth)
- POST /v1/api-keys - Create new API key (requires auth) (Federated: requires tenant_id. For cart/orders, pass auth_token from POST /v1/auth/login. Product IDs are MongoDB ObjectIds from catalog_search.) Endpoint: https://mcp.comos-gateway.com/mcp

## Resources
Not captured

## Prompts
Not captured

## Metadata
- Owner: io.github.ronrey
- Version: 1.0.0
- Runtime: Sse
- Transports: HTTP
- License: Not captured
- Language: Not captured
- Stars: Not captured
- Updated: Feb 11, 2026
- Source: https://registry.modelcontextprotocol.io