# nessie-mcp-server

A standalone, read-only [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for accessing supported Capital One Nessie API resources. It communicates over standard input/output and is designed for Node.js 18 or later.

**Official Nessie site:** [https://prod.nessieisreal.com/](https://prod.nessieisreal.com/) is the official source for Nessie. It is distinct from the API request origin, `https://prod-api.nessieisreal.com`, used by this package.

> **Unofficial community project:** This package is not affiliated with, endorsed by, or sponsored by Capital One.

## Requirements

- Node.js 18 or later
- A Nessie API key

## Installation

Run the package directly with `npx`:

```sh
npx -y nessie-mcp-server
```

Or install it globally and use the package executable:

```sh
npm install --global nessie-mcp-server
nessie-mcp-server
```

For a project-local installation:

```sh
npm install nessie-mcp-server
npx nessie-mcp-server
```

## Configuration

Set `NESSIE_API_KEY` in the server process environment. The server reads and trims the value at each tool invocation and sends it only as the Nessie API `key` query parameter.

```sh
NESSIE_API_KEY=your_api_key_here npx -y nessie-mcp-server
```

On PowerShell:

```powershell
$env:NESSIE_API_KEY = "your_api_key_here"
npx -y nessie-mcp-server
```

Copy `.env.example` only when your process runner loads environment files; the server does not load `.env` files itself.

### MCP client configuration

`mcp.json.example` contains a complete example:

```json
{
  "mcpServers": {
    "nessie": {
      "command": "npx",
      "args": ["-y", "nessie-mcp-server"],
      "env": {
        "NESSIE_API_KEY": "YOUR_NESSIE_API_KEY"
      }
    }
  }
}
```

Replace the placeholder through your MCP client's secure environment configuration. Never pass an API key as a tool argument, commit it to source control, or include it in prompts or logs.

## Tools

The server exposes exactly these nine read-only tools. All identifier inputs are opaque strings; do not assume an ID format or length.

| Tool                      | Input                      | Behavior and limitations                                                                                                                                                                                                        |
| ------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `nessie_list_customers`   | `{}`                       | Lists customers available to the configured API key.                                                                                                                                                                            |
| `nessie_get_customer`     | `{ "customerId": string }` | Gets one customer by opaque customer ID.                                                                                                                                                                                        |
| `nessie_list_accounts`    | `{ "customerId": string }` | Lists accounts owned by one customer. Nessie account data provides no credit limit; credit utilization cannot be calculated from Nessie account data.                                                                           |
| `nessie_get_account`      | `{ "accountId": string }`  | Gets one account by opaque account ID. Nessie account data provides no credit limit; credit utilization cannot be calculated from Nessie account data.                                                                          |
| `nessie_get_transactions` | `{ "accountId": string }`  | Merges deposits and withdrawals into a newest-first feed with literal `deposit`/`withdrawal` tags. Nessie account data provides no credit limit; credit utilization cannot be calculated from Nessie account data.              |
| `nessie_list_deposits`    | `{ "accountId": string }`  | Lists deposits for one account. Nessie account data provides no credit limit; credit utilization cannot be calculated from Nessie account data.                                                                                 |
| `nessie_list_withdrawals` | `{ "accountId": string }`  | Lists withdrawals for one account. Nessie account data provides no credit limit; credit utilization cannot be calculated from Nessie account data.                                                                              |
| `nessie_list_bills`       | `{ "accountId": string }`  | Lists bills and recurring obligations for one account. Nessie account data provides no credit limit; credit utilization cannot be calculated from Nessie account data.                                                          |
| `nessie_list_loans`       | `{ "accountId": string }`  | Lists loans for one account. Each loan `credit_score` is a static on-file value, not a live credit-bureau feed. Nessie account data provides no credit limit; credit utilization cannot be calculated from Nessie account data. |

There are no date-range, pagination, status-filter, write, or API-key tool inputs.

## Resource status

| Resource or operation                 | Status   | Notes                                                                                   |
| ------------------------------------- | -------- | --------------------------------------------------------------------------------------- |
| Customers                             | Exposed  | List and individual read tools.                                                         |
| Accounts                              | Exposed  | Customer-scoped list and individual read tools; no global account-list tool.            |
| Deposits                              | Exposed  | Account-scoped read tool and part of the merged transaction feed.                       |
| Withdrawals                           | Exposed  | Account-scoped read tool and part of the merged transaction feed.                       |
| Bills                                 | Exposed  | Account-scoped read tool.                                                               |
| Loans                                 | Exposed  | Account-scoped read tool; credit scores are static values stored on loan records.       |
| Transfers                             | Excluded | No transfer tools or money-movement operations.                                         |
| Purchases                             | Excluded | Not part of the v1 transaction feed.                                                    |
| Merchants                             | Excluded | No merchant tools.                                                                      |
| ATMs                                  | Excluded | No ATM tools.                                                                           |
| Branches                              | Excluded | No branch tools.                                                                        |
| Enterprise resources                  | Excluded | No enterprise-wide tools.                                                               |
| Create, update, and delete operations | Excluded | The entire tool surface is read-only.                                                   |
| Global account listing                | Excluded | Accounts are discovered through a customer ID.                                          |
| Credit limits and credit utilization  | Excluded | Nessie account records provide no credit-limit field, so utilization cannot be derived. |

## API compatibility

The server uses the live-verified Nessie origin:

```text
https://prod-api.nessieisreal.com
```

Older examples may reference a different host. Resource IDs are URL-encoded and preserved as arbitrary strings, including UUIDs or other formats and lengths. The server performs a fresh asynchronous request for every read and does not expose write or money-movement endpoints.

## Security

- Keep `NESSIE_API_KEY` in environment or secret-manager configuration.
- Do not place real keys in `mcp.json.example`, `.env.example`, source files, issue reports, prompts, or logs.
- Restrict access to MCP client configuration files that contain injected secrets.
- Tool errors are designed to preserve actionable status/path information without returning credentials or upstream response bodies.
- Review the Nessie service's terms and data-handling requirements before exposing financial data to an MCP client.

## License

MIT. See [LICENSE](LICENSE).