MCP Docs

Connect your AI assistant with MCP

Manage connected apps: Open API & MCP / Connected apps to review authorized accounts, permissions, and day/general journal access. Choose Disconnect and confirm to revoke an app’s authorization across its sessions. This blocks future access and token refresh without deleting trades, notes, or tags; an in-progress request may finish. Revoked connections remain visible until you authorize that app again. Disconnecting here does not uninstall the app in your MCP client.

Connect through TradesViz sign-in. Use the URL below in a supported MCP client, then choose which accounts and permissions to approve.

MCP lets a compatible agent read, import, edit, split, merge and delete journal data using the permissions you approve. Notes and tags have their own read, add/edit and delete permissions. No local installation or pasted REST API key is required.

1. Add TradesViz to your agent

Use a supported client with remote MCP over Streamable HTTP and browser-based OAuth. If your client cannot connect, contact TradesViz support with its name and the error message, never your credentials.

1. Open the agent's integrations or MCP settings and choose to add a remote/custom MCP server. Menu names vary by client.
2. Name the connection TradesViz and use the connection settings below. Do not enter a command to run locally.
3. Choose Connect or Authorize to begin browser sign-in. Do not put a REST key in a bearer-token field or paste it into a chat.

2. Sign in and approve access

1. Sign in to your TradesViz account with current Pro or Platinum access. MCP must also be available for your account.
2. Review the client, requested permissions, and trading accounts. Approve only the accounts and read or write actions you want to allow.
3. Return to the agent after authorization. trades.read allows the core read tools. If you also approve offline_access, the client can use rotating refresh tokens to stay connected without repeated sign-in.

New accounts are not added automatically. Read permission does not grant writes. To import executions or change notes/tags, check the write permissions below before approving.

3. Test the connection

Ask the agent:

List my authorized TradesViz accounts. Ask me which account to use, then show its latest five trades.

The agent should call list_accounts, then list_trades with the returned public account ID and page_size=5. It should not ask for your internal account ID, password, or API key in chat.

Check the result against the same account in your journal. Only authorize an agent you trust: the returned journal data is shared with that client and its model provider. Journal management tools need their own permissions and never place broker orders.

MCP write permissions

Write tools appear only when they are available for your account and your client has requested permissions that you approved. Existing read-only connections do not gain write scopes automatically. Reauthorize your connection and review the consent screen; the client must request the write permissions you need alongside trades.read. Never paste an Account Secret into an agent chat to bypass OAuth.

For the combined notes-and-tags read tool, approve both notes.write and tags.write. If these permissions are missing from the consent screen, check that the client requests them or contact TradesViz support. Creating a REST read key will not add them.

Keep the same intent/key/fill IDs on uncertain results. An expired intent can recover an already-admitted operation but cannot admit new facts; otherwise WRITE_INTENT_EXPIRED requires preparing again with the same facts and key. Do not regenerate identity to overcome authorization, validation or conflict errors. MCP and REST imports use separate source identities; sending the same fills through both can create duplicates.

Prepare/annotation results are limited to 48 KiB and tool results to 50 KiB; use small operations. QUERY_TOO_BROAD, NOT_AUTHORIZED, IDEMPOTENCY_CONFLICT, BUSY and UNAVAILABLE require resolving the reported problem, not inventing a fresh request.

Reconnect, revoke, and troubleshoot

Disconnect an app under Connected apps to revoke its authorization, or use the client's OAuth revocation action when available. Removing a connection from a client's list may not revoke its tokens. Revoking a dashboard REST key does not revoke a separate MCP OAuth grant.

MCP tools and the tool catalog share the same user request, pagination, response-data and concurrency budgets as REST. Token refreshes and additional connections do not reset them. A tool can return RATE_LIMITED with retry_after_seconds; wait at least that long before retrying. Catalog errors include a retry interval in their message. HTTP-level limits use 429 and Retry-After. After an uncertain write, keep the original intent and idempotency key because the change may already have committed.

Your subscription, account access, and approved permissions are checked on each tool operation, including retries.

Notes and tags

Notes can belong to a trade, a journal day, or your general journal. Tags can be attached to trades and days. Use the corresponding read, add/edit or delete permission for each operation. These operations do not import executions or place broker orders.

