Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@nexi-xpay-mcp-server List the orders placed today"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server for the Nexi XPay Back Office APIs. Enables AI assistants (Claude, Cursor, etc.) to query orders, transaction details, warnings/anomalies, and payment methods from your Nexi XPay merchant account.
Tool | Description |
| List orders with filters (date range, channel, status, transaction code) |
| Full details of a specific transaction |
| Retrieve warnings/anomalies (default: last 7 days) |
| List active payment methods for the merchant |
Related MCP server: PayBridgeNP MCP Server
Python >= 3.10
A Nexi XPay merchant account with Back Office API access
API credentials: Alias, API Key and Secret Key (from Nexi Back Office)
uvx nexi-xpay-mcp-serverAdd to your MCP configuration file (.mcp.json for Claude Code, claude_desktop_config.json for Claude Desktop):
{
"mcpServers": {
"nexi": {
"command": "uvx",
"args": ["nexi-xpay-mcp-server"],
"env": {
"NEXI_ALIAS": "your_alias",
"NEXI_SECRET_KEY": "your_secret_key"
}
}
}
}Use different keys to run one instance per merchant:
{
"mcpServers": {
"nexi-acme": {
"command": "uvx",
"args": ["nexi-xpay-mcp-server"],
"env": {
"NEXI_ALIAS": "acme_merchant",
"NEXI_SECRET_KEY": "acme_secret_key"
}
},
"nexi-globex": {
"command": "uvx",
"args": ["nexi-xpay-mcp-server"],
"env": {
"NEXI_ALIAS": "globex_merchant",
"NEXI_SECRET_KEY": "globex_secret_key"
}
}
}
}Variable | Required | Default | Description |
| Yes | — | Merchant alias (also used as API key) |
| Yes | — | Secret key for MAC calculation |
| No |
| Set to |
git clone https://github.com/stucchi/nexi-xpay-mcp-server.git
cd nexi-xpay-mcp-server
uv syncLocal run:
NEXI_ALIAS=your_alias NEXI_SECRET_KEY=your_secret uv run nexi-xpay-mcp-serverMIT
Retrieve the list of orders from Nexi XPay Back Office. Supports filters by period, channel, status, and transaction code.
| Name | Required | Description | Default |
|---|---|---|---|
| periodo | Yes | ||
| canale | No | All | |
| codiceTransazione | No | ||
| stato | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavior. It indicates a read operation ('Retrieve') but does not disclose pagination, rate limits, or error handling. The presence of an output schema reduces the need to describe return values.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the main action ('Retrieve the list of orders'), and includes key functionality without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 params, output schema exists), the description adequately covers purpose and parameters. It omits details like required parameter format or default values, but the output schema likely fills some gaps. Still, slight incompleteness keeps it from a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description maps all four parameters to filters (period, channel, status, transaction code), adding context that the schema lacks (e.g., 'codiceTransazione' is transaction code). This compensates for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Retrieve the list of orders' (specific verb+resource) and distinguishes from siblings like 'order_details' (which implies single order retrieval). The mention of filters further specifies the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Supports filters by...' which implies usage when filtering by those criteria. It does not provide explicit when-not or alternatives, but the context is clear enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve full details of a specific order from Nexi XPay Back Office by transaction code.
| Name | Required | Description | Default |
|---|---|---|---|
| codiceTransazione | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must handle behavioral disclosure. It implies a read operation but doesn't specify error handling or data scope, which is adequate but not enriched.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no wasted words, front-loaded with core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists, the description doesn't need to explain returns, but lacks context on error cases or workflow with siblings like list_orders.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description only mentions the parameter indirectly ('by transaction code'), adding minimal semantic detail beyond the name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves full details of a specific order using a transaction code, distinguishing it from sibling tools like list_orders (listing) and payment_methods.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use vs alternatives; no mention of prerequisites like obtaining a transaction code via list_orders first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve active payment methods for a merchant from Nexi XPay Back Office.
| Name | Required | Description | Default |
|---|---|---|---|
| platform | No | custom | |
| platformVers | No | 0 | |
| pluginVers | No | 0 |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Only states it retrieves active payment methods, but does not disclose behavioral traits like authentication requirements, rate limits, or data freshness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, concise, but under-specified. No wasted words, but lacks necessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Has output schema but description does not hint at return values. With 0% schema coverage, fails to fill parameter gaps. Incomplete for a 3-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the three parameters (platform, platformVers, pluginVers). No added meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action (retrieve), resource (active payment methods), and context (for a merchant from Nexi XPay Back Office). Distinguishes from siblings which are about orders and warnings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives or any prerequisites. The description is a single statement without context for appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve warnings/anomalies from Nexi XPay Back Office. Can filter by transaction code or date range.
| Name | Required | Description | Default |
|---|---|---|---|
| codiceTransazione | No | ||
| dataTransazioneDal | No | ||
| dataTransazioneAl | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It only states that the tool retrieves warnings, with no disclosure about side effects, authentication needs, or rate limits. The behavior is implied to be read-only but not explicitly confirmed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at two sentences (15 words) while still conveying the core purpose and filter capabilities. Every word serves a purpose, with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with three optional parameters and an output schema (presumably listing warnings), the description covers the basic goal. However, it lacks details about the output format, error handling, or any limitations, leaving gaps for an agent unfamiliar with the Nexi system.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description adds meaning by linking 'codiceTransazione' to 'transaction code' and the two date params to 'date range'. This compensates partially, but the exact format or constraints are not given, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Retrieve') and the resource ('warnings/anomalies from Nexi XPay Back Office'). It distinguishes itself from sibling tools (list_orders, order_details, payment_methods) by focusing on a different entity (warnings).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions filtering options ('by transaction code or date range'), giving some context on when to use. However, it does not provide explicit when-not-to-use advice or compare with alternatives, leaving the agent to infer based on the resource name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.2.1list_ordersorder_detailspayment_methodswarningsScored across 4 tools
Each tool targets a distinct resource or aspect: orders list, order details, payment methods, and warnings. There is no overlap in purpose, making it easy for an agent to select the correct tool.
All tool names use snake_case, which is consistent. However, the pattern is not uniform: 'list_orders' follows verb_noun, while 'order_details', 'payment_methods', and 'warnings' are noun_noun or noun-only. This minor inconsistency prevents a perfect score.
With 4 tools, the server is scoped to a focused set of read operations. While slightly low, it covers the essential queries for the Nexi XPay Back Office without unnecessary bloat, making it appropriate for its purpose.
The tools cover the main read operations: listing orders, getting details, viewing payment methods, and checking warnings. Missing operations like creating or updating orders are not expected if the server is read-only, so the surface is largely complete for its intended use.
Enable AI assistants to interact seamlessly with Feeef e-commerce stores, products, and orders usi…
Connect e-commerce and marketing data to AI assistants via MCP.
Manage your NanoCart store from any AI agent: products, orders, coupons, subscribers, reports.
AI access to your Qualy payments back office: contacts, payment requests, and search.
