MCP Connector | SentiSense API Documentation

Overview

The SentiSense MCP connector is a Model Context Protocol endpoint that lets AI apps like Claude, Claude Code, Codex, ChatGPT, and Grok pull SentiSense market intelligence directly into a conversation. Add it once and your assistant can answer questions about market mood, a stock's sentiment, market-moving news, analyst ratings, and institutional flows.

It is the third way into the same data graph that powers our REST API and the full app. Builders who need the complete surface use the API and the agent skill; the connector is a curated, read-only slice designed for chat.

What it is: eleven read-only tools, exposed over MCP. No trading, no account changes, no writes.
Auth: zero-config OAuth. There is no API key to paste. You sign in with your SentiSense account inside the AI app and approve access, and the connection is remembered.
Hosts: Claude, Claude Code, Codex, ChatGPT, and Grok. In Claude, SentiSense is listed in the connector directory, so there is no URL to paste either.
Guides: the connector page has setup steps for each app, an Add to Claude button that opens the directory listing, and a recorded example conversation; how to connect market data to your AI agent is the longer walkthrough; how to build a portfolio dashboard in Claude shows a live dashboard built from the connector.

Add the connector

The connector URL is:

https://app.sentisense.ai/mcp

Claude

SentiSense is listed in Claude's connector directory, so in Claude on the web, in the desktop app and on mobile there is nothing to paste.

Open SentiSense in Claude's connector directory. Inside Claude, the same listing is under Customize, then Connectors, then Discover.
Choose Connect.
Sign in with your SentiSense account and approve access.
Start a chat and ask about a ticker or the market.

If your organization restricts the directory, add it by URL instead: open Customize, then Connectors, choose Add custom connector, paste the URL above, and choose Add. Custom connectors are available on Free (one custom connector), Pro and Max. On Team and Enterprise, an Owner adds them under Organization settings, then Connectors.

Claude Code

From your project directory, register the connector as a local MCP server:

claude mcp add sentisense -- npx -y mcp-remote@0.1.38 https://app.sentisense.ai/mcp

Start claude, approve the server when prompted, and sign in with your SentiSense account in the browser tab that opens.
Ask about a ticker or the market; the agent picks the tool.

Walkthrough: how to add live market data to your Claude Code agent.

Codex

Codex is included in every ChatGPT plan, Free and Go included.

From your terminal, register the connector and start the OAuth sign-in:

codex mcp add sentisense --url https://app.sentisense.ai/mcp
codex mcp login sentisense

Sign in with your SentiSense account in the browser tab that opens and approve access.
To add it from the Codex desktop app instead, open Plugins, then Manage, then MCP, then Add server. Choose URL and paste the connector URL above. Restart if prompted.
The desktop app, CLI, and IDE extension share the same MCP configuration, so you only need to add the server once. Ask about a ticker or the market; Codex picks the tool.

Walkthrough: how to add live market data to your Codex agent.

ChatGPT

On the web, Free accounts included:

Open Plugins, choose Add, then Add custom MCP server.
Name it SentiSense, keep Connection on Server URL and paste the URL above, and set Authentication to OAuth. The icon is optional.
Tick "I understand and want to continue", then choose Create as a plugin.
Sign in with your SentiSense account when asked and approve access.
Ask your question in any chat. Name SentiSense in the question if ChatGPT does not pick it up on its own.

ChatGPT shows a notice that custom MCP servers introduce risk. SentiSense is read-only: it can never trade, change or delete anything in your account. The same steps work on Plus and Pro; on Business, Enterprise and Edu an admin may need to allow custom servers first.

Grok

Open Connectors in Grok.
Choose New Connector, then Custom, and paste the URL above.
Sign in with your SentiSense account and approve access.
Ask your question in any chat.

Grok calls anything outside its built-in catalog a custom connector, which is what the SentiSense endpoint is.

Grok Bot (pending verification)

Grok Bot, the xAI agent runtime, registers with its own private-scheme callback rather than a web one. We allowlisted that callback on 2026-09-04, so adding the connector URL should now work the same way it does in Grok. We have not yet confirmed a completed connection end to end, so treat this host as pending verification.

Menu labels shift between releases. In ChatGPT the area is "Plugins"; in Claude and Grok, "Connectors". In Claude, what you want is the SentiSense listing in the directory; everywhere else, the option to add an app or connector by its URL.

