# Foundry IMS — MCP Server

Official remote [Model Context Protocol](https://modelcontextprotocol.io) server for
[Foundry IMS](https://foundryims.com), an inventory and product-information management
system for parts, gear, and multi-channel retailers.

It lets an AI assistant work directly on a Foundry catalog: search and edit products and
variants, manage brands and categories, curate images, and inspect or rebuild assemblies
(bills of materials) and bundles.

**Endpoint:** `https://mcp.foundryims.com/mcp` (Streamable HTTP)
**Registry name:** `com.foundryims/foundry-ims`

This repository holds the public documentation and the
[`server.json`](./server.json) manifest for the hosted service. The server itself is
hosted — there is nothing to install or run locally.

---

## Install

### Claude

Foundry IMS is published in Claude's connector directory — search for **Foundry IMS** in
**Settings → Connectors** and click Connect. Sign in with your Foundry account and the
connection is scoped to the organizations you belong to.

To add it manually as a custom connector, use the URL `https://mcp.foundryims.com/mcp`.

### ChatGPT

**Settings → Connectors → Create**, then add `https://mcp.foundryims.com/mcp` and
authenticate with a Foundry API key (see below).

### Cursor, VS Code, Zed, and other MCP clients

Point any client that supports remote MCP servers at:

```json
{
  "mcpServers": {
    "foundry-ims": {
      "url": "https://mcp.foundryims.com/mcp"
    }
  }
}
```

## Authentication

Two modes are supported:

| Mode | How | Multi-org |
|---|---|---|
| **OAuth** | Sign in with your Foundry account when the client prompts | Yes — use `list_orgs` / `set_org` to switch |
| **API key** | Send `Authorization: Bearer fims_…` | No — the key is bound to one organization |

Create an API key in the Foundry admin under **Settings → API Keys**. Every call is scoped
to that key's permissions; a `403` means the key lacks the required permission.

## Tools

36 tools over OAuth, or 34 with an API key (`list_orgs` and `set_org` are OAuth-only,
since a key is already bound to a single organization).

### Organizations *(OAuth only)*
| Tool | |
|---|---|
| `list_orgs` | List the organizations you belong to and which is active |
| `set_org` | Set the active organization for subsequent calls |

### Products
| Tool | |
|---|---|
| `search_products` | Search by name, SKU, UPC/GTIN/MPN, or channel/supplier SKU |
| `get_product` | Fetch one product with its variants |
| `create_product` | Create a SIMPLE, FAMILY, ASSEMBLY, or BUNDLE product |
| `update_product` | Update name, description, brand, category |
| `delete_product` | Soft-delete (trash) a product |
| `restore_product` | Restore a trashed product |

### Variants (sellable SKUs)
| Tool | |
|---|---|
| `search_variants` | Search variants across SKU, name, and barcodes |
| `get_variant` | Fetch one variant, including price and available quantity |
| `update_variant` | Update SKU, name, price, cost, and identifiers |

### Assemblies / bills of materials
| Tool | |
|---|---|
| `get_bom` | Get an assembly's active bill of materials |
| `bom_can_build` | How many units can be built from on-hand stock |
| `set_bom` | Replace an assembly's BOM with a new active version |
| `delete_bom` | Remove the recipe (the product itself is untouched) |
| `flatten_bom` | Inline a sub-assembly's components into its parent |
| `find_where_used` | Reverse lookup — every BOM and bundle using a component |
| `replace_bom_component` | Swap a component across every BOM that uses it |

### Bundles
| Tool | |
|---|---|
| `get_bundle_components` | List a bundle's component variants |
| `add_bundle_component` | Add a component with a quantity |
| `update_bundle_component` | Change a component's quantity |
| `remove_bundle_component` | Remove a component |

### Brands
| Tool | |
|---|---|
| `list_brands` | List brands |
| `create_brand` | Create a brand |
| `update_brand` | Rename, re-slug, or set rich descriptions and SEO metadata |
| `merge_brands` | Reassign every product from one brand to another |

### Categories
| Tool | |
|---|---|
| `list_categories` | List the category tree |
| `create_category` | Create a category |
| `update_category` | Rename, re-slug, reparent, or set descriptions and SEO metadata |
| `reorder_categories` | Set display order within a sibling group |

### Images
| Tool | |
|---|---|
| `add_variant_image` | Add an image by URL — Foundry fetches and re-hosts the bytes |
| `remove_variant_image` | Remove an image |
| `reorder_variant_images` | Set image order |

### Custom fields
| Tool | |
|---|---|
| `list_custom_fields` | List the org's custom field definitions |
| `get_custom_values` | Read custom field values on a product or variant |
| `set_custom_values` | Set custom field values (upsert) |

## Notes for agents

- IDs are UUIDs and are not guessable — call `search_products` or `search_variants` first,
  then act on the returned `id`.
- Search matches identifiers, not just names: pass a SKU, UPC, GTIN, MPN, or a
  channel/supplier SKU straight into `search`.
- Pricing and SKUs live on the **variant**, not the product. Use `update_variant`.
- To enumerate every product of a type, call `search_products` with `type` set and no
  `search` term, then page using `meta.total`.
- `delete_product` and `set_bom` are significant changes — confirm with the user first.

## Links

- [Foundry IMS](https://foundryims.com)
- [Connector documentation](https://foundryims.com/integrations/ai/claude/)
- [Storefront API docs](https://foundryims.com/docs/storefront-api)
- [Model Context Protocol](https://modelcontextprotocol.io)

## Support

Questions or problems: [support@foundryims.com](mailto:support@foundryims.com)

## License

Documentation in this repository is released under the [MIT License](./LICENSE). The
Foundry IMS service itself is proprietary.