@paymos/mcp 1.5.0 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,17 @@
2
2
 
3
3
  ## [Unreleased]
4
4
 
5
+ ## [1.6.0] - 2026-11-18
6
+
7
+ - feat(mcp): implement merchant-mcp-phase2 OAuth 2.1 host, dashboard parity, and CLI
8
+
9
+ - feat(mcp): connect a merchant account from Codex or Claude Code through Paymos OAuth, with Owner consent and dashboard connection management
10
+ - feat(mcp): add proof-bound `install-secret`, `upload-file`, and `download-file` helpers alongside local Sandbox
11
+
12
+ ## [1.5.1] - 2026-11-13
13
+
14
+ - fix(plugins,publicweb): SDK webhook credit recipes, CMS recovery, redirects and CSP logs (audit 2026-11-13)
15
+
5
16
  ## [1.5.0] - 2026-11-07
6
17
 
7
18
  - feat(publicweb,docs,blazor,mcp): add MCP prompt tab to code snippets and compact /contacts header
package/README.md CHANGED
@@ -1,18 +1,75 @@
1
1
  # @paymos/mcp
2
2
 
3
- Connect your coding agent to the Paymos sandbox through a local MCP server. The agent can create test invoices, simulate payment scenarios, inspect invoice states, and verify webhook signatures while building your application around a Paymos server SDK.
3
+ Paymos offers a local Sandbox server for integration testing and a hosted MCP connection for your merchant account.
4
4
 
5
- The local MCP server connects your coding agent to the Paymos sandbox with 14 tools and five documentation resources for testing merchant integrations.
5
+ ## Connect a merchant account
6
6
 
7
- Use a test Payment key pair. Live and Payout keys are rejected; API requests are signed through the official SDK, and real funds are not involved.
7
+ Use the hosted Streamable HTTP URL when Merchant MCP is enabled for your Paymos instance.
8
8
 
9
- ## Requirements
9
+ - URL `https://app.paymos.io/connect/merchant-mcp`
10
+ - OAuth scopes `merchant:mcp` and `offline_access`
11
+
12
+ Start sign-in from the MCP settings or your terminal. Paymos opens in your browser. The account owner chooses the merchant and environments, reviews the access being granted, and confirms. The client stores its OAuth session and can then call the merchant tools. Dashboard → Developers → Agents shows connection status, activity, recent operations and the Disconnect action.
13
+
14
+ ### Paymos command
15
+
16
+ ```bash
17
+ paymos auth --client codex
18
+ paymos auth --client claude-code
19
+ ```
20
+
21
+ With the npm package, run `npx -y @paymos/mcp auth --client codex`. The helper adds the hosted entry and starts the native browser flow. It uses `paymos-merchant` when `paymos` is already the Sandbox entry.
22
+
23
+ ### Codex
24
+
25
+ In MCP settings, add Paymos as a Streamable HTTP server and choose Authenticate. For a pre-registered OAuth client, set the following in your Codex `config.toml`.
26
+
27
+ ```toml
28
+ [mcp_servers.paymos]
29
+ url = "https://app.paymos.io/connect/merchant-mcp"
30
+ scopes = ["merchant:mcp", "offline_access"]
31
+
32
+ [mcp_servers.paymos.oauth]
33
+ client_id = "paymos-merchant-codex"
34
+ callback_port = 33419
35
+ callback_url = "http://127.0.0.1:33419/callback"
36
+ ```
37
+
38
+ Run `codex mcp login paymos`. Use the same listener port and callback URL. For a coexisting Sandbox entry, use `paymos-merchant` in both the configuration and the login command. [Codex MCP configuration](https://learn.chatgpt.com/docs/config-file/config-reference)
39
+
40
+ ### Claude Code
41
+
42
+ ```bash
43
+ claude mcp add --transport http --scope user --client-id paymos-merchant-claude-code --callback-port 33420 paymos https://app.paymos.io/connect/merchant-mcp
44
+ claude mcp login paymos
45
+ ```
46
+
47
+ You can also select Paymos → Authenticate in Claude Code’s `/mcp` panel. When a local Paymos Sandbox entry already occupies the name, use `paymos-merchant` in both commands. Clients with public OAuth discovery and native loopback dynamic registration can use the hosted URL directly. [Claude Code MCP sign-in](https://code.claude.com/docs/en/mcp#authenticate-from-the-command-line)
48
+
49
+ ### Key and file delivery
50
+
51
+ The merchant tools can create and rotate Payment and Payout credentials under the merchant’s access policy. The tools return a short-lived installer ticket. The installer uses a verifier generated on the destination machine to exchange the ticket and save the credentials into the chosen environment file.
52
+
53
+ ```bash
54
+ paymos install-secret --prepare --env-file .env --merchant-id "$PAYMOS_MERCHANT_ID" --environment production --operation-id "$PAYMOS_OPERATION_ID"
55
+ paymos install-secret --env-file .env --request-id "$PAYMOS_REQUEST_ID" --token "$PAYMOS_INSTALLER_TICKET"
56
+ ```
57
+
58
+ Pass the first command’s `request_id` and `challenge` as the tool’s `delivery` input with the same merchant, environment and operation ID. Run the second command on the same machine with the returned ticket. For private exports and staged logo or avatar uploads, the `download-file` and `upload-file` helpers use the same prepare-and-redeem flow with `--file`. Upload preparation also supplies the file size, content type and hash.
59
+
60
+ Withdrawals follow the merchant’s current policy and native approval rules. Manage withdrawal whitelist addresses from the dashboard.
61
+
62
+ ## Local Sandbox
63
+
64
+ The local stdio server provides 14 tools and five documentation resources for creating and simulating test invoices, checking invoice states and verifying webhook signatures. It signs API requests with the official SDK using a test Payment key pair.
65
+
66
+ ### Requirements
10
67
 
11
68
  - Requires Node.js 22.12 or later.
12
69
  - A Paymos merchant account with a test key pair from Dashboard → Developer → API Keys (`pk_test_…` and `sk_test_…`)
13
70
  - An MCP client that can launch a local stdio server
14
71
 
15
- ## Setup
72
+ ### Setup the local server
16
73
 
17
74
  Run:
18
75
 
@@ -216,8 +273,6 @@ The server opens no network listener and calls the Merchant API through `@paymos
216
273
 
217
274
  Live (`pk_live_`/`sk_live_`) and payout (`rk_…`) keys are rejected during setup, at server startup, and on tool calls. After checking your integration in the sandbox, run your own application with its live keys. This local MCP server stays outside production payment paths.
218
275
 
219
- Hosted MCP is deferred and is not available as a connection method.
220
-
221
276
  ## Development
222
277
 
223
278
  ```bash