Tools

Your AI selects the right tool for each question, so you ask in plain English rather than calling tools by name.

Tool	What it answers
`get_market_mood`	SentiSense's own fear and greed index: the proprietary 0 to 100 composite for the US market, its phase, and the signal components.
`get_stock_snapshot`	Price plus the SentiSense sentiment, the SentiSense Score, and key stats for a single ticker.
`get_rating`	The SentiSense Rating for a ticker and the composition behind it: the daily letter (A, B, C, D or F), its percentile among every stock rated that day, and the seven dimensions that produced it (crowd sentiment, smart money, options positioning, analysts, fundamentals, earnings, and technicals: where the price sits versus its own history), with the anomaly flags the run evaluated. It is an informational rank of the stocks we cover against each other on that day's cross section, not a recommendation. Recomputed once a night; not every stock is rated every day, and the tool says so when one is not.
`get_news`	News for a stock or a topic. `view=documents` (default) returns the documents we track as publisher or X author, our derived sentiment and a link to the original, never the headline; `ticker` and `query` combine. `view=stories` returns SentiSense's curated story clusters, each with our own title and one-line summary, when it broke, how many sources it groups, aggregate sentiment and the tickers involved; search them by ticker, by a topic query such as `fed decision` or `MCD traffic value menu`, or both, over a lookback of up to 30 days. `view=story` with a story id returns one story's full narrative: summary, body, bull and bear views, timeline and source links (20 reads a month on FREE, unlimited on PRO, SentiSense Originals free for everyone).
`get_analyst_ratings`	The buy, hold, and sell consensus and price targets for a ticker, one ticker's recent analyst moves, or market-wide rating changes (upgrades, downgrades, and coverage initiations, with reiteration noise filtered out). Tunable lookback window, row count, and direction filter, and every list leads with a shown-versus-total header so the AI knows how much more exists.
`get_smart_money`	Institutional 13F holdings and flows: who is buying and who is selling, who owns a stock, and what one 13F manager holds.
`get_options`	Options intelligence for a ticker (stock or ETF), ranked against its own history: options-implied sentiment, IV rank, put/call percentile, max pain, and, for PRO, 25-delta skew, the heaviest open-interest walls, and unusual contracts. Leave the ticker out for the market radar of the most active options today (stocks only; fetch ETFs by ticker). End-of-day chains, latest session.
`get_earnings_calendar`	`view=schedule` (default): next earnings report for a ticker (date, timing, confirmation, fiscal quarter, consensus EPS), or the full `week=last`, `week=this` or `week=next` schedule for every tier, with Monday-to-Sunday bounds anchored on US Eastern time. `view=ranked`: which recent and upcoming reports matter most, with a 14-day lookback, 7-day forward window, resolved bounds, ranking version, shown/total, EPS surprise and distinct measured, provisional live, after-hours or pending readings; FREE sees up to 3 rows per section, PRO up to 12, and ticker/week apply only to schedule.
`get_financials`	Reported income statement, balance sheet, and cash flow for a stock, per fiscal quarter or fiscal year, including margins and other derived ratios, up to 40 quarters or 20 years back. Also returns curated SentiSense company KPIs on PRO. These are reported actuals, not consensus estimates.
`screen_stocks`	Screen and rank the tracked stock or ETF universe by SentiSense signals and market data. Sort by score, mentions, social dominance, market cap, price, change, volume, 52-week distance, IV rank, put/call, or expected move, and filter with a compact list like `score_7d > 10, market_cap < 10B, change_percent > 0`. Call with no arguments for today's sentiment leaders and biggest movers.
`entity_brief`	Who and what sits behind one stock, from the curated SentiSense knowledge graph: executives and founders with the relationship each one has to the company, products and the families they belong to, the companies tracked as peers, and organizations reached through a person. Every entity carries the handle that reads its SentiSense Score. One ticker per call; these are dated, hand-curated relationships, and the graph carries no sentiment or price data.

All eleven are read-only.

For a ticker, get_smart_money also answers who owns the stock and which well-known filers hold it. Ticker ownership uses the latest eligible settled quarter when available and reports newer early filings separately. Market-wide flows retain their latest available quarter.

