AI assistants (MCP)
Connect Claude, Cursor, VS Code and other AI assistants to your GTRADE account with the hosted MCP server, then create payment links and check payments by asking in plain language.
#What it is
The GTRADE MCP server lets AI assistants use your GTRADE account. It speaks the Model Context Protocol (MCP), the open standard that assistants such as Claude Code, Claude Desktop, Cursor and VS Code use to call external tools.
Once it is connected you can ask, for example, "Create a $49 payment link for [email protected] for order ORD-1042". The assistant calls the GTRADE API with your API key and hands you the checkout link.
- Hosted by GTRADE. You install nothing on a server. Every tool call goes straight to the live API.
- Your API key, your account. The assistant can only do what your API key can do: create and read payments, and manage webhook endpoints.
- Live data. Payments created through the assistant are real payment requests, exactly like those created with the API or an SDK.
#Server URL
| Setting | Value |
|---|---|
| Endpoint | https://mcp.gtradegateway.io/mcp |
| Transport | Streamable HTTP (MCP protocol versions 2024-11-05 to 2025-11-25) |
| Authentication | Authorization: Bearer <your API key> on every request |
The server is stateless: it does not keep sessions, so reconnecting never loses anything. The legacy HTTP+SSE transport (/sse) is not offered. Every current client supports Streamable HTTP, and mcp-remote bridges clients that only run local servers.
#Authentication
Use a merchant API key from the dashboard under Developers → API Keys (see Authentication). We recommend creating a separate key for your AI assistant, so you can revoke it without touching your shop integration.
Send the key as a bearer token on every request:
Authorization: Bearer YOUR_API_KEYThe server checks the key against the API on connection and then uses it only to call the API on your behalf. The key is not stored by the MCP server and is never written to its logs.
A missing, wrong or revoked key gets 401 Unauthorized with a WWW-Authenticate: Bearer header, and the client reports that it could not connect:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="GTRADE MCP", error="invalid_token", error_description="Invalid or revoked GTRADE API key."
Content-Type: application/json
{"jsonrpc":"2.0","error":{"code":-32001,"message":"Invalid or revoked GTRADE API key."},"id":null}The server does not implement OAuth sign-in. Use a client that lets you set a request header, as in the setup steps below.
#Tools
| Tool | What it does | Changes data |
|---|---|---|
create_payment | Creates a payment and returns its checkout_url. Inputs: amount_usd, customer_email, optional customer_id, metadata and idempotency_key. | Yes |
get_payment | Returns one payment by id: status, amount requested, amount paid, coin and network. | No |
list_payments | Lists payments, newest first. Optional limit (1–100, default 10), status and starting_after for the next page. | No |
create_webhook | Registers a public https:// URL to receive webhook events. | Yes |
list_webhooks | Lists your webhook endpoints. | No |
delete_webhook | Deletes a webhook endpoint by id. | Yes (destructive) |
send_test_webhook | Sends a signed payment.test event to an endpoint and reports the result of the first attempt. | Sends a request to your endpoint |
check_connection | Checks that the API is reachable and that your key is valid, and shows your remaining requests this minute. | No |
Each tool returns a short human-readable summary plus structured data (the same Payment and webhook objects as the API). Read-only tools are marked readOnlyHint and delete_webhook is marked destructiveHint, so clients that support these hints can skip confirmation for reads and ask before deleting.
The server also provides:
- a prompt,
create_payment_link(argumentsamount_usd,customer_email, optionalorder_id), which clients such as Claude Code show as a slash command; - a resource,
gtrade://docs, with links to this documentation.
Errors from the API come back as tool errors that include the error code and request_id, for example GTRADE API error (HTTP 404, payment_not_found): No such payment. Request id: req_3c773b2d43214881. Quote the request id when you contact support.
#Setup
In every example, replace YOUR_API_KEY with your key, or better, keep it in an environment variable as shown.
#Claude Code
Add the server with claude mcp add:
claude mcp add --transport http gtrade https://mcp.gtradegateway.io/mcp \
--header "Authorization: Bearer $GTRADE_API_KEY"This adds the server to the current project for you only (--scope local, the default). Add --scope user to use it in all your projects. Do not use --scope project with a real key: that scope writes the key into .mcp.json, which is meant to be committed.
Check the connection:
claude mcp listgtrade: https://mcp.gtradegateway.io/mcp (HTTP) - ✔ ConnectedInside Claude Code, /mcp shows the server and its tools. To remove it, run claude mcp remove gtrade.
#Cursor
Add the server to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):
{
"mcpServers": {
"gtrade": {
"url": "https://mcp.gtradegateway.io/mcp",
"headers": {
"Authorization": "Bearer ${env:GTRADE_API_KEY}"
}
}
}
}Cursor replaces ${env:GTRADE_API_KEY} with the environment variable of that name, so set GTRADE_API_KEY in your shell profile or system environment and restart Cursor. You can also write the key directly in place of the variable, but then keep the file out of source control.
#Claude Desktop
Claude Desktop starts local MCP servers from its configuration file, so connect through mcp-remote, a small bridge that runs with npx (it needs Node.js 18 or later on your computer).
Open Settings → Developer → Edit Config and add:
{
"mcpServers": {
"gtrade": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://mcp.gtradegateway.io/mcp",
"--header",
"Authorization:${AUTH_HEADER}"
],
"env": {
"AUTH_HEADER": "Bearer YOUR_API_KEY"
}
}
}
}The file is ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows. Restart Claude Desktop afterwards; the GTRADE tools then appear in the tools menu of the chat box.
Note: Keep Authorization:${AUTH_HEADER} exactly as shown, with no space after the colon, and put Bearer YOUR_API_KEY in env. Some clients (including Claude Desktop on Windows) do not pass spaces inside args through correctly; values in env can contain spaces.
To keep the key out of the process list, mcp-remote can also read headers from a file: replace the last two arguments with "--header-file", "/path/to/headers.txt", where the file contains the line Authorization: Bearer YOUR_API_KEY.
#VS Code
Create .vscode/mcp.json in your workspace (or run MCP: Open User Configuration for all workspaces). The inputs entry makes VS Code ask for the key once and store it securely instead of saving it in the file:
{
"inputs": [
{
"type": "promptString",
"id": "gtrade-api-key",
"description": "GTRADE API key",
"password": true
}
],
"servers": {
"gtrade": {
"type": "http",
"url": "https://mcp.gtradegateway.io/mcp",
"headers": {
"Authorization": "Bearer ${input:gtrade-api-key}"
}
}
}
}Start the server from the Start link above its entry in mcp.json (or with MCP: List Servers), then use the tools in Copilot Chat in agent mode.
#Other clients
Any MCP client that supports the Streamable HTTP transport and custom request headers can connect:
- URL:
https://mcp.gtradegateway.io/mcp - Header:
Authorization: Bearer YOUR_API_KEY
Clients that can only start local (stdio) servers can use the same npx mcp-remote command as Claude Desktop. Clients that only support OAuth sign-in for remote servers cannot connect, because the server authenticates with your API key only.
To test the endpoint by hand:
curl -s https://mcp.gtradegateway.io/mcp \
-H "Authorization: Bearer $GTRADE_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"check_connection","arguments":{}}}'#Example prompts
- Create a $25 payment link for [email protected] with order id ORD-1042.
- Has payment 9f439f25-f403-446c-9c6a-ecd4aab265e3 been paid? How much has arrived?
- List my last 20 payments and summarise how many are paid, open and cancelled.
- Show all partially paid payments and how much is still missing on each.
- Register https://shop.example.com/webhooks/gtrade as a webhook endpoint and send it a test event.
- Which webhook endpoints do I have? Delete the one pointing to staging.
- Check that my GTRADE connection works.
When you pass an order id, ask the assistant to use it as the idempotency_key as well. Then, if the assistant retries the request, it gets the same payment back instead of creating a second one (see idempotency).
#Security
- Treat the assistant like any other holder of your API key. It can create payment requests and register or delete webhook endpoints on your live account. Use a dedicated key and revoke it in the dashboard when you no longer need it. Revoked keys stop working within 5 minutes.
- Review actions before you approve them. Most clients ask before running a tool; keep that confirmation on for
create_payment,create_webhookanddelete_webhook. - Never treat a payment as paid because the assistant says so in passing. Fulfil orders from the
paidstatus in a verified webhook or aget_paymentresult. - Watch for prompt injection. Text that the assistant reads from web pages, emails or files can try to make it call tools. Do not connect the server to an assistant that processes untrusted content unattended.
- Keep the key out of shared files. Use environment variables or your client's secret input (as in the Cursor and VS Code examples), and do not commit configuration files that contain the key.
- No funds can move through the MCP server. None of the tools sends money or changes payout settings. They create payment requests and manage webhook endpoints only.
- Limits. API calls made through the MCP server count towards your key's rate limit of 120 requests per minute. The MCP server also limits requests and failed authentications per IP address and answers
429withRetry-Afterwhen they are exceeded.