Connect via MCP & SDKs

Fastest path: connect your agent#

Your agent signs in to Wealthnow itself. There is no key to copy: you approve the connection once, in your browser, and it uses your plan and credits from then on.

After connecting, ask: "Using Wealthnow, what's the latest quote for AAPL?" Connected agents appear on Overview → Connected agents. Disconnecting one stops that agent only; your API keys keep working.

Each time an agent connects, it gets a key of its own. The agent never sees it: Wealthnow keeps it with the agent's sign-in, and the agent's calls are made and billed as that key, on your workspace's credits and plan. It is listed under Developers → API Keys as Agent connection, with when it was last used and its own request limit. Revoking it cuts off the agent that holds it and nothing else; the agent needs to connect again. After you disconnect an agent, its key can no longer be used, and you can revoke it from the same page. Connection keys do not count toward your workspace's key limit. A workspace can have up to 50 in use; one unused for 30 days stops counting, but keeps working until you revoke it.

Model Context Protocol (MCP)#

The hosted MCP server exposes Wealthnow's market and research tools to compatible AI clients over Streamable HTTP. Tool calls follow the same credit costs and plan access as REST calls.

Tool names. Tools are named for what they do, such as fundamentals_full or fundamentals_price_snapshot, and each MCP tool name matches the operationId of the same route in the OpenAPI spec, with the same parameter names. The API reference lists the tool next to each route. The 10 server-sent-event streams (the nine SSE routes under /api/v3/stream/, and /api/v3/earnings/next/{ticker}/stream) are REST only, because MCP cannot relay a stream; stream_realtime_guide, which explains which stream fits which question, is an ordinary tool. Older tool names from earlier API versions are still accepted by tools/call, so saved prompts and workflows keep working. Every tool carries MCP annotations: a title, and readOnlyHint: true, since no tool changes your account or places orders.

What you can call. The default list only decides what your agent sees first. tools/call accepts any public tool your plan includes, listed or not. A tool outside your plan returns a plan_required tool error that names the plan that unlocks it (the same call over REST answers 402). An unknown name is a JSON-RPC -32602 error. account_status returns your plan, credits remaining and entitlements, and search_tools finds tools by topic; neither spends credits. account_status reads the balance from the key service on every call, so it agrees with the X-Credits-Remaining of the call before it. as_of is when the balance was read and stale_seconds how old it is: 0 for a live reading, more only when the key service could not be reached and the last verified balance is served.

Arguments. Every tool's inputSchema carries each parameter's description, including its unit (roe_min_pct is a percent, debt_to_equity_max a multiple). fundamentals_screener refuses an argument it does not declare: the result has isError: true, structuredContent.error is unknown_argument, and the text lists the accepted arguments, with a suggestion when one is close. Nothing is run or billed. It refuses because an ignored filter returns an unfiltered screen that looks filtered. Other tools ignore an argument they do not declare.

The server advertises its OAuth configuration from the 401 it returns to an unauthenticated request, so clients that implement MCP authorization find the sign-in on their own. A few cannot finish it yet; see Apps that need a key for now. A connection made through sign-in holds a short-lived, revocable token, never one of your API keys: the token stands for that connection's own key.

Claude (web, Desktop, mobile)#

1. On Overview, open Connect your agent → Claude and click Add to Claude. It opens Claude's connector form with the name and URL filled in. (Or, in Claude, open Settings → Connectors → Add custom connector and enter https://mcp.wealthnow.io/mcp.)
2. Click Add, then Connect. Claude opens Wealthnow in your browser.
3. Choose Sign in to Wealthnow, then Connect on the confirmation, which shows the plan and credit balance the agent will use.

You are returned to Claude, connected. On a Claude Team or Enterprise plan, an owner may need to add the connector for your organization first.

Claude Code#

claude mcp add --transport http wealthnow https://mcp.wealthnow.io/mcp

Run /mcp inside Claude Code, select wealthnow, and choose Authenticate. A browser tab opens for Sign in to Wealthnow. On a machine without a browser, pass your key instead:

claude mcp add --transport http wealthnow https://mcp.wealthnow.io/mcp \  --header "X-API-Key: wn_YOUR_KEY"

Cursor#

On Overview, open Connect your agent → Cursor and click Add to Cursor. Cursor installs the server from a link that contains only its public URL, detects that it needs sign-in, and opens Sign in to Wealthnow in your browser. There is no key to paste.

