# MCP Server (onX)
{% hint style="info" %}
The fulfillmenttools MCP Server is being rolled out gradually throughout May and June 2026 and may not be available to all customers immediately.
{% endhint %}
This fulfillmenttools MCP Server provides a standardized interface for interacting with fulfillmenttools. Built on the [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) and implementing the Order Network eXchange (onX) Protocol, it enables system-to-system communication that allows AI Agents, orchestration layers, and external platforms to manage orders using natural language without relying on proprietary APIs.
Designed for agentic commerce applications, this fulfillmenttools MCP Server exposes a set of tools that AI agents can invoke to query inventory, products, and variants — either on user instruction or as part of automated workflows. This initial release focuses on read-only operations to deliver value early without exposing security-sensitive data. Additional tools for order management may follow in future releases.
**Example interactions:**
* What's the current stock level for SKU-12345?
* Show me all products in the electronics category
* List available variants for product PRD-001
* Check inventory availability across all facilities
The fulfillmenttools MCP Server acts as a protocol adapter. It doesn't implement business logic, doesn't infer missing data, and transparently passes requests and responses between the AI Agent and the fulfillmenttools backend.
## Using the fulfillmenttools MCP Server with an agent
The fulfillmenttools MCP Server allows any compatible agent (for example, [Claude Desktop/Claude Code](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)) to securely access and interact with onX functionality in a standardized way.
To use this feature, you first need to make the fulfillmenttools MCP Server known to the agent you plan to work with.
The following example describes the general setup using the fulfillmenttools MCP server, as demonstrated with a Claude agent. The same steps apply to other agents that support MCP integration.
{% stepper %}
{% step %}
**Agent connection**
Start by configuring your agent to recognize the fulfillmenttools MCP Server endpoint.
This typically involves adding the fulfillmenttools MCP server URL and name (for example, `yourtenant.mcp.api.fulfillmenttools.com/onx`, replace `yourtenant` with your fulfillmenttools tenant) to the agent's MCP or tools configuration.
Once configured, the fulfillmenttools MCP Server is available, and your agent is aware that it can call onX capabilities via the fulfillmenttools MCP Server. You need to connect to it to complete this step.
{% endstep %}
{% step %}
**Authorization**
You'll either need to configure a token for your agent or log in on your first interaction with the service by providing your credentials in a fulfillmenttools login form. See the [Authentication section below](#authentication) for more information.
Successful authorization ensures the agent can securely make requests to the fulfillmenttools MCP Server on your behalf.
{% endstep %}
{% step %}
**Interaction**
After configuration and authorization are complete, the agent can start interacting with onX through the fulfillmenttools MCP Server. When you ask the agent to perform an onX-related task, the agent uses the fulfillmenttools MCP Server in the background of the conversation to retrieve data or trigger actions, returning the results directly in its response.
{% endstep %}
{% endstepper %}
## Intended usage and primary user audience
### Target audience
| Audience | Use case |
| -------------------------- | --------------------------------------------------------------- |
| Inventory managers | Query stock levels and availability across facilities |
| Merchandising teams | Access product catalog and variant information |
| eCommerce platforms | Integrate inventory and product data into automated workflows |
| Developers and integrators | Build agentic commerce applications using fulfillmenttools data |
### Primary use cases
* **Inventory queries**: Check stock levels and availability across facilities
* **Product catalog access**: Retrieve product information and metadata
* **Variant lookup**: Query product variants and their attributes
* **Agentic workflows**: Enable AI agents to access fulfillment data for automated decision-making
### Future target audiences
The following audiences will be supported as additional tools are implemented in the future:
| Audience | Use case | Planned tools |
| ------------------------- | ------------------------------------------------ | ------------------------------------- |
| Customer service teams | Handle order inquiries and process cancellations | Order queries, cancel order |
| Operations managers | Monitor order status and fulfillment progress | Order queries, fulfillment operations |
| eCommerce administrators | Create and manage orders through AI workflows | Create order, update order |
| Returns and support teams | Process customer returns and refunds | Return processing |
## User interaction model
### Authentication
{% hint style="info" %}
**SSO login availability**\
Login via [configured OIDC providers](https://docs.fulfillmenttools.com/documentation/integrations/openid-connect) is not available from the initial release of this feature. Support for SSO‑based login is planned as an upcoming improvement.
{% endhint %}
All requests to the fulfillmenttools MCP Server require proper authentication. Because the agent is not an independent actor in this MCP Service, the [OAuth 2.1](https://oauth.net/2.1/) Authorization Code Flow with PKCE is enforced, and any implicit and ROPC flows are disallowed. The agent is intended to work in the name of a user, not on its own.
1. **Agent-provided authentication**: The AI agent includes an authorization header with each request. This is typical for pre-configured integrations where the agent has been provisioned with valid credentials or tokens.
2. **Interactive login**: If no authorization header is present, you're redirected to a login page to enter your fulfillmenttools credentials. Upon successful authentication, a token is generated, and the agent uses this token for all subsequent requests within the session.
In both cases, authentication is handled transparently at the fulfillmenttools level.
{% hint style="danger" %}
Users must never include credentials in their natural language queries. Authentication is configured during system setup or session negotiation and is managed transparently.
{% endhint %}
### Permissions
Access to this service requires the user to have the following permissions:
| Permission | Right | Value in API |
| -------------------- | ----- | --------------------------- |
| Stock availabilities | Read | `STOCK_AVAILABILITIES_READ` |
| Listing | Read | `LISTING_READ` |
More information can be found in the [Users, roles, and permissions article](/documentation/getting-started/authentication-and-authorization/user-management.md#users-roles-and-permissions).
### Allowed and expected data
The fulfillmenttools MCP Server accepts structured data through its standardized tools:
#### **Query tools (read operations)**
| Operation | Expected input | Returns |
| ---------------------- | ------------------------------ | ----------------------------- |
| `get-inventory` | Facility ID or filter criteria | Stock levels and availability |
| `get-products` | Product ID or filter criteria | Product catalog records |
| `get-product-variants` | Product ID or variant filters | Product variant details |
All inputs must conform to the [onX protocol schema](https://github.com/commerce-operations-foundation/mcp-reference-server/tree/develop/schemas). fulfillmenttools validates requests against this schema before forwarding them to the backend.
### Discouraged or prohibited data inputs
The following data types shouldn't be included in natural language queries or tool parameters:
| Category | Examples | Reason |
| ----------------------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------- |
| **Sensitive payment data** | Full credit card numbers, CVV codes, bank account details | Security risk: Use dedicated payment processors |
| **Personal identification documents** | Passport numbers, social security numbers, driver's license copies | Data protection compliance |
| **Authentication credentials in queries** | Passwords, API keys, access tokens typed into prompts | Credentials should never be part of conversation content |
| **Unstructured bulk data** | Large file uploads, binary attachments | The fulfillmenttools MCP Server isn't designed for file transfer |
| **Test data in production** | Fake orders, test customers in a live environment | Data integrity concerns |
#### **System behavior**
**The fulfillmenttools MCP Server:**
* Won't infer or auto-fill missing required fields
* Won't generate placeholder data for incomplete requests
* Won't attempt to correct malformed data
* Won't bypass backend validation rules
If required information is missing, the backend error returns a transparent error, and the AI Agent will request the missing details from the user.
### Data flow
**Data flow steps:**
1. **User request**: User issues a natural language request to the AI Agent
2. **AI interpretation**: The AI parses the intent and invokes the appropriate MCP tool with structured parameters
3. **Protocol translation**: The fulfillmenttools MCP Server validates the request to the onX specifications and translates it to the fulfillmenttools API format
4. **Backend execution**: fulfillmenttools processes the request against the production data
5. **Response return**: Results flow back through the fulfillmenttools MCP Server to the AI Agent
6. **Human-readable output**: The AI presents the information in natural language to the user
### Data processing locations and third parties
The fulfillmenttools MCP Server is deployed and operated exclusively by fulfillmenttools. It runs in the same geographical region as the customer's fulfillmenttools tenant to ensure data residency compliance and optimal performance.
**Processing locations:**
| Component | Location | Data handled |
| ---------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------- |
| **AI Agent** | Customer/Partner infrastructure (varies by provider) | Natural language conversation, tool invocations |
| **MCP Server** | fulfillmenttools infrastructure, same region as customer tenant | Protocol handling, request validation, translation |
| **fulfillmenttools backend** | fulfillmenttools cloud infrastructure in the region of the customers' tenant | Inventory data, product catalog, fulfillment operations |
**Third-party involvement:**
The fulfillmenttools MCP Server doesn't route data to additional third-party services beyond those listed below.
| Third party | Role | Data exposure |
| ------------------------------------------------ | -------------------------------------------------- | ------------------------------------------------------- |
| **AI provider** (for example, Anthropic, OpenAI) | Processes natural language to determine tool calls | Sees conversation content, including any data discussed |
| **fulfillmenttools** | Operates the MCP Server and backend systems | Full access to operational data |
**Privacy consideration:** The AI provider processes conversation content to understand and respond to requests. Users should be mindful of what information they include in their prompts.
{% hint style="info" %}
In connection with this feature, fulfillmenttools acts neither as a provider nor as an operator of an AI system within the meaning of the EU AI Act. Accordingly, the obligations arising from the AI Act don't apply to fulfillmenttools.
{% endhint %}
## Output characteristics and limitations
### Output description
**Response characteristics:**
* **Structured format**: All responses follow consistent JSON schemas defined by the onX Protocol specification
* **Transparent errors**: Backend errors are returned exactly as received, without modification or interpretation
* **Data currency**: Query results reflect the current state in fulfillmenttools at the time of the request
**Response types:**
| Operation type | Success response | Error response |
| -------------- | ------------------------------------- | ----------------------------------- |
| **Queries** | Requested data in a structured format | Error code and message from backend |
### Known limitations
| Limitation | Description | Workaround |
| -------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
| **Read-only operations** | Only query tools (inventory, products, variants) are currently available | Use fulfillmenttools APIs and clients for order management and other write operations |
| **No real-time streaming** | Results are returned as complete responses, not streamed | Use polling for status updates on long-running operations |
| **No file attachments** | Can't upload or download files such as invoices or shipping labels | Access documents through the fulfillmenttools clients or via APIs |
| **No data inference** | fulfillmenttools won't guess or auto-fill missing information | Provide all required fields in requests |
fulfillmenttools reserves the right to impose usage quotas on this feature.
**Planned future capabilities:**
The following operations are defined in the onX specification and planned for future implementation:
* Order management (create, update, cancel, query orders)
* Fulfillment operations (mark orders as shipped)
* Return processing
* Customer profile queries
Attempting to use unimplemented operations will return a `FEATURE_NOT_AVAILABLE` response with guidance on alternatives.
## Human-in-the-loop
The fulfillmenttools MCP Server is designed with human oversight as a foundational principle. While AI Agents can interpret requests and execute operations, fulfillmenttools ensures users remain in control of all decisions and actions.
### Oversight mechanisms
* **Transparent communication**: All operations, including errors, are communicated clearly to the user
* **No autonomous actions**: fulfillmenttools doesn't perform high-impact operations without explicit user direction
### When human input is required
fulfillmenttools requests clarification rather than making assumptions when:
* Required information is missing from the request
* Multiple valid interpretations of user intent exist
* The requested action would have significant business impact
* Backend validation rules reject the request
### User responsibility
Users are the decision-makers in all interactions. The AI Agent accelerates work by:
* Translating natural language into precise commands
* Presenting information in accessible formats
* Maintaining context within conversations
* Suggesting relevant next steps based on results
However, users should:
* Review proposed actions before confirming execution
* Verify that AI-interpreted data matches their intent
* Report unexpected behavior to the fulfillmenttools Support team
* Maintain awareness of what data is being shared in conversations
The combination of AI assistance and human oversight ensures efficient operations while maintaining appropriate control over business-critical actions.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.fulfillmenttools.com/documentation/integrations/mcp-server-onx.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.