> For the complete documentation index, see [llms.txt](https://plexo.gitbook.io/rest-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://plexo.gitbook.io/rest-api/getting-started/mcp-server.md).

# MCP Server (AI Integration)

The Plexo MCP Server lets AI agents interact with Plexo payment gateway capabilities through the Model Context Protocol. It is intended for approved operational and integration workflows where an MCP-compatible client can call Plexo tools on behalf of an authenticated Dashboard user.

## What is the MCP Server?

The **Model Context Protocol (MCP)** is an open standard that allows AI assistants such as Claude, Cursor, VS Code, or custom agents to interact with external services. Plexo exposes payment gateway functionality as MCP tools, so an agent can perform guided operations without requiring the user to write direct REST calls.

**Instead of writing code like this:**

```bash
curl -X POST https://api.plexo.com.uy/v1/payments \
  -H "Authorization: Basic ..." \
  -d '{"merchantId": 123, "amount": 100.00, ...}'
```

**You can ask an MCP client:**

> "Create a $100 payment for merchant 123 using VISA"

The MCP client calls Plexo tools, handles validation, and reports API errors in a developer-friendly format.

## Available Tools

The MCP server exposes tools across these categories:

| Category            | Examples                                                |
| ------------------- | ------------------------------------------------------- |
| **Payments**        | List, get, create, capture, cancel, and refund payments |
| **Merchants**       | List merchants and inspect merchant configuration       |
| **Customers**       | Manage customers and saved payment instruments          |
| **Payment Methods** | Inspect and configure merchant payment methods          |
| **Sessions**        | Inspect checkout and tokenization sessions              |
| **Reference Data**  | List payment methods, processors, and error codes       |
| **Documentation**   | Search and retrieve Plexo API documentation             |

Tool availability depends on the OAuth scopes granted to the MCP client and on the merchant/workspace permissions of the authenticated Dashboard user.

## Authentication

Plexo MCP uses **OAuth 2.0 Authorization Code with PKCE**, following the MCP authorization recommendations. MCP tool calls use Bearer tokens, not REST API Basic Auth credentials.

The normal flow is:

1. Configure the Plexo MCP resource URL in an MCP client.
2. The client discovers the protected resource metadata from the MCP endpoint.
3. The client starts the OAuth authorization flow against the Plexo MCP OAuth server.
4. The user signs in with their Dashboard account and confirms access.
5. The client receives access and refresh tokens.
6. The client calls `/mcp` with `Authorization: Bearer <access_token>`.

{% hint style="warning" %}
Do not put REST API keys or Dashboard passwords in MCP client configuration. MCP access is delegated through OAuth and can be revoked without rotating REST API keys.
{% endhint %}

## OAuth Discovery

Unauthenticated MCP requests return a Bearer challenge with the protected resource metadata URL:

```http
WWW-Authenticate: Bearer resource_metadata="https://api.testing.plexo.com.uy/.well-known/oauth-protected-resource/mcp"
```

Clients can also fetch metadata directly:

```bash
curl https://api.testing.plexo.com.uy/.well-known/oauth-protected-resource/mcp
curl https://mcp-oauth.testing.plexo.com.uy/.well-known/oauth-authorization-server
curl https://mcp-oauth.testing.plexo.com.uy/.well-known/openid-configuration
```

The authorization server exposes:

| Endpoint                                  | Purpose                                                 |
| ----------------------------------------- | ------------------------------------------------------- |
| `/.well-known/oauth-authorization-server` | OAuth authorization server metadata                     |
| `/.well-known/openid-configuration`       | OpenID Connect discovery metadata                       |
| `/connect/authorize`                      | Authorization Code + PKCE authorization endpoint        |
| `/connect/token`                          | Token exchange and refresh token endpoint               |
| `/connect/revocation`                     | Token revocation endpoint                               |
| `/connect/register`                       | Dynamic Client Registration, only when enabled by Plexo |

## Scopes

Plexo grants MCP access with narrowly scoped permissions:

| Scope                       | Access                                 |
| --------------------------- | -------------------------------------- |
| `mcp:docs:read`             | Read Plexo documentation through MCP   |
| `mcp:reference:read`        | Read reference data                    |
| `mcp:merchants:read`        | Read merchant data                     |
| `mcp:merchant-config:write` | Update merchant configuration          |
| `mcp:customers:read`        | Read customer data                     |
| `mcp:customers:write`       | Create or update customer data         |
| `mcp:payment-links:read`    | Read payment links                     |
| `mcp:payment-links:write`   | Create or update payment links         |
| `mcp:payments:read`         | Read payment data                      |
| `mcp:payments:write`        | Create or modify payments              |
| `mcp:sessions:read`         | Read checkout or tokenization sessions |
| `mcp:sessions:write`        | Create or modify sessions              |

Tokens also include Plexo context claims, such as the Dashboard user, OAuth client, Plexo client, workspace, and allowed merchant access. Tool calls still enforce the same merchant isolation and authorization rules as the REST API.

## Supported MCP Clients

Use the Plexo MCP URL as the server URL. OAuth-capable MCP clients should discover the authorization server automatically from the protected resource metadata.

### Claude Desktop

Add the server URL to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "plexo": {
      "url": "https://api.testing.plexo.com.uy/mcp",
      "transport": "http"
    }
  }
}
```

### Cursor

Add the server URL to Cursor settings:

```json
{
  "mcp.servers": [
    {
      "name": "Plexo Payment Gateway",
      "url": "https://api.testing.plexo.com.uy/mcp"
    }
  ]
}
```

### VS Code

Add the server URL to `.vscode/mcp.json`:

```json
{
  "servers": {
    "plexo-mcp": {
      "type": "http",
      "url": "https://api.testing.plexo.com.uy/mcp"
    }
  }
}
```

If your MCP client does not support OAuth for remote HTTP MCP servers, contact Plexo before using it with production data.

## Environments

| Environment | MCP endpoint                           | Protected resource metadata                                                 | OAuth issuer                             |
| ----------- | -------------------------------------- | --------------------------------------------------------------------------- | ---------------------------------------- |
| Testing     | `https://api.testing.plexo.com.uy/mcp` | `https://api.testing.plexo.com.uy/.well-known/oauth-protected-resource/mcp` | `https://mcp-oauth.testing.plexo.com.uy` |
| Production  | `https://api.plexo.com.uy/mcp`         | `https://api.plexo.com.uy/.well-known/oauth-protected-resource/mcp`         | `https://mcp-oauth.plexo.com.uy`         |