If sign-in is blocked on your machine, add the server to ~/.cursor/mcp.json with your key in the X-API-Key header instead. Keep that file out of shared repositories. See Cursor's MCP documentation.

ChatGPT#

ChatGPT connects custom MCP servers through OAuth, which Wealthnow supports. The Connect your agent → ChatGPT card walks through the clicks:

1. In ChatGPT, open Settings → Apps (some accounts show Apps & Connectors), then Advanced settings, and turn on Developer mode.
2. Back on Apps, click Create.
3. Enter https://mcp.wealthnow.io/mcp as the MCP server URL and choose OAuth.
4. Sign in to Wealthnow and Connect. Do not paste an API key.

Developer mode availability depends on your ChatGPT plan, and workspace administrators may control it.

Codex#

Add the server, then sign in; Codex opens Sign in to Wealthnow in your browser:

codex mcp add wealthnow --url https://mcp.wealthnow.io/mcpcodex mcp login wealthnow

To use a key instead, set bearer_token_env_var in ~/.codex/config.toml; the server accepts your key as a bearer token:

[mcp_servers.wealthnow]url = "https://mcp.wealthnow.io/mcp"bearer_token_env_var = "WEALTHNOW_API_KEY"

Claude Desktop extension (API key)#

The extension bundles its own MCP bridge, so it needs no Node.js install and no config files. Use it when you would rather authenticate with a key.

1. Download the Wealthnow desktop extension (or use the Download for Claude Desktop button on Overview).
2. In Claude Desktop, open Settings → Extensions → Advanced settings and click Install Extension.
3. Select wealthnow.mcpb and enter your Wealthnow API key when prompted.

Claude stores the key in your operating system's secure storage. See Claude's extension installation guide.

Configure Claude Desktop by hand (API key)#

Claude Desktop can launch mcp-remote as a local process that forwards your key. Node.js and npx must be available to Claude Desktop.

1. Open claude_desktop_config.json and add the wealthnow entry to mcpServers, keeping any existing entries.
2. Replace wn_YOUR_KEY in the env object with your Wealthnow key.
3. Save the file, fully quit Claude Desktop, and reopen it.

{  "mcpServers": {    "wealthnow": {      "command": "npx",      "args": [        "-y",        "mcp-remote@0.14.2",        "https://mcp.wealthnow.io/mcp",        "--header",        "X-API-Key:${WEALTHNOW_API_KEY}"      ],      "env": {        "WEALTHNOW_API_KEY": "wn_YOUR_KEY"      }    }  }}

Desktop apps may not inherit variables exported in your terminal; the env object supplies the key to the MCP process directly. This file contains your key, so keep it out of source control and screenshots. To expose the full public catalogue, use https://mcp.wealthnow.io/mcp?catalog=full in args.

Grok#

Grok supports custom MCP connectors, but authenticated calls through the Grok app have not been verified. To try it, open Grok connectors, select New Connector → Custom, enter https://mcp.wealthnow.io/mcp, and choose Sign in to Wealthnow if Grok offers sign-in. Organization administrators may need to provision the connector first. For applications on the xAI API, the remote MCP integration accepts an X-API-Key header.

Apps that need a key for now#

Apps that support remote MCP servers with OAuth add https://mcp.wealthnow.io/mcp, register themselves, and open Sign in to Wealthnow. We have checked (2026-09-28, 70 of 72 client variants) that Claude (web, Desktop including its Code tab, and Claude Code), ChatGPT, Codex, Cursor, VS Code, Zed, GitHub Copilot CLI and the Copilot desktop app, Goose, Gemini CLI, Grok, Perplexity, Devin Desktop (formerly Windsurf), Warp, Continue, Cline, Raycast, LibreChat, Le Chat and MCP Inspector reach that sign-in. The sign-in response carries the iss parameter that Gemini CLI 0.60 and later require.

