PopaDex MCP (Distribution v0)

This folder contains the listing-ready contract for the first PopaDex MCP release.

Goal

Expose deterministic, read-only finance tools so marketplace reviewers can validate utility quickly.

Proposed v1 Tools

Initial launch scope was the five core tools listed below. Runtime has expanded and the canonical set is now the "Current implemented tools" section.

• get_net_worth_summary
• get_account_allocation
• run_salary_comparison
• run_tax_estimate
• run_retirement_projection

Implemented Runtime Endpoints

• GET /api/mcp/tools
• POST /api/mcp/execute
• POST /api/mcp/signup
• POST /api/mcp/subscribe

Current implemented tools:

• get_net_worth_summary
• get_account_allocation
• run_salary_comparison
• run_tax_estimate
• run_retirement_projection
• compare_disposable_income
• build_budget_sankey
• get_portfolio_total_value
• get_portfolio_performance
• get_portfolio_historical_timeline
• export_portfolio_csv

Current implemented acquisition flow:

• POST /api/mcp/signup creates API channel users with signup_source=api_mcp
• POST /api/mcp/signup with plan=premium returns a Stripe checkout session via Pay gem
• POST /api/mcp/subscribe upgrades existing API users to premium checkout
• Admin notification includes Channel: api_mcp for support visibility

Example Request

curl -X POST https://app.popadex.com/api/mcp/execute \
	-H "Authorization: Bearer <MCP_API_KEY>" \
	-H "Content-Type: application/json" \
	-d '{
		"tool":"get_net_worth_summary",
		"input":{"from":"2026-01-01","to":"2026-03-31","currency":"EUR"}
	}'

Why read-only first

• Faster marketplace approval.
• Lower security risk.
• Easier to test and reason about outputs.

Note: acquisition endpoints are write operations used for user onboarding and premium checkout handoff.

Auth Model (v1)

• API key per workspace/user.
• Scope-limited to read-only finance endpoints.
• Rate limit per key with dedicated MCP endpoint throttles.
• API key sources: Rails credentials[:mcp][:api_key] or POPADEX_MCP_API_KEY.

Security Controls

• Input allowlisting: MCP input rejects unknown fields and non-object payloads.
• Request size limit: oversized MCP execute payloads return 413 Payload Too Large.
• CORS hardening: MCP endpoints are configured for non-credentialed cross-origin access.
• API key hardening: new keys use identifier + adaptive secret hashing for authentication, with legacy digest compatibility.
• Artifact parity gates: tests enforce runtime catalog parity with MCP schema/examples and OpenClaw declarations.

Files

• tools.schema.json: canonical tool list and I/O schema.
• examples/request_examples.json: example requests and expected shape.

Runtime Catalog Source

• Runtime tool listing and dispatch are driven by Mcp::ToolsRegistry in app/services/mcp/tools_registry.rb.
• Tool execution is routed through Mcp::ToolDispatcher in app/services/mcp/tool_dispatcher.rb.
• Access enforcement reads per-tool scope and entitlement flags from the same registry, reducing drift between docs and runtime.

Validation Checklist

1. Every tool has explicit required fields.
2. Error responses include stable machine-readable codes.
3. Output includes units/currency and date context.
4. No tool mutates user data.