Click on "Install 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., "@novapay-mcp Create a payment link for 1000 UAH, hold the funds"
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 stdio server for NovaPay on top of the official novapay SDK. Connect it to any MCP-compatible agent (Claude Desktop, Claude Code, custom agents) β and the agent can create payment links, poll payment status, drive the session lifecycle and generate merchant keys.
π ΠΠΎΠΊΡΠΌΠ΅Π½ΡΠ°ΡΡΡ ΡΠΊΡΠ°ΡΠ½ΡΡΠΊΠΎΡ
Contents Β· Requirements Β· Setup Β· Onboarding from scratch Β· Tools Β· Development Β· License
Node.js 20.3+
Related MCP server: merchant-mcp
Add to your MCP client config:
{
"mcpServers": {
"novapay": {
"command": "npx",
"args": ["-y", "novapay-mcp"],
"env": {
"MERCHANT_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\nMIIEvQ...\n-----END PRIVATE KEY-----",
"MERCHANT_ID": "<your merchant id>",
"NOVAPAY_ENVIRONMENT": "stage"
}
}
}
}The PEM can be pasted either with \n escapes (as in the example) or as a multi-line value β the server understands both.
Variable | Required | Description |
| yes | Merchant's private RSA key (PEM). Signs every request to NovaPay |
| yes | Merchant identifier in NovaPay |
| yes |
|
| no | NovaPay public key (PEM). Unused in stdio mode β the server does not receive postbacks |
The server starts without configuration too: generate_keys stays available, and the payment tools return an error listing the missing variables.
No keys yet? Generate them straight from the agent:
Connect the server without env (or with a partial env) and ask the agent to call generate_keys.
Register the public key from the response with NovaPay (Acquiring3 admin panel or via support).
Paste the contents of the private key file (the path is in the response, the file lives in ~/.novapay/ with 0600 permissions) into MERCHANT_PRIVATE_KEY, add MERCHANT_ID and NOVAPAY_ENVIRONMENT.
Restart the MCP server β the payment tools go live.
The private key is never returned in a tool response β only the file path, so the key never lands in the agent's context or logs.
Onboarding
generate_keys β generate a 2048-bit RSA pair for the merchant. Works without configuration.
Creating payments (a session can hold several payments)
create_acquiring_session β create an Internet Acquiring session β session id.
add_acquiring_payment β add a payment to the session β payment URL for the customer.
create_checkout_session β create a Checkout session (payment + Nova Poshta delivery) β session id.
add_checkout_payment β add a payment to a checkout session β payment URL.
Both add_*_payment require an explicit use_hold: true β hold the funds for a later capture via complete_hold, false β charge immediately. If the user did not say which, the agent should ask.
Session lifecycle (shared by acquiring and checkout)
get_session_status β session status, amounts, list of operations. The only way to see the result of the operations below.
complete_hold β capture the held funds (possibly partially).
void_session β cancel a paid/held session. On a paid session this refunds real money.
expire_session β invalidate an unpaid session (cancel the payment link).
create_*_session βββΆ add_*_payment βββΆ url
β
customer pays
ββ use_hold: true βββΆ holded ββcomplete_holdβββΆ paid
ββ use_hold: false βββββββββββββββββββββββββββΆ paid
β
unpaid ββexpire_sessionβββΆ expired void_session ββββββββ
βΌ
voidednpm install
npm test # tsc --noEmit + node:test
npm run build # tsc β dist/A smoke test against the NovaPay stage environment is possible with the published QE keys (merchant 2) from the Authentication page.
CI runs the same checks on Node 20, 22 and 24 for every push and pull request; pushing a v* tag publishes the package to npm.
Add a payment to an existing acquiring session. Returns the payment URL to send to the customer, plus the session and transaction ids. Call again with the same session_id to add more payments.
| Name | Required | Description | Default |
|---|---|---|---|
| amount | Yes | Payment amount in UAH, e.g. 250.5 | |
| delivery | No | Delivery details object (Nova Poshta fields) | |
| products | No | Order lines shown to the payer | |
| use_hold | Yes | true β hold (block) the funds for a later capture via complete_hold; false β charge immediately. This is a required business decision: if the user has not said whether to hold or charge right away, ASK THEM before calling this tool. | |
| identifier | No | Recipient identifier (split payments) | |
| session_id | Yes | Session id returned by the create_*_session tool | |
| external_id | No | Merchant-side payment id, echoed in status/postbacks |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden for behavioral disclosure. It reveals that the tool creates a payment and returns the payment URL and ids, and that repeated calls with the same session are allowed. However, it does not explain prerequisites, failure modes, hold/charge side effects, or what happens if the session is invalid or expiredβgaps that matter for a payment mutation.
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 three short, information-dense sentences. The first sentence states the core action, the second lists the key return values, and the third explains repeatability. Every sentence earns its place with zero filler.
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?
The tool has 7 parameters and nested objects, but the schema covers all parameter semantics. The description provides return values (payment URL, session/transaction ids) and the repeat-call behavior, which is adequate given the lack of an output schema. It could be more complete by noting that the session must be active or by cross-referencing create_acquiring_session, but it is reasonably complete for an existing-session payment addition.
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 100%, so every parameter is already documented in the input schema. The description adds little beyond referencing session_id, which is also in the schema. This meets the baseline but does not elevate it since the tool description itself provides no additional parameter-level meaning.
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 a specific verb ('Add a payment') and resource ('existing acquiring session'), immediately distinguishing it from add_checkout_payment. It also notes the key output (payment URL, session and transaction ids), making the tool's purpose unmistakable.
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 gives practical usage context: it must be called on an existing acquiring session and can be called again with the same session_id to add more payments. It does not explicitly contrast with add_checkout_payment or other siblings, but the 'acquiring session' framing and the mention of 'existing session' imply the proper workflow after create_acquiring_session.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a payment to an existing checkout session. Returns the checkout URL to send to the customer plus the session id (the transaction id appears later in get_session_status).
| Name | Required | Description | Default |
|---|---|---|---|
| amount | Yes | Payment amount in UAH, e.g. 250.5 | |
| delivery | No | Delivery details object (Nova Poshta fields) | |
| products | No | Order lines shown to the payer | |
| use_hold | Yes | true β hold (block) the funds for a later capture via complete_hold; false β charge immediately. This is a required business decision: if the user has not said whether to hold or charge right away, ASK THEM before calling this tool. | |
| identifier | No | Recipient identifier (split payments) | |
| session_id | Yes | Session id returned by the create_*_session tool | |
| external_id | No | Merchant-side payment id, echoed in status/postbacks |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing side effects and returns. It does state return values (checkout URL + session id) and the timing of the transaction id. However, it omits important behavioral details such as fund holding vs. immediate charge (though the use_hold parameter schema covers this), permission requirements, or any side effects beyond adding a payment. This is adequate but not rich.
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 two sentences, front-loaded with the core function, and every clause adds information. No fluff or redundant wording.
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?
Despite having 7 parameters, nested objects, and no output schema, the description plus schema cover the essential context: what the tool does, prerequisites (existing session), and return values. It could mention the need to ask about hold vs. charge, but that is already in the use_hold schema description. Overall, adequate for the complexity.
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 100%, so the baseline is 3. The description itself adds no parameter-specific meaning; it relies entirely on the schema, which already documents each parameter well, including the critical use_hold business decision.
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's function: 'Add a payment to an existing checkout session' with a specific verb and resource. It also differentiates it from creating a session (create_checkout_session) and status retrieval (get_session_status) by noting the return of the checkout URL and session id, and pointing to later transaction id availability.
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 implies usage context: it requires an existing checkout session (as opposed to creating one) and coordinates with get_session_status for the transaction id. However, it does not explicitly name alternative tools like add_acquiring_payment or state when not to use this tool, so guidance is clear but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Capture funds previously held with use_hold=true, moving the session from holded to paid. Optionally capture a smaller amount than was held. NovaPay returns no body for this call β check the result with get_session_status.
| Name | Required | Description | Default |
|---|---|---|---|
| amount | No | Partial capture amount; omit to capture the full hold | |
| session_id | Yes | Session id (acquiring or checkout) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses a key behavioral trait: 'NovaPay returns no body for this call,' and explains the state transition (holded to paid) and partial capture option. It does not cover failure modes or authorization requirements, but the disclosed behaviors are important and non-obvious.
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?
Two sentences, front-loaded with the primary action, and no filler. The first sentence defines the core purpose; the second adds the crucial note about no response body and how to verify. Every phrase earns its place.
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 state-changing payment tool with no output schema, the description covers the essential aspects: what it does, a prerequisite, an option, and a verification step via get_session_status. It stops short of covering error handling or side effects beyond the state transition, but it is reasonably complete for an agent to operate correctly.
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 100%, with both parameters clearly described. The description adds a slight clarification of the amount parameter ('Optionally capture a smaller amount than was held') but mostly repeats schema information. The baseline of 3 is appropriate because the schema already does the heavy lifting.
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's action: 'Capture funds previously held with use_hold=true, moving the session from holded to paid.' It uses a specific verb (capture), resource (funds held), and context (use_hold=true), which distinguishes it from sibling tools like void_session and expire_session.
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 implies when to use the tool: after a hold created with use_hold=true. It also mentions the optional partial capture. However, it does not explicitly contrast with alternatives (e.g., void_session) or state exclusions, but the prerequisite and follow-up guidance ('check with get_session_status') provide clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a NovaPay Internet Acquiring payment session. Returns the session id. To get a payment URL for the customer, follow up with add_acquiring_payment. A session can hold multiple payments.
| Name | Required | Description | Default |
|---|---|---|---|
| fail_url | No | Where the payer is redirected after failure | |
| metadata | No | Arbitrary merchant metadata, echoed in status | |
| success_url | No | Where the payer is redirected after success | |
| callback_url | No | Merchant URL for payment postbacks | |
| client_email | No | ||
| client_phone | Yes | Payer phone in international format, e.g. +380501112233 | |
| client_last_name | No | ||
| client_first_name | No | ||
| client_patronymic | No | ||
| success_redirect_timeout | No | Seconds before auto-redirect |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the return value, the need for a follow-up call, and that a session can hold multiple payments. While it omits authorization needs, idempotency, and failure behavior, the disclosed workflow context adds meaningful behavioral insight beyond the schema.
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?
Three sentences each earn their place: what it does, what it returns, and what to do next. There is no redundant phrasing and the key information is front-loaded.
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?
The description covers the core workflow (create session, follow up with payment) and the multi-payment nature. However, with no output schema and 10 parameters, it misses important details such as the required client_phone format, behavior of success/fail URLs, and session expiration rules. It provides a good high-level overview but is not fully complete.
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 descriptions cover 60% (6/10) of parameters, and the description adds no parameter-specific meaning. The remaining parameters client_email, client_first_name, client_last_name, and client_patronymic lack schema descriptions and are unaddressed by the description, so it fails to compensate for the coverage gap.
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 identifies the specific action 'Create a NovaPay Internet Acquiring payment session', distinguishes it from the sibling create_checkout_session by specifying 'Acquiring', and states the return value (session id) and the follow-up tool. This makes the purpose unambiguous and differentiates it from siblings.
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?
It explicitly instructs to follow up with add_acquiring_payment to get a payment URL, providing a clear when-to-use and next step. However, it does not contrast with create_checkout_session or state when not to use this tool, so it lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a NovaPay Checkout session (payment + Nova Poshta delivery collection). Returns the session id. To get a payment URL for the customer, follow up with add_checkout_payment.
| Name | Required | Description | Default |
|---|---|---|---|
| delivery | No | Delivery details object | |
| fail_url | No | ||
| metadata | No | ||
| success_url | No | ||
| callback_url | Yes | Merchant URL for postbacks (required for checkout) | |
| client_phone | No | Payer phone, e.g. +380501112233 | |
| create_express_waybill | No | Create a Nova Poshta express waybill |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses that the tool returns the session id and that the payment URL requires a separate call, which is key behavioral information. It stops short of stating prerequisites, side effects, or idempotency, but the disclosed workflow is meaningful.
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?
Three short sentences are front-loaded with the purpose, return value, and next step. Every sentence adds value without redundant elaboration.
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 has no output schema or annotations, the description covers the essential aspects: what it creates, what it returns, and the required follow-up. It doesn't explain optional parameters or prerequisites, but for a creation tool the core information is present.
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 57%, which the description does not augment. The description adds no meaning for parameters like delivery, metadata, or URLs beyond the schema, so it relies on its baseline.
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 'Create a NovaPay Checkout session' with the scope '(payment + Nova Poshta delivery collection)'. It also distinguishes from sibling tools by noting the follow-up with add_checkout_payment, which sets this apart from creating acquiring sessions.
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 provides context that this tool is for payment and delivery collection, and instructs to follow up with add_checkout_payment for the payment URL. However, it does not explicitly mention when to use this alternative to create_acquiring_session or any exclusions, leaving usage partially implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Invalidate an UNPAID session so its payment URL can no longer be paid. Use this to cancel a payment link that was created by mistake or is no longer needed. NovaPay returns no body β check the result with get_session_status.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | Session id (acquiring or checkout) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that the tool only works on UNPAID sessions, invalidates the payment URL, returns no body, and suggests using 'get_session_status' for verification. While it doesn't cover error cases or authorization requirements, it provides solid insight into the tool's runtime behavior.
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 three sentences, each with a distinct purpose: the action, the use case, and the response behavior plus follow-up. It is front-loaded with the core function and contains no redundant or extraneous information.
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 tool with a single parameter and no output schema, the description adequately covers the purpose, the precondition (UNPAID), the effect (payment URL becomes unpayable), and the verification step (use get_session_status). Minor gaps remain around error handling for invalid or paid session IDs, but the description is sufficient for correct selection and invocation.
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 already fully describes the only parameter 'session_id' as 'Session id (acquiring or checkout)'. The description adds context about the session being 'UNPAID' but does not provide additional parameter-specific syntax or formatting details. Since schema coverage is 100%, the baseline score 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 specifies the verb 'Invalidate' and the resource 'UNPAID session', with a concrete outcome: the payment URL can no longer be paid. It differentiates from siblings like 'void_session' by emphasizing the 'UNPAID' constraint, making the tool's purpose distinct.
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?
It explicitly states when to use the tool: 'Use this to cancel a payment link that was created by mistake or is no longer needed.' It also provides a follow-up instruction to 'check the result with get_session_status,' which guides the agent on next steps and differentiates from alternative session-management tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate an RSA 2048 keypair for NovaPay merchant onboarding. Returns the PUBLIC key (register it with NovaPay via the Acquiring3 admin panel or NovaPay support) and the file path of the PRIVATE key. The private key itself is never returned. Works without any configuration β this is the first onboarding step.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behaviors: returns the public key and file path of the private key, the private key itself is never returned, and no configuration is needed. This is sufficient for a simple key generation tool, though it doesn't mention file naming or security details.
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?
Three sentences, each earning its place: the core action, the output details, and the usage context. Front-loaded with a clear verb and resource, no redundancy or filler.
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 simplicity (no parameters, no output schema), the description fully covers what it does, what it returns, and when to use it. It even explains the next step (register public key), making it self-contained for an agent.
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 tool has zero parameters, so the schema provides no semantics. The description compensates by explaining the output (public key and private key path) and the purpose, which is more than enough for a parameterless tool. Baseline 4 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 starts with 'Generate an RSA 2048 keypair for NovaPay merchant onboarding,' which clearly identifies the action (generate), resource (keypair), and context (NovaPay onboarding). It is specific and differentiates from sibling payment/session tools, making it easy to select.
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?
States it is 'the first onboarding step' and 'works without any configuration,' giving clear context for when to use it. While it doesn't explicitly exclude alternatives, the sibling tools are unrelated (payments/sessions), so no alternative ambiguity exists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current status of a payment session (acquiring or checkout): lifecycle status (created/holded/paid/voided/expired/...), transaction status, amounts (decimal strings) and the list of payment operations. Use this to poll for payment results and to verify the outcome of complete_hold / void_session / expire_session.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | Session id (acquiring or checkout) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the key return contents: lifecycle status, transaction status, amounts as decimal strings, and list of payment operations. It implies a read-only operation but does not explicitly state it has no side effects, which would have made it fully transparent.
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 two sentences, front-loaded with the action and key details, and every clause adds value. It is concise without being under-specified, listing the specific status types and use cases.
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 status-query tool with one parameter and no output schema, the description is complete: it explains what data is returned and when to use it. It also implicitly differentiates from sibling tools, making the tool's role in the workflow fully clear.
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 schema already provides a clear description for session_id ('Session id (acquiring or checkout)'), covering 100% of the parameters. The tool description does not add further parameter-level details, but no additional clarification is needed given the simple, self-explanatory parameter.
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's action ('Get the current status') and resource ('a payment session'), and specifies the scope (acquiring or checkout). It distinguishes itself from sibling tools by focusing on status retrieval, not creation or modification, making its purpose unambiguous.
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 explicitly says 'Use this to poll for payment results and to verify the outcome of complete_hold / void_session / expire_session,' giving direct guidance on when to call it relative to other operations. It also indicates coverage for both session types, which is helpful context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cancel a PAID or HELD session: releases a hold or REFUNDS an already charged payment β real money moves back to the customer. Confirm with the user before calling this on a paid session. For unpaid sessions use expire_session instead. NovaPay returns no body β check the result with get_session_status.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | Session id (acquiring or checkout) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so admirably: it discloses that real money moves back to the customer, that holds are released, that NovaPay returns no body, and that status must be checked separately. This is rich, accurate behavioral disclosure.
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 compact and information-dense. Three sentences cover purpose, usage guidance, behavioral caveats, and response handlingβno wasted words, and the key action is front-loaded.
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 one-parameter tool with no output schema, the description is complete: it explains the operation's effect, side effects (money movement), appropriate exclusions (unpaid sessions), and how to verify success (get_session_status). Nothing essential is missing.
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 100% and the only parameter, session_id, already has a clear description ('acquiring or checkout'). The tool description adds no further parameter-level detail, so the baseline score 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 uses a specific verb ('Cancel') and resource ('session'), clearly scopes to PAID or HELD sessions, and explicitly distinguishes itself from expire_session for unpaid sessions. This differentiates it well from sibling tools.
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 explicitly states when to use (paid/held sessions), when not to use (unpaid sessions β expire_session), and instructs to confirm with the user before use on paid sessions. It also advises checking the result with get_session_status, providing clear alternatives and follow-up steps.
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. Dates show when Glama detected each change.
v0.1.0add_acquiring_paymentadd_checkout_paymentcomplete_holdcreate_acquiring_sessioncreate_checkout_sessionexpire_sessiongenerate_keysget_session_statusvoid_sessionEach tool targets a distinct resource/action: key generation, two session creation flows, two payment addition flows, status retrieval, and three lifecycle operations. The distinction between acquiring and checkout sessions is clear, and void/expire/complete_hold have explicit use-case boundaries.
All tool names follow a consistent verb_noun pattern in snake_case (generate_keys, create_acquiring_session, add_checkout_payment, etc.). The verbs and objects are uniformly structured, with no mixed casing or naming style deviations.
With 9 tools, the set is well-scoped for a payment processing server. Each tool serves a distinct step in the payment lifecycleβonboarding, session creation, payment addition, status polling, and post-payment actionsβwithout redundancy or bloat.
The tool set covers the full payment session lifecycle: key generation, session creation for both acquiring and checkout, payment addition, status tracking, and resolution via hold completion, void, or expiration. There are no obvious dead ends or missing operations for the stated purpose.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
The Mercado Pago MCP Server implements the Model Context Protocol to provide AI agents and LLMs with access to Mercado Pago's APIs and tools within compatible development environments. It acts as an intermediary that translates Mercado Pago resources into executable functions (tools) that AI applications can invoke to perform actions and automate flows. The server simplifies integration, enables using documentation to implement or improve code, and optimizes operations through natural language interactions without manual implementations.
MCP server for Modern Treasury β payment orders, transactions, counterparties and ledgers.
MCP Server for agents to onboard, pay, and provision services autonomously with InFlow
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/NovaPay/novapay-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
