MCP - Vings External API

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.

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:

bunx @modelcontextprotocol/inspector

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

Authorization: Bearer <access-token>

Production smoke check (expect 401 without a token):

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). Shared AI connectors use known_mcp OAuth clients provisioned from the Vings server package; register redirect URIs per the OpenAI Apps SDK auth guide.

​Transport (OpenAPI)

​V1 tools (readonly)

​Test locally

​OAuth for ChatGPT and Claude

Transport (OpenAPI)

V1 tools (readonly)

Test locally

OAuth for ChatGPT and Claude