Until 2026-09-28, Devin Desktop and Warp refused the sign-in after it: their clients drop the iss parameter and then report it missing (devin-cli#5). The server no longer asks clients to require it, while still sending it, so their sign-in is no longer refused for that reason.

If an app shows an error page where Sign in to Wealthnow should be, or fails after you sign in, connect it with your wn_ key instead.

Put the key in your user-level settings, never in a project file that may be committed to a repository.

Gemini CLI (-s user saves the server in your user settings, ~/.gemini/settings.json; without it, Gemini CLI writes the key into the current project's .gemini/settings.json):

gemini mcp add -s user --transport http wealthnow https://mcp.wealthnow.io/mcp -H "X-API-Key: wn_YOUR_KEY"

Goose (~/.config/goose/config.yaml):

extensions:  wealthnow:    type: streamable_http    name: wealthnow    enabled: true    uri: https://mcp.wealthnow.io/mcp    headers:      X-API-Key: wn_YOUR_KEY    timeout: 300

OpenCode cannot finish sign-in yet because of a bug in OpenCode (opencode#50510). Connect it with a key in your global config, ~/.config/opencode/opencode.json, which reads the key from an environment variable:

{  "mcp": {    "wealthnow": {      "type": "remote",      "url": "https://mcp.wealthnow.io/mcp",      "headers": { "X-API-Key": "{env:WEALTHNOW_API_KEY}" },      "oauth": false    }  }}

Devin Desktop and Warp sign in on their own; a key also works, for example on a machine without a browser.

Devin Desktop (formerly Windsurf; ~/.config/devin/mcp_config.json on macOS and Linux, %APPDATA%\devin\mcp_config.json on Windows), reading the key from an environment variable:

{  "mcpServers": {    "wealthnow": {      "url": "https://mcp.wealthnow.io/mcp",      "headers": { "X-API-Key": "${env:WEALTHNOW_API_KEY}" }    }  }}

Warp (Settings → Agents → MCP servers, then add a server):

{  "wealthnow": {    "url": "https://mcp.wealthnow.io/mcp",    "headers": { "X-API-Key": "wn_YOUR_KEY" }  }}

VS Code and Zed sign in on their own, but you can use a key instead, for example on a machine without a browser.

VS Code (.vscode/mcp.json) asks for the key once and keeps it in secure storage, so the file itself holds no key:

{  "inputs": [    {      "type": "promptString",      "id": "wealthnow-key",      "description": "Wealthnow API key",      "password": true    }  ],  "servers": {    "wealthnow": {      "type": "http",      "url": "https://mcp.wealthnow.io/mcp",      "headers": { "X-API-Key": "${input:wealthnow-key}" }    }  }}

Zed (your user settings, ~/.config/zed/settings.json, not a project's .zed/settings.json) skips sign-in when an Authorization header is set, and the server accepts your key as a bearer token:

{  "context_servers": {    "wealthnow": {      "url": "https://mcp.wealthnow.io/mcp",      "headers": { "Authorization": "Bearer wn_YOUR_KEY" }    }  }}

Inspect the available tools#

Listing tools requires a key or a sign-in, like every other call; without one the server answers 401 with its sign-in challenge. Listing does not run a market-data tool or spend credits:

curl --fail-with-body --silent --show-error --max-time 30 \  https://mcp.wealthnow.io/mcp \  -H 'Content-Type: application/json' \  -H 'Accept: application/json, text/event-stream' \  -H "X-API-Key: $WEALTHNOW_API_KEY" \  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \  | jq '.result.tools[].name'

Use https://mcp.wealthnow.io/mcp?catalog=full in the same command to inspect the full public catalogue, or call search_tools to find tools by topic. A successful listing confirms your key and the connection; it does not establish your plan's access to a particular dataset.

What the default list shows#

Without a catalog option, tools/list shows account_status, search_tools, and the tools your key can call: the products in your plan and add-ons, within the key's scopes. The list follows your plan, so it changes when you upgrade.

• When your key can call 40 tools or fewer, as on Free, the list is all of them.
• On a larger plan, the list holds about 100 tools and never more than 120. It always includes every Free tool, a curated set of headline tools and your add-on tools. Your own plan's tools fill the room left, one product at a time, then tools from the plans below it.

Some clients refuse long tool lists (VS Code and the OpenAI API stop at 128), so the default list is bounded. Call search_tools or list the full catalogue with ?catalog=full to reach the rest. The option also works as a catalog parameter of tools/list. The response to tools/list is the authoritative count for your key; each tool's _meta carries wealthnow/min_plan and wealthnow/credits.

Find a tool: search_tools#

search_tools searches the whole public catalogue by words in tool names and descriptions, including tools your plan cannot call yet. It is answered by the MCP server itself: it runs no data tool and costs no credits. It needs the same sign-in or key as tools/list.

curl --fail-with-body --silent --show-error --max-time 30 \  https://mcp.wealthnow.io/mcp \  -H 'Content-Type: application/json' \  -H 'Accept: application/json, text/event-stream' \  -H "X-API-Key: $WEALTHNOW_API_KEY" \  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_tools","arguments":{"query":"options flow","limit":1}}}' \  | jq '.result.structuredContent'

It answers (summary shortened here):

{  "query": "options flow",  "matches": [    {      "name": "intel_options_flow",      "summary": "The most recent unusual options-flow alerts across the whole market ...",      "min_plan": "pro",      "credits": 4    }  ],  "total_matches": 54}

The result is in structuredContent and, as JSON text, in content. Matches are ranked by how often the words appear, and a word in a tool's name counts more than one in its description. summary is the description's first sentence, cut at 200 characters. min_plan is the cheapest plan that can call the tool (null when only an add-on sells it), and credits its cost per call. total_matches counts every match, not only those returned.

A query that is missing or not a string, is longer than 200 characters or has more than 10 distinct words, or a limit outside 1 to 25, is a JSON-RPC -32602 error. A query with no usable words is a tool error (isError: true), and so is an argument other than query and limit (unknown_argument).

OpenAPI spec#

A curated public OpenAPI 3.1 spec, only the advertised public tools, never internal or admin routes, is served at:

• https://firm.wealthnow.io/api/openapi.json (no key needed to fetch the spec)

Each operation's operationId is the same name the MCP server uses for that tool, and x-wealthnow-min-plan gives the cheapest plan that can call it (free, starter, pro or expert).

Load it into Swagger UI, Redoc, or Postman, or lint it:

npx @redocly/cli lint https://firm.wealthnow.io/api/openapi.json

SDKs#

Official clients for Python and TypeScript / JavaScript, with the same auth, credits and plan gating as the REST API. Both default to https://firm.wealthnow.io and read your key from WEALTHNOW_API_KEY:

pip install wealthnow       # Python 3.9+npm i wealthnow             # Node 18+, ESM and CommonJS

Every operation in the spec is callable by its operationId, which is the same name the MCP server uses for the tool. Failed calls raise WealthnowError (Python) or throw it (TypeScript) with the status, error code and request ID. Source and full reference: github.com/Hlobo-dev/wealthnow-mcp.

Prefer to generate a client yourself? Point any OpenAPI generator at the live spec:

openapi-generator generate -i https://firm.wealthnow.io/api/openapi.json \  -g python -o wealthnow-python

No SDK required to start. The API is plain HTTP + JSON, so any client works:

import os, requests r = requests.get(    "https://firm.wealthnow.io/api/v3/fundamentals/price_snapshot",    params={"ticker": "AAPL"},    headers={"Authorization": f"Bearer {os.environ['WEALTHNOW_API_KEY']}"},    timeout=30,)r.raise_for_status()snap = r.json()["snapshot"]stale = " (stale)" if snap.get("is_stale") else ""print(f"{snap['ticker']} @ ${snap['price']} as of {snap['as_of']}{stale}")

For Claude Code & AI agents#

Two rules matter more than the rest when an agent drives this API:

1. Disambiguate colliding tickers. Nine symbols are both a crypto asset and a US-listed equity: BTC, ETH, LINK, LTC, COMP, ARB, NEAR, APT, ATOM. On the intel_ml_prediction tool, pass asset_class=equity or asset_class=crypto explicitly. Responses for those nine carry a ticker_collision note that must be relayed to the user. Presenting the equity BTC as Bitcoin is a correctness failure. Requesting the crypto side fails closed with 404 crypto_model_unavailable; that never means "fall back to the equity." Full detail in Ticker collisions.

2. Streams are long-lived, not request/response. The SSE routes under /api/v3/stream/ are REST only, not MCP tools: they return Server-Sent Events and stay open. Outside roughly 04:00–20:00 ET they emit heartbeats and no market data. That is correct, not a failure. Don't retry a quiet stream. See Real-Time Streaming.

Beyond that: read /api/capabilities before generating calls rather than guessing paths; retry 429, 502, and a 503 only when it carries Retry-After or "retryable": true, never one that says "retryable": false or asks for a wait longer than 120 seconds; and check X-Credits-Cost / X-Credits-Remaining on each response to track spend.