> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vin.gs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

> JSON-RPC transport, tools, schemas, and local testing with MCP Inspector.

The Vings **Model Context Protocol** server is exposed at:

```
POST https://external.vin.gs/api/mcp
```

Send JSON-RPC 2.0 requests with the same bearer token as REST. See [Authentication](/external/docs/authentication).

## Transport (OpenAPI)

OpenAPI documents the HTTP transport, not each tool’s parameters:

| Method                      | Role                                                      |
| --------------------------- | --------------------------------------------------------- |
| `initialize`                | Session setup                                             |
| `notifications/initialized` | Client notification (HTTP 202, no body)                   |
| `tools/list`                | List readonly tools with `inputSchema` and `outputSchema` |
| `tools/call`                | Invoke a tool                                             |

`GET /api/mcp` returns **405** — use POST with a JSON-RPC body.

Per-tool **input** and **output** JSON Schemas are returned only from `tools/list` (`outputSchema` uses JSON Schema draft 2020-12 for validating `structuredContent` from `tools/call`). Tool descriptors also include OAuth `securitySchemes` for ChatGPT linking. They are intentionally not duplicated in OpenAPI.

## V1 tools (readonly)

| Tool                         | Purpose                |
| ---------------------------- | ---------------------- |
| `search_transactions`        | Transaction search     |
| `get_cashflow_summary`       | Cashflow summary       |
| `get_spending_by_category`   | Spending by category   |
| `get_top_merchants`          | Top merchants          |
| `detect_recurring_payments`  | Recurring payments     |
| `get_budget_summary`         | Budget summary         |
| `list_budget_categories`     | Budget categories      |
| `get_connected_banks_status` | Bank connection status |
| `get_portfolio_snapshot`     | Portfolio snapshot     |
| `get_portfolio_history`      | Portfolio history      |
| `get_preferences`            | User preferences       |

Scopes on the bearer token must allow the data each tool reads.

## Test locally

From `packages/external`, run the API (for example `bun run dev`), then use [MCP Inspector](https://github.com/modelcontextprotocol/inspector):

```bash theme={null}
bunx @modelcontextprotocol/inspector
```

Point the server URL at `http://localhost:<port>/api/mcp` and set:

```http theme={null}
Authorization: Bearer <access-token>
```

Production smoke check (expect **401** without a token):

```bash theme={null}
curl -sS -o /dev/null -w "%{http_code}\n" -X POST https://external.vin.gs/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'
```

## OAuth for ChatGPT and Claude

Discovery URLs:

* `GET /.well-known/oauth-protected-resource`
* `GET /api/.well-known/oauth-protected-resource/mcp`
* `GET /.well-known/oauth-authorization-server` (includes `offline_access` for refresh tokens)
* `GET /.well-known/openid-configuration`

ChatGPT app domain verification (hostname root, not under `/api`):

* `GET /.well-known/openai-apps-challenge`

Authorize requests go through `GET /api/oauth/authorize` on the external host, which forwards to Supabase after removing `offline_access`. Token exchange and refresh use Supabase's `token_endpoint` directly.

After updating OAuth discovery, delete and recreate the ChatGPT connector so cached metadata is refreshed ([OpenAI connector OAuth guidance](https://help.openai.com/en/articles/12584461-developer-mode-apps-and-full-mcp-connectors-in-chatgpt-beta)).

Shared AI connectors use `known_mcp` OAuth clients provisioned from the Vings server package; register redirect URIs per the [OpenAI Apps SDK auth guide](https://developers.openai.com/apps-sdk/build/auth).