MCP uses notes.read/tags.read for reading and notes.write/tags.write for creating or editing. Each write permission also permits reading that type of annotation, but not deletion. Deleting a note requires notes.delete; removing tag attachments requires tags.delete. Trade access is limited to the accounts you authorize. Day notes, day tags and general notes are user-wide: opt in to Optional: day and general journal during authorization. Existing connections do not gain permissions automatically; reconnect and review the request.

REST accepts Authorization: Bearer API_KEY with the same notes/tag scopes and account/personal consent as MCP. For mutations, send a stable Idempotency-Key. Reads use a default page size of 25 (maximum 50); pass next_cursor back as cursor without changing its target.

Deletion requires its own scope. Scoped API keys and OAuth tokens may delete only with notes.delete or tags.delete as applicable. Account Secret authentication never permits deletion. Bearer requests do not need client-instance or connector headers. Legacy Basic clients still require X-TradesViz-Connector: python and a stable UUID in X-TradesViz-Client-Instance. Never paste credentials into chat.

Every request uses schema_version: 2 and one target: {"type":"trade","account_id":"PUBLIC_UUID","trade_ref":"OPAQUE_REF"}, {"type":"day","date":"2026-09-15"}, or {"type":"misc"} (notes only). Dates identify journal days, not execution timestamps. Use references returned by reads; do not guess IDs.

{
  "schema_version": 2,
  "target": {"type": "misc"},
  "title": "Weekly review",
  "text": "Follow the plan and review risk before entry.",
  "edit_existing": false
}

edit_existing defaults to false, which creates a new note. To edit, send true and the exact note_ref returned by read_notes for that target. A missing note returns an error; it never silently creates a replacement. Notes are plain text on writes; returned content_html may contain legacy HTML and must be sanitized before display. Other notes, favorites, categories and tag groups are not replaced.

For tags, send operation: "add" or "remove" with tags: ["Reviewed", "Risk checked"]. For deletion, send only the common fields and note_ref. Keep the same body, client identity and key if a mutation needs retrying. Notes nested inside another note and general-note tag attachments are not supported.

Search, edit, split, merge and delete

REST and MCP share these journal operations and permission checks. Use a scoped personal API key for REST, or a scoped OAuth token for the MCP resource. Read-only keys, Account Secrets and old connections do not acquire management rights. Approve only the additional permissions you need.

REST prepare takes the command below and an Idempotency-Key header. MCP prepare takes {"body": COMMAND, "idempotency_key": "YOUR_STABLE_KEY"}. Use opaque references from the connected account, never database IDs.

{
  "schema_version": 1,
  "account_id": "PUBLIC_ACCOUNT_UUID",
  "operation": "trade.edit",
  "trade_refs": ["RETURNED_TRADE_REF"],
  "changes": {"stop_loss": "19999", "profit_target": "20002"}
}

Operations are trade.edit, execution.edit, execution.delete, trade.delete, trade.split, trades.merge, and tag.delete_global. Execution operations and splitting also take execution_refs; execution edit takes exactly one. Merge takes 2–10 trade refs, with the destination first. All numeric edits are exact decimal strings; timestamps include a timezone. Target null clears that target. See OpenAPI for complete request shapes.

Show the preview and obtain confirmation, then send its intent_token, account_id and operation to commit. A preview expires after five minutes. Changed data or calculation settings require a fresh preview and confirmation. After a timeout, retry the identical intent: a retained receipt prevents double application, even after deletion. A signed preview is not itself proof that a human approved it.

Split moves selected whole executions to a new trade; notes, tags, uploads and targets stay on the original. Merge keeps the first trade's identity and metadata, and moves source annotations and uploads. Incompatible instruments, accounts, simulator status, conflicting TP/SL or shared conversations are rejected. Deletes include the previewed dependent rows; files are not removed from storage by these tools.

Global tag deletion is a separate explicit action: {"schema_version":1,"account_id":null,"operation":"tag.delete_global","tag":"123"}. It previews and removes every exact matching trade/day attachment in your journal, including simulated trades. It requires tags.delete, personal-journal consent, and consent for every affected account. Tag groups, note categories and other labels are preserved. TradesViz derives tag labels from attachments, so removing all occurrences removes the label from its tag list; the same label can be created again later. This is never inferred from a request to remove a tag from one trade.

Execution recalculation and TP/SL calculation currently support qualified USD stocks and fixed-multiplier futures with the supported FIFO profile, including simulated trades. Unsupported profiles return an error without changes. Search, full-trade deletion, lock edits and annotations do not require that calculation profile. Advanced analytics may remain pending; a receipt is not proof that deferred analytics has completed.