# Nine — AI Financial Assistant & Workspace Platform

> Nine (ninehoang.com) is a platform for portfolio showcase, shared group funds, event budgeting, and automated financial tracking.

Nine provides a native Model Context Protocol (MCP) server (`nine`) and a programmatic REST API that empowers AI agents (Google Gemini, Anthropic Claude, ChatGPT, Cursor) to manage workspace finances and collaborate seamlessly.

## Core AI Discovery & Protocols

- [MCP Server Endpoint](https://ninehoang.com/mcp): Native Model Context Protocol (SSE/HTTP) server named `nine` with tools for recording expenses, inspecting group funds, logging contributions, and querying directories.
- [REST API](https://ninehoang.com/api/v1): Authenticate with a workspace token as a plain bearer credential (`Authorization: Bearer nh_ws_...`). Nothing to refresh — the server performs the short-lived JWT exchange on every request, so one static credential is all a client stores. The token itself can still be revoked or reach its expiry date, and either cuts access on the next statement.
- [OpenAPI 3.0 Specification](https://ninehoang.com/openapi.json): Standard REST API definitions for Custom GPTs, Gemini Actions, and SDK clients. Describes the endpoint above.
- [Full AI Reference & Specs](https://ninehoang.com/llms-full.txt): Comprehensive database schemas, RLS isolation rules, and integration guides.
- [Developer Portal](https://ninehoang.com/developers): Interactive documentation and quickstart guides.

## Core Capabilities for AI Agents

1. **Expense Recording**: Logging of daily outlays with a category, a payment method and an ISO timestamp. Category and method are REQUIRED and are slugs (`food-drinks`, `bank-transfer`) — each tool lists the values its workspace accepts, so an agent picks from that list rather than inventing one.
2. **Group Funds & Budgets**: Lifecycle status, per-member contribution schedules (an amount, a period and a due day), and transparent group ledgers (e.g. travel funds, sports clubs). A fund has no single target figure — what it expects to collect comes from its contribution rule, and what it holds is the sum of its transactions.
3. **Fund Contributions & Payouts**: Income logging and shared expense payouts. Amounts are SIGNED and in VND — there is no currency field and no conversion. The sign follows the category: `fund-income` and `fine` are positive, every other category including `refund` is negative.
4. **Workspace Directory**: Secure member search and contact address book.

## Scoping Rules an Agent Should Know

- Every request is confined to the token's own workspace by PostgreSQL Row Level Security. A token never sees another workspace's rows.
- A workspace can uninstall an app (Inbox, Contacts, Expenses, Funds, Portfolio). An uninstalled app's tables return an empty array rather than an error. Nothing is deleted, and reinstalling restores every record.
- Revoking a token, letting it expire, or switching the workspace API off cuts access on the next statement.
- Every create, update and delete an agent performs is recorded in the workspace's activity history, attributed to the token by name and to the member who minted it.