What agent access is#
Pyx has an MCP server built in. MCP, the Model Context Protocol, is the open standard AI tools use to reach data and take actions, and it is how you point an agent you already use at your own portfolio. Claude Code, Claude Desktop, Codex, and any other MCP client all work.
Pyx does not bundle a chatbot, and it never sends your portfolio to an AI provider itself. You choose the agent, the model, and the questions. Pyx's side of the conversation happens entirely on your machine, and access is off until you turn it on.
Once connected, an agent can answer questions that normally mean exporting spreadsheets: how concentrated am I in semiconductors across all accounts, what is my true time-weighted return this year versus SPY, what earnings are coming up in my watch tags, how does CVX rank against my Energy tag on leverage. It reads the same local database the app renders, including the fundamentals and filings the research modules show, so the answers match what you see on screen.
The five capabilities#
Agent access itself is off by default. Once you turn it on, five capability switches in Settings scope what a connected agent can reach. They start enabled, and you switch off what you do not want:
| Capability | What it allows |
|---|---|
| Portfolio read | The portfolio snapshot with allocation by any dimension, holdings with ledger and broker cost basis, transactions, time-weighted and money-weighted performance with risk metrics and a benchmark overlay, the audit log |
| Market research | Quotes, price history, symbol search, company profiles with estimates and ownership, earnings, a decade of financials with growth, margins, and multiples, peer comparison, the SEC filing index |
| Notes | Read your notes, save research documents linked to securities, accounts, tags, or the portfolio, delete |
| Tags | Create or update tags and their members in one call, delete |
| App control | Read where you are in the app, reorder customizable surfaces such as the Overview metrics and the Performance chip bar, and put a view, security, tag, or note on screen |
Twenty-one tools sit behind those switches. Each takes selectors, so get_financials returns statements, growth, margins, or multiples by the view you ask for, and compare_companies runs the Trading Multiples, Growth, Profitability, or Leverage template against an explicit ticker list, one of your tags, or a ticker's related securities. get_financials and list_filings read the fundamentals Pyx already synced from SEC EDGAR and Yahoo, so they work offline and do not count against the research rate budget. There is no switch that lets an agent modify holdings or transactions; no such tool exists.
Skills#
Pyx ships its own research workflows as agent skills, compiled into the app and versioned with it: company dossier, forensic filing review, bull and bear stress test, moat analysis, sector report, disruption scan, portfolio checkup, and earnings prep. Each one scripts which tools to call, in what order, and how to write the result back as a research document linked to the company or tag, then opens it in the app.
Connected agents see them as prompts, for example /pyx:company-dossier ticker=AAPL. For clients that keep skills on disk, Settings > AI Agents > Skills > Export skills writes one SKILL.md folder per skill to a directory you choose. When the app updates, the pane tells you the export is behind and a re-export refreshes it.
Turn it on#
- Open Settings > AI Agents.
- Turn on Enable access. An active Pyx license is required.
- Enable the capabilities you want the agent to have.
The Status row shows whether the local socket is listening and how many agent sessions are connected. Recent activity lists every tool call with its outcome and duration.
Connect an agent#
Pyx ships a small bridge binary inside the app bundle. Agents talk MCP to the bridge over stdio, and the bridge forwards to the running app over a local socket. The Settings pane shows the bridge path, copyable with a click.
For Claude Code, one command registers it:
claude mcp add pyx -- /Applications/Pyx.app/Contents/MacOS/pyx-mcp
For Claude Desktop and other clients, add the same bridge path as a stdio MCP server in the client's configuration. Pyx must be running for the connection to work; the bridge reaches the live app, not the database file.
The security model#
Agent access was designed to be boring to audit:
- Local only. The socket is a same-user Unix domain socket in your data directory. Nothing listens on TCP, so nothing is reachable from the network, and no cloud relay is involved.
- Portfolio data is read-only. No tool can insert, update, or delete holdings, transactions, accounts, prices, or lots. The database connection agents reach is opened read-only at the SQLite level, so even a bug in Pyx could not let an agent write portfolio data. Agents write exactly three things: notes, tags, and the visibility and order of dashboard widgets. Navigation changes what is on screen and nothing that is stored, and never steals focus from another app.
- Zero new network egress. Enabling agents adds no hosts to the network allowlist. Market research tools use the same Yahoo Finance endpoints the app already uses.
- No secrets cross the boundary. License keys, brokerage credentials, and encryption keys are not reachable by any tool.
- Account numbers are masked. Account identifiers cross as opaque aliases, and digit runs in account names are masked to the last four.
- Everything is on the record. Every tool call lands in the activity feed under Settings > AI Agents, and every session and every change an agent makes lands in the audit log, tagged as agent activity. Reads stay in the feed; writes reach the log. A research document an agent wrote carries a caption naming the client and date, derived from the audit log rather than stored on the note.
- Bounded by construction. Sessions are capped at four, network research calls are rate limited, navigation is limited to one move every two seconds, responses are size limited, and every tool call times out.
Approving individual tool calls is your agent client's job: Claude and its peers already prompt before running tools, so Pyx does not stack a second dialog on top.
What agents cannot do#
Stated plainly:
- No chart control. Agents cannot open workspaces, add indicators, or draw. A charts capability is planned for a future release.
- No attachments. Agents write note text and links; attaching files stays in the app.
- No filing bodies. Pyx serves the filing index and URLs; the agent fetches documents with its own tools.
- No trades, ever. Pyx itself is read-only at the brokerage, so there is nothing to reach.
- No access while disabled. Turning off Enable access closes the socket and ends every session.
Turn it off#
Flip Enable access off in Settings > AI Agents, or disable individual capabilities and keep the rest. The switch takes effect immediately. Uninstalling nothing, restarting nothing.
Worked examples#
The use cases page walks through prompts people actually run: biggest movers over a month, dividend growth by year, a tag of quantum computing names with an outlook note on each, dated legislation notes pinned to energy holdings, earnings prep notes, true returns against a benchmark, a company dossier saved as research, and a peer comparison against one of your tags, each with the tools the agent calls to answer.