Developers & API

Connect Paperball to AI assistants and your own tools. Programmatic access runs through the MCP server — usable via OAuth (e.g. claude.ai) or with a personal API key.

What you can do with it

List your backtest sets and portfolios and read them in detail
Start backtests (simulations) and retrieve or compare results
Query public Community-Backtests and current exchange rates
Query your account and subscription limits (whoami)
Create backtest sets, save portfolios from results, run Monte Carlo simulations and manage templates, lists and folders
List your securities, add prices from files as deletable packages and set master data (e.g. TER) manually
Delete only with the “Delete” permission (delete), only as an owner or account admin, and only if it is switched on for the account under Settings → API keys — otherwise the assistant does not even see the delete tools

Every key is bound to your account and acts on your behalf. Available scopes: read, run simulations (run_simulation), maintain securities (watchlist:write — upload prices, set master data) and delete (delete — granted only by owners and account admins, see “Deleting”). Backtests, Monte Carlo simulations and updates consume credits from your balance.

Quickstart: create a key

Create a personal API key in your account settings under “API keys”. The key starts with sk_ppf_ and is shown exactly once — copy it right away.

Go to key management

Connect claude.ai (OAuth)

In claude.ai, go to Settings → Connectors and add a custom connector with this MCP URL. Leave the OAuth fields empty — registration happens automatically (Dynamic Client Registration). On first connect you confirm access to your account.

https://www.paperball.finance/mcp

No API key needed — the connection is established via OAuth 2.1 with PKCE and then appears under “Connected apps”.

Connect Claude Desktop (key)

Add the following block to your claude_desktop_config.json and replace sk_ppf_… with your key. mcp-remote bridges the local stdio transport to the HTTP MCP server.

{
  "mcpServers": {
    "paperball": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://www.paperball.finance/mcp",
               "--header", "Authorization: Bearer ${PAPERBALL_API_KEY}"],
      "env": { "PAPERBALL_API_KEY": "sk_ppf_..." }
    }
  }
}

n8n, Make & your own scripts

Any MCP-capable HTTP client can talk to the endpoint directly — via Streamable HTTP with your key in the Authorization header.

# n8n / Make / eigener MCP-Client (Streamable HTTP, JSON-RPC 2.0)
MCP-Endpoint:  https://www.paperball.finance/mcp
Auth:          Header  ->  Authorization: Bearer sk_ppf_...
Tools:         tools/list zeigt, was dein Schlüssel darf (Scope).
Backtest-Sets: list_my_tables · get_table_detail · create_table
               add_to_table · create_table_from_result
               create_table_from_portfolio_list · rename_table · copy_table
               set_table_client_tag · update_table_security
               link_table_securities_to_funds · validate_table
               get_table_data_status · set_table_distribution
Backtest:      run_simulation · wait_for_simulation · cancel_simulation
               list_recent_simulations · get_simulation_result
               rename_simulation_result · get_result_wealth
               filter_simulation_portfolios · compare_simulations
Vorlagen:      list_simulation_presets · create_simulation_preset
               update_simulation_preset · list_current_portfolio_templates
               create_current_portfolio_template
               update_current_portfolio_template · list_withdrawal_templates
               create_withdrawal_template · update_withdrawal_template
Portfolios:    list_portfolio_lists · create_portfolio_list
               update_portfolio_list · list_my_favorite_portfolios
               save_portfolio_from_result · update_saved_portfolio
               get_saved_portfolio_price_start · start_saved_portfolio_earlier
               get_saved_portfolio_wealth
               get_portfolio_metrics_over_time · set_portfolio_list_update
               refresh_saved_portfolios
Monte Carlo:   run_monte_carlo · run_monte_carlo_mix
               run_monte_carlo_community · get_monte_carlo_result
               list_monte_carlo_results · rename_monte_carlo_run
               check_monte_carlo_history · list_monte_carlo_building_blocks
               list_monte_carlo_securities · list_monte_carlo_mix_templates
               create_monte_carlo_mix_template
               update_monte_carlo_mix_template
               add_monte_carlo_allocation_reference
               list_monte_carlo_allocation_folders
               create_monte_carlo_allocation_folder
               update_monte_carlo_allocation_folder
               list_monte_carlo_settings · create_monte_carlo_settings
               update_monte_carlo_settings · list_saved_monte_carlo
               save_monte_carlo_result · create_saved_monte_carlo_folder
               update_saved_monte_carlo_folder · update_saved_monte_carlo
               list_community_portfolios
