> ## Documentation Index
> Fetch the complete documentation index at: https://support.pexcard.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Connecting the PEX MCP Server to your AI assistant
> Run the PEX MCP Server locally over stdio and wire it into Claude Desktop, Claude Code, GitHub Copilot in VS Code, Cursor, Windsurf, or any other MCP-compatible AI assistant.
The **PEX MCP Server** is a [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes the [PEX Card External API](https://developer.pexcard.com/) as a set of read-only tools. Wire it into an AI assistant like **Claude Desktop**, **Claude Code**, **GitHub Copilot** in VS Code, **Cursor**, or **Windsurf** and you can analyze business spending, review transactions, monitor card activity, and inspect spending rules — all in natural language.
This article walks through generating an API token, running the server locally over `stdio`, and verifying the connection.
**Heads up — Beta feature.**
Authorized apps and the PEX MCP Server are currently labeled **Beta** in the PEX dashboard. To get access, contact the PEX support team at `adminsupport@pexcard.com`. Behavior and field names may change.
**Hosted vs. local.**
This article covers the **local stdio** integration where the MCP Server runs on your own machine. If you want to wire PEX into a **Microsoft Copilot Studio agent** instead, use the hosted endpoint — see [Connecting the PEX MCP Server to a Microsoft Copilot Studio agent](/developer-guide/connecting-pex-mcp-to-copilot-studio).
***
## Prerequisites
Before you start, make sure you have:
* A **PEX business account with admin access** in the PEX dashboard (`https://dashboard.pexcard.com`).
* **Two-factor authentication (MFA) enabled** on your PEX account — token generation requires MFA. If MFA is not yet enabled, turn it on under **Profile** > **Two-Factor Authentication** in the dashboard first.
* **[Node.js](https://nodejs.org/)** installed locally (used to run the server with `npx`). Any active LTS version works.
* Access to your chosen AI client — Claude Desktop, Claude Code (CLI), VS Code with GitHub Copilot, Cursor, Windsurf, or any other MCP-compatible client.
***
## Step 1. Generate a PEX API token
Sign in to the PEX dashboard and open your **user profile** (click your avatar in the top-right and choose your name).
Navigate to **Profile** > **Authorized apps**, or go directly to `https://dashboard.pexcard.com/account/authorized-apps`. The tab is marked **Beta**.
Find the **PEX MCP Server** application in the list and click the **MCP server config** button.
Complete the MFA prompt when it appears. This is required every time you generate a new token.
Click **Generate** and copy the token value immediately. You will paste it into your AI client's configuration in Step 3.
**Important — the token is shown only once.**
Copy the token immediately and store it securely (for example, in your password manager). The dashboard will not show it again. If you lose it, you can always come back to this page and generate a new one — previously generated tokens remain active until you revoke them.
**Treat this token like a password.**
Anyone with the token can call PEX tools as you. Do not commit it to version control or share it publicly. If you suspect it has been exposed, revoke it on the same Authorized apps page and generate a new one. PEX support contact for anything unusual: `adminsupport@pexcard.com`.
***
## Step 2. Pick the environment variables
Every client uses the same two environment variables to point the server at PEX and authenticate. Note them down — you will paste them into the client config in Step 3.
| Variable | Required | Description |
| --------------- | -------- | ---------------------------------------------------------------------- |
| `PEX_API_URL` | Yes | PEX API base URL. Use `https://coreapi.pexcard.com/v4` for production. |
| `PEX_API_TOKEN` | Yes | The API token you copied in Step 1. |
Both variables are required at startup — if either is missing, the server exits immediately with a descriptive error.
***
## Step 3. Wire up your AI client
Pick the client you want to use. The configuration shape is the same in each — only the file location and the wrapping property name change.
### Option A. Claude Desktop
Add the PEX MCP Server to your `claude_desktop_config.json`:
```json theme={null}
{
"mcpServers": {
"pex": {
"command": "npx",
"args": ["-y", "@pexcard_engineering/mcp"],
"env": {
"PEX_API_URL": "https://coreapi.pexcard.com/v4",
"PEX_API_TOKEN": "your-api-token-here"
}
}
}
}
```
Config file locations:
* **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
Replace `your-api-token-here` with the token you generated in Step 1, then restart Claude Desktop to apply the changes.
### Option B. Claude Code (CLI)
Add the MCP Server in a single command:
```bash theme={null}
claude mcp add pex \
-e PEX_API_URL=https://coreapi.pexcard.com/v4 \
-e PEX_API_TOKEN=your-api-token-here \
-- npx -y @pexcard_engineering/mcp
```
Or add it manually to `.claude/settings.json`:
```json theme={null}
{
"mcpServers": {
"pex": {
"command": "npx",
"args": ["-y", "@pexcard_engineering/mcp"],
"env": {
"PEX_API_URL": "https://coreapi.pexcard.com/v4",
"PEX_API_TOKEN": "your-api-token-here"
}
}
}
}
```
Run `/mcp` in your Claude Code session to verify the connection.
### Option C. GitHub Copilot in VS Code
Add the server to your VS Code settings (`.vscode/settings.json` for a single workspace, or your user settings for every workspace):
```json theme={null}
{
"github.copilot.chat.mcpServers": {
"pex": {
"command": "npx",
"args": ["-y", "@pexcard_engineering/mcp"],
"env": {
"PEX_API_URL": "https://coreapi.pexcard.com/v4",
"PEX_API_TOKEN": "your-api-token-here"
}
}
}
}
```
Alternatively, create an `.mcp.json` file in your project root:
```json theme={null}
{
"servers": {
"pex": {
"command": "npx",
"args": ["-y", "@pexcard_engineering/mcp"],
"env": {
"PEX_API_URL": "https://coreapi.pexcard.com/v4",
"PEX_API_TOKEN": "your-api-token-here"
}
}
}
}
```
**Tip:**
When using `.mcp.json`, add it to your `.gitignore` if it contains your actual token, or reference an environment variable so secrets stay out of source control.
### Option D. Other MCP clients (Cursor, Windsurf, and others)
For any MCP-compatible client, use the following server configuration and consult your tool's MCP documentation for where to put it:
* **Command:** `npx`
* **Arguments:** `-y @pexcard_engineering/mcp`
* **Environment variable** `PEX_API_URL`: `https://coreapi.pexcard.com/v4`
* **Environment variable** `PEX_API_TOKEN`: your PEX API token
***
## Step 4. Verify the connection
Open a new chat in your AI client and try one of these prompts to confirm everything is working:
* *"What is my business profile?"*
* *"Show me the current business account balance."*
* *"List my recent transactions."*
In Claude Code, you can also run `/mcp` to check that the **pex** server appears in your connected servers list.
If the connection is working, the assistant will call `pex_get_business_profile` (or a similar tool) and return your live PEX data — Business Account ID, name, address, contact info, and so on.
***
## Example use cases
Once the server is connected, you can ask the assistant questions in plain English that span analytics, card management, and broader business operations.
### Data analysis & reporting
```
"What is our current business account balance?"
"Show me all transactions over $500 from the past 30 days."
"Which cards have the highest spending this month?"
"List all declined transactions for our business."
```
### Card & account management
```
"Show me the spending rules for card #12345."
"What are the scheduled funding rules for this card?"
"List all cardholders and their account details."
"What card orders are currently pending?"
```
### Business operations
```
"Show me our business profile details."
"What bills are outstanding this month?"
"List all vendors we've paid in Q1."
"What are our current callback subscriptions?"
```
The PEX MCP Server exposes a comprehensive PEX toolset, including business profile/balance/admins, cards and spend rules, transactions and attachments, account details, spending rulesets, bills, vendors, payments, credit lines, invoices, groups, tokens, callbacks, and partner details.
***
## Read-only by design
The PEX MCP Server only exposes **GET** endpoints. The assistant can read your PEX account data — cards, transactions, business profile, spending rulesets, bills, payments, and so on — but it cannot move money, change settings, or take any other write action. This is enforced at the server level, not by client configuration.
If you need write capabilities, contact PEX support at `adminsupport@pexcard.com`.
***
## Troubleshooting
* Verify your `PEX_API_TOKEN` is correct and has not been revoked.
* Ensure `PEX_API_URL` is set to `https://coreapi.pexcard.com/v4`.
* Generate a new token from the dashboard if your current one has expired or been lost.
* **Claude Desktop / Cursor:** Remove and re-add the server in your config file, then fully restart the app.
* **Claude Code:** Run `/mcp`, select **pex**, and choose **Restart** to reconnect.
* Verify `npx` is available in your terminal by running `npx --version`.
* Check that you have an active internet connection to reach the PEX API.
* Ensure two-factor authentication (MFA) is enabled on your PEX account before trying to generate a token.
* If MFA verification fails, try again or contact your administrator.
* If you've lost a token, generate a new one from the dashboard — previously issued tokens remain active until you revoke them.
Both `PEX_API_URL` and `PEX_API_TOKEN` are required. Double-check that the `env` block in your client config is spelled exactly that way and that the values are not empty strings.
Make sure the MCP Server is configured under the right top-level key for your client (`mcpServers` for Claude, `github.copilot.chat.mcpServers` for GitHub Copilot in VS Code, or `servers` inside a project `.mcp.json`). Restart the client after editing the config file.
The server retries `502`, `503`, and `504` responses with exponential backoff and a 30-second timeout. Intermittent failures usually indicate a network issue between your machine and the PEX API. Check `https://status.pexcard.com` for ongoing incidents.
***
## Getting help
For the full source code and latest updates, visit the [PEX MCP Server GitHub repository](https://github.com/pexcard/mcp).
If you need assistance or have questions about the PEX MCP Server, contact the PEX support team at `adminsupport@pexcard.com`.
You may also be interested in [Connecting the PEX MCP Server to a Microsoft Copilot Studio agent](/developer-guide/connecting-pex-mcp-to-copilot-studio).