With source=institutional, the optional manager argument reads one 13F filer's portfolio in place of a ticker: a filer name, URL slug or SEC CIK (Berkshire Hathaway, Bridgewater-Associates, 1067983), or a well-known manager's name such as Buffett or Ackman. It resolves by exact slug, then CIK, then a curated list of well-known managers, then an exact filer name, then the institution directory search; several matches return up to five candidates with their slugs and CIKs, and none is picked. The answer covers the filer's newest filed quarter (a quarter still filing once the filer, and for a multi-filer family every member, has filed) with its subsidiary filers rolled up: the largest positions by reported value (Free up to 6, PRO up to 20) with shares, value, portfolio weight and the change since the immediately preceding quarter, and on PRO the largest adds, trims and exits across the whole portfolio, up to 10 each. Changes use the share changes recorded at ingestion, restated for stock splits, and are omitted when the filer has no 13F for the quarter before, when its subsidiary filers did not all report in both quarters, or when that quarter was filed under a predecessor CIK.

The server also advertises one utility tool, sentisense_health, a lightweight connection check. It is not a data tool and does not consume quota.

Six tools accept an optional format argument: get_stock_snapshot, get_rating, get_analyst_ratings (view=consensus and view=history), get_earnings_calendar (view=schedule with a ticker), get_smart_money and get_news (view=stories). With format: json the tool returns the same facts as its text answer, at the same tier depth, as one JSON object with the keys tool, schemaVersion, generatedAt, access (FREE or PRO, the depth served), ticker (present on per-ticker answers and absent on market-wide ones, such as the market-wide smart-money lists), data, notes and disclaimer; a key with no value is omitted, and any other view returns its text answer with a one-line note. get_smart_money answers carry data.complete: true when the window totals or the full list are whole, false for a ranked top-N market-wide list, a FREE preview, or institutional holders while the 13F quarter is still filing. access reports the depth served, not the plan you are on: a Free account's answer about one of the sample companies is served in full and reads PRO. A per-ticker get_smart_money answer that is full only for that reason also carries top-level sampleCompany: true, and its notes (and the text answer's footer) end with the sentence "TSLA is a sample company: full data on every plan. PRO unlocks every company.", with the answer's own ticker. The key is present only in that case and is never false: a PRO answer on the same ticker, and a Free answer on any other ticker, carry no sampleCompany key and no sentence. get_analyst_ratings history carries data.requested (the days and dates the call asked for) and data.window (the dates the server actually covered, which can be shorter, for example the 30-day FREE preview). get_analyst_ratings consensus carries data.upsideBasis (price and asOf, an ISO instant) when the stored implied upside has a recorded basis: impliedUpsidePercent is measured against that price at that time, not against the live quote. The Rating percentile is a number to one decimal in both get_rating and get_stock_snapshot. get_stock_snapshot carries data.score.latest and data.sentiment.latest with latestAsOf, the US Eastern date of that daily reading: today's once the day's first metrics batch has written it, the previous day's before then (overnight and early morning Eastern; a quiet ticker can stay on the previous day's reading until midday), with a note saying so, and both keys are omitted when neither day has a reading. data.score.avg30dThinSample is true below 20 directional mentions (bullish plus bearish) across the same window as avg30d; data.score.latestThinSample is true below 10 in the daily bucket dated by latestAsOf. They are false at or above the floors and omitted when sample metadata is unavailable; thin readings retain their Score and carry a text warning. data.score.trend compares that reading with avg30d, and avg30d covers the 30 days ending on the latestAsOf date. data.topSignal.generatedAt, when available, is the signal's generation time as an ISO instant, shown in the text as its US Eastern date; it is separate from the envelope's response-time generatedAt. When there is nothing to report (an unknown ticker, an empty result, an upstream outage), data is absent and a message key says why; a rate-limit or monthly-limit reply stays plain text even with format: json. get_stock_snapshot carries data.price.basis when the price basis is known: intraday is a delayed regular-session reading, premarket is a pre-market reading against the prior close, and close is a completed regular-session close. intraday can be undated; price.asOf is omitted when the data has no usable timestamp. The basis is omitted when unclassified, including an undated reading before 09:45 ET, the delayed-close gap from 16:00 to 16:15 ET and missing reference-close data. With close, optional data.price.extendedHoursSession (pre or post) identifies newer extended-hours trading not reflected in value; post can be carried overnight and through weekends. If the previous-close change could not be assembled, basis remains close and data.price.changeAvailable is false; the existing changePercent value is a placeholder, the text says "change unavailable", and a note identifies the placeholder. changeAvailable is omitted for all other quotes. A synthetic example:

For a 13F ticker question, get_smart_money JSON keeps data.quarter.reportDate and data.quarter.pending, and adds data.quarter.value, label and status (settled or filing). data.selection is the same quarter-choice object as the REST /holders/{ticker} response (mode, status, policyVersion, marketDefaultReportDate, isStaleForMarket). data.earlyFilersStatus is AVAILABLE, NONE or UNAVAILABLE; data.earlyFilers is present only on AVAILABLE and can carry coveragePct based on confirmed reporting filers' settled-quarter value, including exits, only when the raw baseline sum reconciles with the served total. The output separately labels positive-position holder families and the reporting-filer coverage cohort. Holder rows keep name, value and changeType, and add shares, cik, slug and per-row comparisonStatus; sharesChange and sharesChangePct are present only when that row's status is AVAILABLE, and NEW positions omit sharesChangePct because they have no prior-position percentage baseline. data.comparisonReportDate names the immediately preceding calendar quarter and can be present when comparison data is unavailable or incomplete; it is omitted when no supported prior comparison date exists. data.comparisonStatus (AVAILABLE, PRIOR_QUARTER_UNAVAILABLE, INCOMPLETE_INPUT, INCOMPLETE_FAMILY_COVERAGE or UNAVAILABLE) summarizes the response, while each holder's status qualifies its own quarter-change claim. data.notableHolders is capped at five identities on Free; PRO can include shares, value, per-row status and valid quarter changes. The notable list is checked against the full selected-quarter roster and does not add rows to data.holders. If that lookup is unavailable, data.notableHolders and data.notableHoldersScope are omitted and a note reports the unavailable auxiliary data. A verified empty match remains notableHolders: [] with notableHoldersScope: "full_roster".

A get_smart_money manager answer in JSON has no ticker key. data.manager carries name, cik, slug, matchedBy (slug, cik, roster, name or search) and, for a rollup, childCikCount; data.quarter and data.selection match the ticker answer. data.positions[] carries ticker, companyName, shares, value, portfolioWeight and, when the quarter comparison holds, changeType, sharesChange and sharesChangePct (omitted for NEW); a position that a subsidiary filer held last quarter and holds none of now carries comparisonStatus: "INCOMPLETE_FAMILY_COVERAGE" instead. data.rankedBy is value, and data.shown, data.total (positions held), data.complete and data.totalValue describe the list. data.comparisonStatus is AVAILABLE, PRIOR_QUARTER_UNAVAILABLE, INCOMPLETE_FAMILY_COVERAGE, PRIOR_QUARTER_FILED_BY_PREDECESSOR, INCOMPLETE_INPUT or UNAVAILABLE, with the compared quarter in data.comparisonReportDate. Only on AVAILABLE: data.changeCounts (new, increased, decreased, soldOut, and notCompared when above zero) and, on PRO, data.added, data.trimmed and data.exited with the same row keys, where adds and trims rank by the value of the shares changed at the filing's own price per share and exits by shares sold. An unmatched, ambiguous or invalid manager returns data absent and a message.

{"tool": "get_rating", "schemaVersion": 1, "generatedAt": "2026-01-02T15:04:05Z", "access": "FREE",
 "ticker": "XYZ", "data": {"rated": true, "letter": "B", "score": 64.0, "percentile": 71.5,
 "dimensions": [{"key": "crowd", "percentile": 30, "metric": {"name": "7-day SentiSense Score", "value": -14.6}}]},
 "notes": ["Flags are observations and never move the letter."], "disclaimer": "Not investment advice."}

Per-ticker earnings results

get_earnings_calendar with a ticker and view: "schedule" returns an optional data.latestReported in JSON and a matching "Latest reported" line in text, on both FREE and PRO. It selects the most recent qualifying calendar row on or before today, using the US Eastern business date. A report stays available while it remains in the calendar snapshot, about 90 days. It is independent of whether a future report exists. data.nextReport keeps its existing upcoming-only lower bound of today, inclusive, so a report dated today with actual EPS or revenue can appear in both objects. No past date is placed in nextReport.

latestReported uses the calendar event fields: ticker, companyName, earningsDate, earningsTime, fiscalQuarter, confirmed, estimatedEps, estimatedRevenue, actualEps, actualRevenue, epsSurprisePct, revenueSurprisePct and epsBasis. Dates are ISO YYYY-MM-DD; EPS is per share, revenue is an absolute amount, and surprise values are percentages. These names are the calendar row's names; nextReport retains its existing names such as date, timing, epsEstimate and epsActual.

A row dated today qualifies only when at least one of actualEps or actualRevenue is available. With both null, the current snapshot has no reported actuals for that row, so latestReported falls back to the previous qualifying report, if any. A past-dated row still qualifies with null actuals, which remain explicit nulls in JSON; text says "reported results unavailable" when neither actual is available. A past scheduled date alone does not confirm receipt of the results. The whole latestReported key is absent if no row in the current snapshot qualifies or its lookup fails. Lookup failures leave the existing response intact and are retried on a later call. With a latest row but no upcoming row, data.latestReported is present, data.nextReport is absent and the existing "No upcoming earnings" message remains. Snapshot retention of about 90 days does not guarantee continuous history between quarterly reports. The REST calendar also includes data.latestReported on ticker-filtered requests.

Tiers

The connector respects the tier of the SentiSense account you sign in with.

Free: 1,000 tool calls per month at up to 30 calls per minute. Tool calls share the same monthly quota as your REST API requests. Market Mood and news return full results; stock snapshots, smart money, options, the earnings calendar, and the screener return preview-depth data. Analyst ratings are generous on Free: the price-target band and the market-wide rating-changes feed are full data on every tier, with only the buy/hold/sell counts and deep per-ticker history reserved for PRO. For options, Free shows the headline readings and a short radar, while PRO adds skew, the open-interest walls, unusual contracts, and a longer radar. For the earnings calendar, Free sees the current week (a per-ticker next-report lookup is open to everyone), while PRO adds next week and the full forward window. For the screener, Free returns up to 10 ranked rows and PRO up to 50. For financials, the reported statements are full data on every tier; only the curated company KPIs section is PRO. On the sample companies, a Free account gets full data from the per-ticker get_smart_money and get_options answers and the curated KPIs in get_financials; each of the three then says so in one line ("TSLA is a sample company: full data on every plan. PRO unlocks every company."), which in get_options follows "Data access: PRO depth." and in get_financials sits under the KPI section's heading.
PRO: full data on every tool, no monthly cap, up to 300 calls per minute.
Pro Max and Data License: everything in PRO, at up to 1,500 (Pro Max) or 2,000 (Data License) calls per minute.

You start on whatever tier your account is on. Upgrading to PRO unlocks the full payload through the same connection, with no reconnecting.

How it relates to the REST API

The connector is the fastest way in, not the deepest. It is a read-only surface over the same data graph as the REST API. If you are building a product, an agent, or a dashboard, use the API directly and load the agent skill: you get the full endpoint set, typed SDKs for Python and Node, and direct control. The connector is for asking questions inside Claude, ChatGPT, and Grok.

Example prompts

"What's the market mood right now?"
"Give me a snapshot of NVDA with its SentiSense score and recent news."
"What do analysts think of TSLA, and what are the price targets?"
"Which institutions are buying and selling AAPL?"
"Who owns CRM, and which well-known funds hold it?"
"What did Berkshire Hathaway add last quarter?"
"What's the options sentiment on NVDA, and is IV high right now?"
"What options are unusually active today?"
"Who reports earnings this week, and when does NVDA report?"
"Pull 10 years of annual revenue and free cash flow for AAPL."
"What stocks lead by sentiment today?"
"Find stocks under $10B market cap with rising sentiment."

Notes

Quotes are 15-minute delayed; sentiment, mood, and news are batch. Prices refresh continuously, while the sentiment reads, Market Mood, and news annotations are recomputed on a regular cadence.
Coverage spans the most-watched US stocks, not every ticker.
The connector provides market information for informational and educational purposes only. It is not investment advice.
Use of the MCP connector is governed by the API Terms of Service. Connecting and approving access constitutes acceptance.