# FinHub API
> FinHub is a SaaS billing, subscription management, and usage tracking platform by FinHero.

## API Access
- Authentication: POST /api/v1/login with {"email", "password"} returns a JWT bearer token (24h expiry)
- REST API docs (OpenAPI 3.1): /api/v1/openapi.json
- Interactive docs (Swagger UI): /api/docs/finhub
- Developer Portal: /api/docs

## MCP Server
- Endpoint: POST /api/v1/mcp
- Transport: Streamable HTTP (JSON-RPC 2.0)
- Auth: OAuth 2.1 Authorization Code + PKCE
- Discovery: /.well-known/mcp.json
- OAuth Metadata: /.well-known/oauth-authorization-server
- Resource Metadata: /.well-known/oauth-protected-resource

## Available MCP Tools (Company Users)
- list_subscriptions, get_subscription
- list_billing_records
- get_credit_balance (credit-based subscriptions)
- search_usage (multi-dimensional usage search with aggregation)
- list_clients, create_client
- list_products, create_product
- list_billing_models
- create_subscription
- schedule_billing_model_change (change billing model with effective date, supports retroactive)
- list_billing_model_changes (view scheduled/applied/cancelled changes)
- cancel_billing_model_change (cancel a scheduled change)
- list_emandate_products, create_emandate_product
- list_emandate_mandates, create_emandate_mandate (auto-creates customer account)
- get_emandate_mandate (with payment history)
- list_emandate_customers
- list_emandate_banks

## Available MCP Tools (Client Users)
- list_subscriptions, get_subscription
- list_billing_records
- get_credit_balance
- list_forms, get_form, create_form, delete_form, validate_form

## Connecting with MCP Clients
Add the remote MCP server URL to your client:
URL: https://finhub.finhero.asia/api/v1/mcp
Auth will open in your browser automatically via OAuth 2.1.