.. meta:: :description: Connecting the Payneteasy MCP server to AI agents: A step-by-step guide to connecting Payneteasy stateless Streamable HTTP MCP server to Claude Desktop, Claude Code, and other AI agents, authenticated with a restricted access token. .. _mcp_guide: Payneteasy MCP Server ############################## .. toctree:: :maxdepth: 1 .. contents:: :local: .. role:: ex .. role:: code Introduction -------------------------- A step-by-step guide to connecting the Payneteasy :ex:`stateless Streamable HTTP MCP server` to Claude Desktop, Claude Code and other AI agents, authenticated with a restricted access token. .. list-table:: :header-rows: 1 :widths: 28 72 * - Key Concepts - * - Production endpoint - ``https://gate.payneteasy.ru/mcp-ui`` * - Authorization - ``Authorization: Bearer `` * - Transport - ``Streamable HTTP (stateless)`` * - Token rights - ``MCP Read Only`` .. note:: The server is **read-only**. A ``MCP Read Only`` token cannot mutate platform state — every exposed tool is annotated ``readOnlyHint: true``. MCP server URLs -------------------------- Pick the endpoint that matches your environment. The configuration examples throughout this guide use the **production** URL — replace it with the sandbox URL when needed. .. list-table:: :header-rows: 1 :widths: 20 45 35 * - Environment - MCP endpoint - Purpose * - **Production** - ``https://gate.payneteasy.ru/mcp-ui`` - Live payment traffic * - **Sandbox** - ``https://sandbox.payneteasy.ru/mcp-ui`` - Safe testing and integration .. warning:: The restricted access token is issued **per environment**. Create the token in the profile of the same environment you intend to connect to. A token from one environment will not work on another. Get a restricted access token --------------------------------------- Access to the MCP server uses a Bearer token. Payneteasy uses a **restricted access token** — it grants rights only to a selected set of operations. The ``MCP Read Only`` profile is enough to connect MCP. Step 1 — Open user profile ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Go to the *Restricted tokens* section: :code:`Profile` → :code:`Restricted tokens`. .. figure:: _static/images/screen-1.png :alt: User profile with the Restricted tokens section :width: 100% Step 2 — Click "Create token" ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To create token, press the :code:`Create token` button in the top-right corner of the Restricted tokens page. .. figure:: _static/images/screen-2.png :alt: Restricted tokens page with the Create token button :width: 100% Step 3 — Fill in the token parameters ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. list-table:: :header-rows: 1 :widths: 35 65 * - Field - Value * - Name - any token name, e.g. ``mcp-1`` (1) * - Lifetime in days - up to ``180`` (maximum) * - Access rights - tick the ``MCP Read Only`` checkbox (2) .. figure:: _static/images/screen-3.png :alt: Create token form with name, lifetime and MCP Read Only checkbox :width: 100% Step 4 — Create and copy the token ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Click :code:`Create token` (top-right of the form), then copy the token value and save it. .. figure:: _static/images/screen-4.png :alt: Window with the created token and the Copy to clipboard button :width: 100% .. warning:: The token is shown **only once**. Сlick "Copy to clipboard" and store it safely. The value cannot be viewed again. It is a long JWT string of the form ``eyJ…``. Claude Desktop --------------------------------------- Claude Desktop connects to remote MCP servers through a configuration file. Since Payneteasy server uses an HTTP transport, it is added to the ``mcpServers`` section. .. note:: In every configuration below, replace ```` with the value you copied. The token is sent to the server in the ``Authorization: Bearer `` header. File Location ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. list-table:: :header-rows: 1 :widths: 20 80 * - OS - Path * - macOS - ``~/Library/Application Support/Claude/claude_desktop_config.json`` * - Windows - ``%APPDATA%\Claude\claude_desktop_config.json`` It can be also opened from the app: :code:`Settings` → :code:`Developer` → :code:`Edit Config`. Configuration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. rubric:: claude_desktop_config.json .. code-block:: json { "mcpServers": { "Payneteasy": { "type": "http", "url": "https://gate.payneteasy.ru/mcp-ui", "headers": { "Authorization": "Bearer " } } } } .. note:: After saving the file, **fully restart Claude Desktop**. The connected server appears in the tools menu (the "🔌 / Search and tools" icon). Alternative: via mcp-remote ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If version of Claude Desktop does not support a direct HTTP transport, use the ``mcp-remote`` bridge (Node.js required): .. rubric:: claude_desktop_config.json — mcp-remote .. code-block:: json { "mcpServers": { "Payneteasy": { "command": "npx", "args": [ "-y", "mcp-remote", "https://gate.payneteasy.ru/mcp-ui", "--header", "Authorization: Bearer " ] } } } Windows: fixing the startup issue ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ On Windows, launching ``npx`` by an absolute path often breaks because of the space in ``C:\Program Files\nodejs``. The fix is to run it through ``cmd /c npx`` with a bare ``npx`` — it is picked up from ``PATH``, so the space no longer breaks argument parsing: .. rubric:: claude_desktop_config.json — Windows .. code-block:: json { "mcpServers": { "Payneteasy": { "command": "cmd", "args": [ "/c", "npx", "-y", "mcp-remote", "https://gate.payneteasy.ru/mcp-ui", "--header", "Authorization: Bearer " ] } } } That is, ``command`` = ``cmd``, and ``npx`` becomes the first argument after ``/c``. The resulting command line is ``cmd /c npx -y mcp-remote …``, and the space in "Program Files" no longer matters. .. note:: If it still misbehaves, as a fallback specify the 8.3 short path: ``"command": "C:\PROGRA~1\nodejs\npx.cmd"``. But the ``cmd /c npx`` variant is usually enough. Claude Code --------------------------------------- In Claude Code, MCP servers are added with a single ``claude mcp add`` command or via a ``.mcp.json`` file in the project root. Via the CLI ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The fastest way is to add an HTTP server with an authorization header: .. rubric:: Terminal .. code-block:: bash # transport http, server name Payneteasy claude mcp add --transport http Payneteasy \ https://gate.payneteasy.ru/mcp-ui \ --header "Authorization: Bearer " Visibility is set with the ``--scope`` flag: .. list-table:: :header-rows: 1 :widths: 20 80 * - Scope - Description * - ``local`` - only for you in the current project (default) * - ``project`` - in ``.mcp.json``, shared with the team via git * - ``user`` - available across all projects Checking the connection ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. rubric:: Terminal .. code-block:: bash claude mcp list # list servers and their status claude mcp get Payneteasy # server details Inside a Claude Code session, the status is checked with the ``/mcp`` command. Via the project file ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To make the server available to the whole team, add a ``.mcp.json`` to the repository root. It's best not to commit the token — move it to an environment variable: .. rubric:: .mcp.json .. code-block:: json { "mcpServers": { "Payneteasy": { "type": "http", "url": "https://gate.payneteasy.ru/mcp-ui", "headers": { "Authorization": "Bearer ${PAYNET_MCP_TOKEN}" } } } } .. rubric:: Terminal .. code-block:: bash export PAYNET_MCP_TOKEN="" .. note:: Claude Code expands ``${VAR}`` from the environment at startup. Commit ``.mcp.json`` to the repository, and keep the token itself in a local ``.env`` / secret manager. Other AI agents --------------------------------------- The principle is the same for every client: point to the endpoint ``https://gate.payneteasy.ru/mcp-ui``, use the **Streamable HTTP** transport, and the ``Authorization: Bearer `` header. Below are concrete configurations for popular agents. Cursor ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File: ``~/.cursor/mcp.json`` or ``.cursor/mcp.json`` in the project. .. rubric:: .cursor/mcp.json .. code-block:: json { "mcpServers": { "Payneteasy": { "url": "https://gate.payneteasy.ru/mcp-ui", "headers": { "Authorization": "Bearer " } } } } Then: **Settings → MCP → Enable** for the ``Payneteasy`` server. VS Code (GitHub Copilot / Agent Mode) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File: ``.vscode/mcp.json``. .. rubric:: .vscode/mcp.json .. code-block:: json { "servers": { "Payneteasy": { "type": "http", "url": "https://gate.payneteasy.ru/mcp-ui", "headers": { "Authorization": "Bearer " } } } } Start the server via the *Start* button above the block in ``mcp.json`` or with the ``MCP: List Servers`` command. Cline · Windsurf · other MCP clients ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Most clients use a single format. If a client only supports stdio, wrap the HTTP server with ``mcp-remote``: .. rubric:: mcp settings (generic) .. code-block:: json { "mcpServers": { "Payneteasy": { "command": "npx", "args": [ "-y", "mcp-remote", "https://gate.payneteasy.ru/mcp-ui", "--header", "Authorization: Bearer " ] } } } Manual check (curl) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Before configuring an agent, you can verify that the token works: .. rubric:: Terminal .. code-block:: bash curl https://gate.payneteasy.ru/mcp-ui \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' The response should contain the list of available tools — that means the server and token are configured correctly. .. admonition:: Parameter summary for any agent :class: tip * **URL** — ``https://gate.payneteasy.ru/mcp-ui`` * **Transport** — ``Streamable HTTP (stateless)`` * **Header** — ``Authorization: Bearer `` * **Token rights** — ``MCP Read Only`` Domain model --------------------------------------- The server ships a domain model in its ``instructions`` field so an agent knows how the entities relate before it calls any tool. The model is reproduced here. Orders and transactions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ * An **order** is a customer purchase attempt. It contains one or more **transactions**: pre-authorization, capture, refund, chargeback. * Transaction statuses are **approved**, **declined** and **filtered** (*filtered* = blocked by fraud-prevention rules before processing). Statistics tools ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``stats_*`` tools return **aggregates** (counts and amounts) — never individual orders. Use ``orders_search`` to find specific orders. .. list-table:: :widths: 25, 75 :header-rows: 1 :class: longtable * - Scope - Description * - :code:`stats_get_transaction_timeseries` - Returns count + amount per time bucket (day / week / month), split by transaction status. * - :code:`stats_get_transaction_summary` - Returns sales / reversals /chargebacks / frauds / disputes (counts + amounts + ratios) for a date range, broken down by card type, with a grand total. * - :code:`stats_list_top_entities` - Ranks merchants / companies / processors by a metric over a date range (highest first); reuse the returned ids in the ``*_get_details`` tools or as stats filters. * - :code:`stats_get_breakdown` - Splits a metric over a date range (bar chart) by transaction status, card-issuer / IP country, or decline / chargeback / fraud reason. Same filters as the timeseries tool. Order tools ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. list-table:: :widths: 25, 75 :header-rows: 1 :class: longtable * - Scope - Description * - :code:`orders_get_details` - Returns one order by id: the order/transaction summary, the customer's card metadata + masked contact, and the merchant routing. Sections appear only for the order APIs the token may call. * - :code:`orders_search` - Finds orders by a change-date window with optional status / entity filters and paging; returns safe order summaries. Use ``orders_get_details`` for one order's full detail. * - :code:`orders_get_logs` - Returns an order's processing session stages (the log trail), each stage with its message; ``mode=UNLIMITED`` for the full set. Resolving ids ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Resolve currency / card-type ids via ``refs_list_*``, and merchant / processor / manager / etc. ids via the ``*_search`` tools, before using them as stats filters. Indices --------------------------------------- * :ref:`genindex` * :ref:`search`