{% hint style="warning" %}
Always use the testing environment during development. MCP access follows the same environment separation as the REST API.
{% endhint %}

## Example Workflows

### Investigate a Payment

> "Show me the details of payment 12345"

The agent retrieves payment information, including status, transactions, and metadata, if the token has payment read access and the user is authorized for the merchant.

### Process a Refund

> "Refund $50 from payment 12345"

The agent validates the refund amount, checks payment status, and processes the partial refund if the token has payment write access.

### Search Documentation

> "How do I implement 3DS authentication?"

The agent searches Plexo documentation and returns relevant guides and code examples.

### List Failed Payments

> "Show me all failed payments for merchant 123 from last week"

The agent queries payments with appropriate filters and presents the results.

## Security

The MCP server maintains Plexo security boundaries:

* OAuth Bearer tokens with short-lived access tokens and refresh tokens
* User login and consent through Plexo Dashboard identity
* Client, workspace, and merchant-scoped access
* No PAN, CVV, track data, or raw card data exposed through MCP tools
* Revocable OAuth tokens without rotating REST API credentials
* Audit logging and rate limiting

## Related Resources

* [Authentication](/rest-api/getting-started/authentication.md)
* [API Environments](/rest-api/getting-started/environments.md)
* [Security](/rest-api/core-concepts/security.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://plexo.gitbook.io/rest-api/getting-started/mcp-server.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.