MCP server

Connecting

The server is remote and speaks the streamable HTTP transport, so you install nothing and run nothing locally. It answers at two addresses, which serve the same tools. Point your client at the endpoint to read the documentation with no credential, or to present a sandbox API key:

https://winkpg-internal-qa-portal.azurewebsites.net/mcp

Point your client at the sign-in address to connect with OAuth. It serves the same tools, but it asks your client to sign in on the first request, which is what starts the sign-in in most clients. The endpoint above never asks, so a client pointed there connects without offering you a sign-in. A deployment that doesn't run the authorization server doesn't serve the sign-in address.

https://winkpg-internal-qa-portal.azurewebsites.net/mcp/authorized

Client configuration

Most clients read a project-level file listing the servers a repository uses. Save the snippet below as .mcp.json in the root of your project and the server is available to every tool in that project. It connects with OAuth, so it names the sign-in address and carries no credential. Claude Code, Cursor and Visual Studio Code all read this shape, and a client with its own settings screen wants the same three values: a name, the address, and the transport.

{
  "mcpServers": {
    "winkpg": {
      "type": "http",
      "url": "https://winkpg-internal-qa-portal.azurewebsites.net/mcp/authorized"
    }
  }
}

If your client can't do OAuth, point it at the endpoint instead, add an Authorization header, and present a sandbox API key:

{
  "mcpServers": {
    "winkpg": {
      "type": "http",
      "url": "https://winkpg-internal-qa-portal.azurewebsites.net/mcp",
      "headers": {
        "Authorization": "Bearer ${WINKPG_API_KEY}"
      }
    }
  }
}

The integrator CLI writes this file for you, alongside the agent instructions it installs, and fills in this instance's own address:

winkpg-integrator setup

The file it writes carries the Authorization header. To connect with OAuth instead, delete the headers block and change the url to the sign-in address. Your client asks you to sign in the next time it connects.

Authentication

The documentation tools need no credential at all: they publish exactly what this site already serves to any visitor, so an agent can read the whole integration surface before you hold a key. The two executing tools, execute_sandbox_request and certify_integration, need one, and they read it from the Authorization header your client sends on the connection.

There are two ways to present it, and your client decides which. Connect with OAuth if your client supports it: you sign in to the portal in a browser, approve the client once, and no key is pasted anywhere. A client that can't do OAuth sends a sandbox API key on the connection instead, which stays fully supported.

Connecting with OAuth

Add the sign-in address with no credential at all. Your client asks this instance what it needs, registers itself, and opens a browser so you can sign in to the WinkPG Developer Portal and approve it. You paste nothing, and the connection that results reaches all seven tools.

1. Add the sign-in address above to your client with no Authorization header. Its first request comes back 401 with a pointer to this instance's resource metadata, which is how your client knows to sign in. That refusal is expected, and nothing is wrong with the connection.
2. Your client finds the authorization server. It reads the metadata documents in the table below, which it asks for on its own. A pointer to the same documents comes back later in any refusal of a token this instance no longer accepts, which is how a client knows to authorize again.
3. Your client registers itself, on a deployment that publishes a registration address. By default a registration takes no credential, and a deployment can require a signed-in portal session instead. A registration grants nothing on its own: what comes back is an identifier and the addresses this server may answer to.
4. A browser opens on the portal. Sign in the way you always do. If you already have a portal session, this step passes without a prompt.
5. Approve the connection. The screen names the client, the merchant it would act on, and what it asks to do. Your answer holds for 90 days by default, so a client you reconnect each morning doesn't ask again.
6. Your client gets a token and connects. No credential is written into your project files, and the token works at the endpoint too. A client connected to the endpoint with no credential is refused by the two executing tools, and the refusal names the sign-in address.

Signing in from your client

Every client below signs in from the sign-in address, with no key configured.

Your client reads these documents on its own. They're listed here so you can see what this instance publishes, and so you can set up a client that doesn't discover them. Each address has its own resource document, and a refusal points at the one for the address your client called. A deployment that doesn't run the authorization server serves none of them.

The approval screen lists what the client asked for. There are two scopes, and a token never carries more than your own portal role holds.

• An access token is short lived, 15 minutes by default. Your client refreshes it in the background, and the refresh token is replaced each time it's used, so a long sitting asks nothing of you.
• A token never grants more than you hold. Each approval derives the scopes from your own portal role, so a read-only developer gets a token that reads, whatever the client asked for.
• Executing still runs against the sandbox. The token is exchanged for the same short-lived sandbox credential the Try-It console uses, so it reaches test data only and spends the same run budget.
• You can end a connection at any time. The portal's Sessions page lists what's signed in as you and every application you've approved, and it ends one or all of them. Ending one stops the refresh straight away, and a token already issued lapses when its own short lifetime runs out.

Connecting with an API key

A client that can't do OAuth sends a sandbox API key as the bearer value on the connection, the way the second snippet above does. When yours does:

• Present a sandbox API key, which is prefixed sk_test_. A live key (sk_live_) is refused outright, before anything is composed and before any call is sent. No setting changes this, and no tool here reaches production.
• The key is read per request, forwarded to the API in the platform's own header, and dropped. It's never stored on a session, never written to a log, and never echoed back in a tool result.
• Executing charges the same sandbox run budget the Try-It console and the blueprint runner charge. Spending it in one surface spends it in the others, which is deliberate: one budget for one developer, not one per way of reaching it.
• Keep the key in an environment variable your client expands rather than committed into .mcp.json. Commit the file, never the key.

Tools

Seven tools, of which five read and two send. Your client lists them once it connects. They're named here so you can tell what an agent did.

Limits

• Tool calls are rate limited per caller. An agent that hits the limit is told so in the tool result and should wait rather than retry immediately.
• A response body comes back as a bounded excerpt with always-sensitive fields blanked, and it says so when it has been shortened. It's for confirming a call worked, not for reading a full payload.
• Card numbers, CVVs and expiration dates are cardholder data. Use only the test values the sandbox testing guide publishes, and never a real one.