Altersvorsorge: get_av_depot_grant
Wertpapiere:   list_watchlist · add_securities · get_add_securities_status
               refresh_watchlist · get_watchlist_refresh_status
               get_watchlist_metrics_over_time · get_watchlist_correlation
               compare_watchlist_securities · get_security_crisis_behaviour
               get_security_price_history · get_security_fundamentals
               get_security_master_data · set_security_master_data
               get_price_sources · upload_prices
               list_benchmarks · set_security_benchmark
               set_watchlist_item_note · list_watchlist_folders
               create_watchlist_folder · update_watchlist_folder
               add_to_watchlist_folder · remove_from_watchlist_folder
               set_watchlist_folder_update · set_watchlist_folder_email
               start_portfolio_test · get_portfolio_test_result
               save_portfolio_test_as_portfolio
Markt, Konto:  get_top_portfolios_leaderboard · get_exchange_rates
               whoami · get_my_subscription_limits · get_credits
Löschen:       nur mit Scope delete — siehe Abschnitt „Löschen“
               delete_table · delete_table_security
               delete_table_uploaded_prices · delete_table_distribution
               delete_simulation_result · delete_saved_portfolio
               delete_portfolio_list · delete_simulation_preset
               delete_current_portfolio_template · delete_withdrawal_template
               delete_monte_carlo_run · delete_monte_carlo_mix_template
               delete_saved_monte_carlo · delete_saved_monte_carlo_folder
               delete_monte_carlo_settings
               delete_monte_carlo_allocation_folder
               delete_watchlist_folder · remove_from_watchlist
               delete_price_upload

Deleting

Deleting tools appear in tools/list only when three things hold: the key carries the “delete” permission, it belongs to an owner or account admin, and “Deleting via AI assistants and the API” is switched on under Settings → API keys (default: off). Only what is not in use yet can be deleted.

Existing keys and connections do not have the “Delete” permission. Create a new key with “Allow deleting” or reconnect the assistant and confirm deleting.

Changed tools (2026-10-28)

The tools now return the same figures as the app's pages. To get there, some fields and defaults changed — update saved calls and scripts:

run_monte_carlo, run_monte_carlo_mix, run_monte_carlo_community: the fields have the names of the saved Monte Carlo settings (horizon_years → horizont_jahre, start_capital → startkapital, block_months → block_monate, tax → steuer); alter_heute is new. Unknown fields are rejected instead of ignored.
get_exchange_rates: rates now follow the app's direction, 1 EUR = X foreign currency — before, it was the inverse.
get_top_portfolios_leaderboard: the same rankings as the Community backtests page (sharpe_ratio, sortino_ratio, calmar_ratio, sterling_ratio, martin_ratio, recovery_ratio, default sharpe_ratio); cagr, ulcer and max_drawdown are gone.
list_community_portfolios: without parameters, one page of the search as on the Monte Carlo page (10 entries, longest price history first) with total — instead of up to 200 by Sharpe.
get_table_detail: weight_pct and distribution_type are gone (they were always empty); the fields of the backtest set page are added.
list_my_favorite_portfolios: new metrics field with the figures of the portfolio's own backtest, as My portfolios shows them; leaderboard_metrics stays separate.
run_simulation: defaults as on the page's form (minimum 2 securities, step size from your plan); a preset applies to every field you don't pass.
list_watchlist, compare_watchlist_securities, get_security_price_history: the same securities as the watchlist (including test data and shared folders); without a window, the one of your tile applies.

Changed metrics (2026-10-30)

ulcer_index is now given in percentage points, like max_drawdown (7.65 instead of 0.0765). sortino_ratio averages the squared losses over all days instead of only the losing days, as is standard; this makes the value roughly one and a half times as high. This applies to every tool that returns these metrics, and to saved backtests and portfolios once they have been recalculated.

OAuth discovery

For OAuth clients, the metadata is provided at the standard paths per RFC 8414 / RFC 9728:

https://www.paperball.finance/.well-known/oauth-authorization-server
https://www.paperball.finance/.well-known/oauth-protected-resource

OpenAPI schema

Paperball's programmatic surface is MCP-first. A machine-readable OpenAPI document of the public REST endpoints (whitelist only, no internal routes) is available here: openapi.json