Entwickler & API

• Deine Backtest-Sets und Portfolios auflisten und im Detail auslesen
• Backtests (Simulationen) starten und Ergebnisse abrufen oder vergleichen
• Öffentliche Community-Backtests und aktuelle Wechselkurse abfragen
• Dein Konto und deine Abo-Limits abfragen (whoami)
• Backtest-Sets anlegen, Portfolios aus Ergebnissen speichern, Monte-Carlo-Simulationen rechnen und Vorlagen, Listen und Ordner pflegen
• Deine Wertpapiere auflisten, Kurse aus Dateien als löschbare Pakete ergänzen und Stammdaten (z. B. TER) von Hand setzen
• Löschen nur mit dem Recht „Löschen“ (delete), nur als Inhaber oder Account-Admin und nur, wenn es unter Einstellungen → API-Schlüssel für den Account eingeschaltet ist — sonst sieht der Assistent die Lösch-Werkzeuge gar nicht

Jeder Schlüssel ist an dein Konto gebunden und handelt in deinem Namen. Verfügbare Scopes: Lesen (read), Simulationen ausführen (run_simulation), Wertpapiere pflegen (watchlist:write — Kurse hochladen, Stammdaten setzen) und Löschen (delete — nur von Inhabern und Account-Admins vergeben, siehe „Löschen“). Backtests, Monte-Carlo-Simulationen und Aktualisierungen verbrauchen Credits aus deinem Guthaben.

Erstelle einen persönlichen API-Schlüssel in deinen Konto-Einstellungen unter „API-Schlüssel“. Der Schlüssel beginnt mit sk_ppf_ und wird genau einmal angezeigt — kopiere ihn sofort.

Füge in claude.ai unter Einstellungen → Connectors einen benutzerdefinierten Connector mit dieser MCP-URL hinzu. Die OAuth-Felder lässt du leer — die Registrierung läuft automatisch (Dynamic Client Registration). Beim ersten Verbinden bestätigst du den Zugriff auf dein Konto.

https://www.paperball.finance/mcp

Kein API-Schlüssel nötig — die Verbindung wird über OAuth 2.1 mit PKCE hergestellt und erscheint danach unter „Verbundene Apps“.

Trage folgenden Block in deine claude_desktop_config.json ein und ersetze sk_ppf_… durch deinen Schlüssel. mcp-remote überbrückt den lokalen stdio-Transport zum 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_..." }
    }
  }
}

Jeder MCP-fähige HTTP-Client spricht den Endpoint direkt an — per Streamable HTTP mit deinem Schlüssel im 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

Löschende Tools erscheinen in tools/list nur, wenn drei Dinge gelten: Der Schlüssel trägt das Recht „delete“, er gehört einem Inhaber oder Account-Admin, und „Löschen über KI-Assistenten und API“ ist unter Einstellungen → API-Schlüssel eingeschaltet (Vorgabe: aus). Gelöscht wird nur, was noch nicht im Einsatz ist.

Bestehende Schlüssel und Verbindungen haben das Recht „Löschen“ nicht. Lege dafür einen neuen Schlüssel mit „Löschen erlauben“ an oder verbinde den Assistenten neu und bestätige das Löschen.

Die Werkzeuge liefern jetzt dieselben Zahlen wie die Seiten der App. Dafür haben sich einige Felder und Vorgaben geändert — passe gespeicherte Aufrufe und Skripte an:

• run_monte_carlo, run_monte_carlo_mix, run_monte_carlo_community: Die Felder heißen wie in den gespeicherten Monte-Carlo-Einstellungen (horizon_years → horizont_jahre, start_capital → startkapital, block_months → block_monate, tax → steuer); neu ist alter_heute. Unbekannte Felder werden abgelehnt statt übergangen.
• get_exchange_rates: Die Kurse stehen jetzt in der Richtung der App, 1 EUR = X Fremdwährung — vorher war es der Kehrwert.
• get_top_portfolios_leaderboard: dieselben Ranglisten wie die Seite Community-Backtests (sharpe_ratio, sortino_ratio, calmar_ratio, sterling_ratio, martin_ratio, recovery_ratio, Vorgabe sharpe_ratio); cagr, ulcer und max_drawdown entfallen.
• list_community_portfolios: ohne Angaben eine Seite der Suche wie auf der Monte-Carlo-Seite (10 Einträge, längste Kursgeschichte zuerst) mit total — statt bis zu 200 nach Sharpe.
• get_table_detail: weight_pct und distribution_type entfallen (sie waren immer leer); dazu kommen die Felder der Seite des Backtest-Sets.
• list_my_favorite_portfolios: neu ist metrics mit den Kennzahlen des eigenen Backtests, wie Meine Portfolios sie zeigt; leaderboard_metrics steht getrennt daneben.
• run_simulation: Vorgaben wie das Formular der Seite (Mindestanzahl 2, Schrittweite nach deinem Tarif); eine Vorlage gilt für jedes Feld, das du nicht übergibst.
• list_watchlist, compare_watchlist_securities, get_security_price_history: dieselben Wertpapiere wie die Watchlist (auch Testdaten und geteilte Ordner); das Zeitfenster ist ohne Angabe das deiner Kachel.

ulcer_index steht jetzt in Prozentpunkten wie max_drawdown (7,65 statt 0,0765). sortino_ratio mittelt die quadrierten Verluste über alle Tage statt nur über die Verlusttage, wie es üblich ist; der Wert fällt dadurch etwa anderthalbmal so hoch aus. Das gilt für jedes Werkzeug, das diese Kennzahlen liefert, und für gespeicherte Backtests und Portfolios, sobald sie neu gerechnet sind.

Für OAuth-Clients werden die Metadaten nach RFC 8414 / RFC 9728 an den Standard-Pfaden bereitgestellt:

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

Die programmatische Fläche von Paperball ist MCP-first. Ein maschinell lesbares OpenAPI-Dokument der öffentlichen REST-Endpunkte (nur Whitelist, ohne interne Routen) findest du hier: openapi.json