# CardPilot Remote MCP Server
This is a remote [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server for CardPilot. It exposes tools to fetch and analyze credit card data.
## Server URL
**Public URL**: `https://mcp.cardpilot.ca/sse`
> **Note**: This server uses a custom domain to ensure compatibility with OpenAI Agent Builder.
## Available Tools
### 1. `get-cards`
Fetches a list of credit cards with detailed metadata, suitable for ranking and comparison.
**Input parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `sort` | `string` (enum) | Sort criteria: `recommended`, `welcome_offer`, `interest_rate`, `annual_fee`, `net_value` |
| `direction` | `string` (enum) | Sort direction: `asc`, `desc` |
| `ids` | `string` | Comma-separated list of card IDs (e.g., `card-a,card-b`) |
| `bank` | `string` | Filter by bank name (e.g., "TD", "RBC") |
| `category` | `string` | Filter by category (e.g., "travel", "cash back") |
| `noFee` | `boolean` | Set to `true` to filter for no-annual-fee cards |
| `limit` | `number` | Maximum number of cards to return (default: 5) |
| `persona` | `string` (enum) | Target persona for tailored ranking: `average`, `student`, `newcomer`, `premium` |
**Output structure:**
```json
{
"cards": [
{
"cardId": "string",
"name": "string",
"bank": "string",
"annualFee": number,
"score": number,
"details": { "rewards": number, "perks": number, "fees": number, ... }
}
],
"meta": { "total": number, "sort": "string", "direction": "string" }
}
```
### 2. `get-guides`
Fetches a list of educational guide metadata. This tool is optimized for chatbots to provide links to full articles.
**Input parameters:** None
**Output structure:**
```json
{
"guides": [
{
"slug": "string",
"title": "string",
"intro": "string",
"icon": "string (emoji)",
"url": "string"
}
]
}
```
## Agent System Prompt
If you are using this MCP server with an LLM Agent (like OpenAI Custom GPT), add the following to your System Instructions:
```text
You are an expert credit card advisor powered by CardPilot data.
1. **Card Recommendations**:
- ALWAYS use the `get-cards` tool to fetch real-time data before making recommendations.
- Set `limit=5` by default to ensure concise recommendations.
- If the user specifies or asks for a specific persona (e.g., student, newcomer), set the `persona` parameter (e.g., `persona="student"`).
- Use the `sort` parameter to align with user priorities (e.g., `sort="annual_fee"` for cheap cards).
- Use filters like `bank="TD"` or `category="travel"` to narrow down results.
- For "no fee" requests, explicitly set `noFee=true`.
- When presenting cards, list the Name, Annual Fee, Welcome Bonus, and a brief "Why it fits" explanation.
- Link the card name to the `applyUrl` or CardPilot detail page if available.
2. **Educational Content**:
- If a user asks general questions (e.g., "Cash back vs Points"), use `get-guides` to see if there is a relevant article.
- Provide the answer based on the guide's `intro` and encourage the user to read the full guide by providing the `url`.
3. **General Rules**:
- Do not make up card details. If data is missing, state that.
- Be concise and helpful.
```
## How to Use
### OpenAI Agent Builder
1. Create a new Agent.
2. Under **Actions**, click **Add Action**.
3. Select "Add from URL".
4. Enter: `https://mcp.cardpilot.ca/sse`
5. It should load the `get-cards` tool immediately.
### Cloudflare AI Playground
1. Go to [https://playground.ai.cloudflare.com/](https://playground.ai.cloudflare.com/)
2. Enter the server URL: `https://mcp.cardpilot.ca/sse`
3. Click **Connect**.
### Claude Desktop
Add the following to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"cardpilot": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://mcp.cardpilot.ca/sse"
]
}
}
}
```
## Troubleshooting
### OpenAI 424 Error ("Unable to load tools")
If you see this error, ensure you are using the **Custom Domain** URL (`mcp.cardpilot.ca`).
OpenAI blocks generic `.workers.dev` domains for MCP servers.
### Local Development
To test locally:
1. Install dependencies:
```bash
npm install
```
2. Start local server:
```bash
npm start
```
(Runs on port 8787)
3. **Expose via Ngrok** (Required for OpenAI testing):
```bash
ngrok http 8787
```
Use the Ngrok URL (e.g., `https://xxxx.ngrok-free.app/sse`) in Agent Builder.
## Deployment
Deploy to Cloudflare Workers:
```bash
npm run deploy
```
The server will be live at `https://mcp.cardpilot.ca/sse`.
