Skip to content
Back to search

octagon-mcp-server

An MCP server for public & prediction markets research. Ask natural-language questions and get structured, source-backed answers across SEC filings, earnings transcripts, company financials, stock & crypto market data, and prediction markets news & research. Built for investors, analysts, and researchers who need fast, cited intelligence.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/OctagonAI/octagon-mcp-server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/OctagonAI/octagon-mcp-server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/octagonai--octagon-mcp-server/badge.svg)](/listings/octagonai--octagon-mcp-server)

HTML

<a href="/listings/octagonai--octagon-mcp-server"><img src="/api/listings/octagonai--octagon-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Running on Claude Desktop

To configure Octagon MCP for Claude Desktop:

1. Open Claude Desktop 2. Go to Settings > Developer > Edit Config 3. Add the following to your `claude_desktop_config.json` (Replace `your-octagon-api-key` with your Octagon API key):

{
  "mcpServers": {
    "octagon-mcp-server": {
      "command": "npx",
      "args": ["-y", "octagon-mcp@latest"],
      "env": {
        "OCTAGON_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

4. Restart Claude for the changes to take effect

Running on Cursor

Configuring Cursor Desktop 🖥️ Note: Requires Cursor version 0.45.6+

To configure Octagon MCP in Cursor:

1. Open Cursor Settings 2. Go to Features > MCP Servers 3. Click "+ Add New MCP Server" 4. Enter the following: - Name: "octagon-mcp" (or your preferred name) - Type: "command" - Command: `env OCTAGON_API_KEY=your-octagon-api-key npx -y octagon-mcp`

> If you are using Windows and are running into issues, try `cmd /c "set OCTAGON_API_KEY=your-octagon-api-key && npx -y octagon-mcp"`

Replace `your-octagon-api-key` with your Octagon API key.

After adding, refresh the MCP server list to see the new tools. The Composer Agent will automatically use Octagon MCP when appropriate, but you can explicitly request it by describing your investment research needs. Access the Composer via Command+L (Mac), select "Agent" next to the submit button, and enter your query.

Running with npx

env OCTAGON_API_KEY=your_octagon_api_key npx -y octagon-mcp

Manual Installation

npm install -g octagon-mcp

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 23 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "octagon-local",
  3. "description": "Local marketplace for testing the Octagon Claude Code plugin from the octagon-mcp-server repository.",
  4. "owner": {
  5. "name": "Octagon AI",
  6. "url": "https://github.com/OctagonAI/octagon-mcp-server"
  7. },
  8. "plugins": [
  9. {
  10. "name": "octagon-market-intelligence",
  11. "description": "Skills-first Claude Code plugin for Octagon market intelligence, prediction market research, and financial analysis workflows.",
  12. "source": "./",
  13. "version": "1.1.0",
  14. "category": "finance",
  15. "tags": [
  16. "finance",
  17. "markets",
  18. "octagon",
  19. "prediction-markets"
  20. ]
  21. }
  22. ]
  23. }
README.md · README · 440 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Octagon: MCP for Public & Prediction Markets Intelligence
  2. [![smithery badge](https://smithery.ai/badge/@OctagonAI/octagon-mcp-server)](https://smithery.ai/server/@OctagonAI/octagon-mcp-server)
  3. ![Favicon](https://octagonai.co/docs/logo.svg) The Octagon MCP server provides specialized AI-powered financial research and analysis by integrating with the Octagon Market Intelligence API, enabling users to analyze and extract insights from public filings, earnings calls, financial metrics, stocks & crypto data, stock news, and prediction markets news & research within Claude Desktop and other popular MCP clients.
  4. [![Demo](https://octagonai.co/docs/financial_model_demo_fast.gif)](https://octagonai.co/docs/financial_model_demo.mp4)
  5. ## Tools
  6. ✅ `octagon-agent` orchestrates broad market intelligence analysis
  7. - Public market insights: SEC filings (10-K, 10-Q, 20-F, 8-K, S-1, 13-F, DEF 14A), earnings call transcripts
  8. - Stocks & crypto market data: stock trading, crypto trading data, news, press release, ownerships and holdings
  9. ✅ `octagon-deep-research-agent` for comprehensive deep research
  10. - Multi-source synthesis for investment research questions
  11. - Best for up-to-date, cross-source thematic analysis
  12. ✅ `octagon-podcasts-agent` for what investors said on podcasts
  13. - Cited answers from 70+ finance and business shows (Bloomberg, All-In, Odd Lots, Invest Like the Best, …)
  14. - Filters by time window, show, host, guest, company or ticker read from the question
  15. ✅ Prediction market research tooling
  16. - `octagon-prediction-markets-agent` for updated research reports on each prediction markets
  17. - `prediction_markets_history` for structured historical market data retrieval
  18. ✅ Live Octagon documentation access
  19. - `octagon-docs-search`, `octagon-docs-read`, `octagon-docs-list`, and `octagon-docs-refresh`
  20. - MCP resources for `octagon-docs://catalog`, `octagon-docs://status`, and `octagon-docs://page/{target}`
  21. ## Get Your Octagon API Key
  22. To use Octagon MCP, you need to:
  23. 1. Sign up for a free account at [Octagon](https://app.octagonai.co/signup/?redirectToAfterSignup=https://app.octagonai.co/api-keys)
  24. 2. After logging in, from left menu, navigate to **API Keys**
  25. 3. Generate a new API key
  26. 4. Use this API key in your configuration as the `OCTAGON_API_KEY` value
  27. ## Prerequisites
  28. Before installing or running Octagon MCP, you need to have `npx` (which comes with Node.js and npm) installed on your system.
  29. ### Mac (macOS)
  30. 1. **Install Homebrew** (if you don't have it):
  31. ```bash
  32. /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  33. ```
  34. 2. **Install Node.js (includes npm and npx):**
  35. ```bash
  36. brew install node
  37. ```
  38. This will install the latest version of Node.js, npm, and npx.
  39. 3. **Verify installation:**
  40. ```bash
  41. node -v
  42. npm -v
  43. npx -v
  44. ```
  45. ### Windows
  46. 1. **Download the Node.js installer:**
  47. - Go to [https://nodejs.org/](https://nodejs.org/) and download the LTS version for Windows.
  48. 2. **Run the installer** and follow the prompts. This will install Node.js, npm, and npx.
  49. 3. **Verify installation:**
  50. Open Command Prompt and run:
  51. ```cmd
  52. node -v
  53. npm -v
  54. npx -v
  55. ```
  56. If you see version numbers for all three, you are ready to proceed with the installation steps below.
  57. ## Installation
  58. ### Running on Claude Desktop
  59. To configure Octagon MCP for Claude Desktop:
  60. 1. Open Claude Desktop
  61. 2. Go to Settings > Developer > Edit Config
  62. 3. Add the following to your `claude_desktop_config.json` (Replace `your-octagon-api-key` with your Octagon API key):
  63. ```json
  64. {
  65. "mcpServers": {
  66. "octagon-mcp-server": {
  67. "command": "npx",
  68. "args": ["-y", "octagon-mcp@latest"],
  69. "env": {
  70. "OCTAGON_API_KEY": "YOUR_API_KEY_HERE"
  71. }
  72. }
  73. }
  74. }
  75. ```
  76. 4. Restart Claude for the changes to take effect
  77. ### Running on Cursor
  78. Configuring Cursor Desktop 🖥️
  79. Note: Requires Cursor version 0.45.6+
  80. To configure Octagon MCP in Cursor:
  81. 1. Open Cursor Settings
  82. 2. Go to Features > MCP Servers
  83. 3. Click "+ Add New MCP Server"
  84. 4. Enter the following:
  85. - Name: "octagon-mcp" (or your preferred name)
  86. - Type: "command"
  87. - Command: `env OCTAGON_API_KEY=your-octagon-api-key npx -y octagon-mcp`
  88. > If you are using Windows and are running into issues, try `cmd /c "set OCTAGON_API_KEY=your-octagon-api-key && npx -y octagon-mcp"`
  89. Replace `your-octagon-api-key` with your Octagon API key.
  90. After adding, refresh the MCP server list to see the new tools. The Composer Agent will automatically use Octagon MCP when appropriate, but you can explicitly request it by describing your investment research needs. Access the Composer via Command+L (Mac), select "Agent" next to the submit button, and enter your query.
  91. ### Running with npx
  92. ```bash
  93. env OCTAGON_API_KEY=your_octagon_api_key npx -y octagon-mcp
  94. ```
  95. ### Manual Installation
  96. ```bash
  97. npm install -g octagon-mcp
  98. ```
  99. ## Documentation
  100. For comprehensive documentation on using Octagon agents, please visit our official documentation at:
  101. [https://octagonai.co/docs/](https://octagonai.co/docs/)
  102. The documentation includes:
  103. - Detailed API references
  104. - Agent-specific query guidelines
  105. - Examples and use cases
  106. - Best practices for investment research
  107. For the latest hosted MCP client setup guide, see:
  108. - [Octagon MCP Server Guide](https://octagonai.co/docs/guide/mcp-server)
  109. - [Octagon Claude Plugin Guide](https://octagonai.co/docs/guide/claude-plugin)
  110. - [Octagon Agents Guide](https://octagonai.co/docs/guide/agents/)
  111. This MCP server also exposes the live docs corpus directly to MCP clients. Documentation access is fetched from the public Octagon docs LLM entry point at `https://octagonai.co/docs/llms.txt`; it does not use or transmit `OCTAGON_API_KEY`.
  112. ## Available Tools
  113. The MCP server currently exposes the following tools:
  114. ### Documentation Tools
  115. These tools expose live Octagon docs inside the MCP session. They work even before `OCTAGON_API_KEY` is configured, which makes them useful for setup, troubleshooting, and discovering the right Octagon agent or API workflow.
  116. #### `octagon-docs-list`
  117. Lists live docs sections and pages from the Octagon docs corpus.
  118. **Parameters**
  119. - `section` (string, optional): filter by docs section.
  120. - `source` (`docs`, `site`, or `all`, optional): defaults to the docs corpus.
  121. - `limit` (number, optional): maximum entries to return.
  122. #### `octagon-docs-search`
  123. Searches the Octagon API, agent, MCP, and plugin docs with source URLs and optional snippets.
  124. **Parameters**
  125. - `query` (string, required): search query.
  126. - `section` (string, optional): filter by docs section.
  127. - `source` (`docs`, `site`, or `all`, optional): defaults to the docs corpus.
  128. - `limit` (number, optional): maximum results to return.
  129. - `includeSnippets` (boolean, optional): include matched snippets in results.
  130. Example:
  131. ```text
  132. Search Octagon docs for Claude plugin connector setup.
  133. ```
  134. #### `octagon-docs-read`
  135. Reads one docs page or section as Markdown by title, URL, path, or catalog id.
  136. **Parameters**
  137. - `target` (string, required): docs title, URL, path, or catalog id.
  138. - `source` (`docs`, `site`, or `all`, optional): defaults to the docs corpus.
  139. - `maxChars` (number, optional): maximum Markdown characters to return.
  140. - `preferCachedContent` (boolean, optional): use the indexed docs corpus when available.
  141. Example:
  142. ```text
  143. Read the Octagon MCP server guide.
  144. ```
  145. #### `octagon-docs-refresh`
  146. Refreshes the in-memory docs catalog from the live LLM-friendly docs endpoints.
  147. **Parameters**
  148. - `includeSite` (boolean, optional): also refresh the broader `https://octagonai.co/llms.txt` site index.
  149. ### Documentation Resources
  150. Clients that support MCP resources can also browse:
  151. - `octagon-docs://catalog`: normalized live docs catalog.
  152. - `octagon-docs://status`: cache state, source endpoints, and refresh metadata.
  153. - `octagon-docs://page/{target}`: one docs page or section as Markdown.
  154. ### `octagon-agent`
  155. Orchestrates public and private market intelligence analysis.
  156. **Parameters**
  157. - `prompt` (string, required): natural language research request.
  158. - `conversation` (string, optional): existing Octagon conversation ID to continue a prior `octagon-agent` thread. Omit this on the first turn.
  159. - `newConversation` (boolean, optional): if `true`, starts a fresh Octagon thread for the active session/thread anchor. Recommended for the first turn of a brand new visible chat in top-layer hosts such as Claude Desktop.
  160. **Threaded usage**
  161. `octagon-agent` is the only MCP tool that forwards Octagon conversation threading. It is a stateful tool and expects session continuity. The MCP resolves session/thread state in this order:
  162. 1. stored conversation for MCP transport session identity, when the transport actually provides it
  163. 2. stored conversation for the server-managed default `stdio` session
  164. 3. explicit `conversation` can still override the active session conversation for that call
  165. This package currently runs as a `stdio` MCP server. In `stdio` mode, the server automatically establishes a process-local session for continuity across calls. Most local hosts such as Claude Desktop or Cursor can therefore use `octagon-agent` without supplying any extra threading fields for basic follow-up behavior.
  166. When a top-layer host knows a call is the first turn of a new visible chat, it should pass `newConversation: true`. That explicitly clears any stored Octagon thread for the active MCP session anchor before the call, which prevents stale continuity when a `stdio` host reuses the same long-lived MCP process across multiple visible chats.
  167. This means you can use any of these patterns:
  168. 1. First call: send only `prompt`
  169. 2. Let the MCP host preserve transport session continuity or rely on the default stdio session
  170. 3. Second call: either
  171. - send the new `prompt` in the same MCP session, or
  172. - keep using the same stdio MCP process, or
  173. - explicitly pass the previous `conversation`
  174. Transport session identity is the canonical continuity primitive for standards-compliant stateful MCP transports. For local `stdio` usage, the server-managed process session provides default continuity.
  175. Session identity and Octagon conversation identity are different concepts:
  176. - MCP session identity controls server-side continuity across tool calls
  177. - Octagon `conversation` controls the active Octagon thread inside that session
  178. The MCP result keeps the answer in `content`, and also returns structured metadata for orchestrators in `structuredContent`:
  179. ```json
  180. {
  181. "model": "octagon-agent",
  182. "text": "Which stock would you like the latest price for?",
  183. "conversation": "conv_123",
  184. "responseId": "resp_123",
  185. "followUp": {
  186. "required": true,
  187. "inputTemplate": "<ticker or company name>",
  188. "instructions": "Reply with just the missing detail and reuse the conversation value from this response."
  189. }
  190. }
  191. ```
  192. Explicit carry-forward example:
  193. ```json
  194. {
  195. "prompt": "AAPL",
  196. "conversation": "conv_123"
  197. }
  198. ```
  199. New visible chat example:
  200. ```json
  201. {
  202. "prompt": "Analyze Apple",
  203. "newConversation": true
  204. }
  205. ```
  206. Explicit refresh example:
  207. ```json
  208. {
  209. "prompt": "Start a fresh Octagon thread for this chat",
  210. "newConversation": true
  211. }
  212. ```
  213. **Stateful tool policy**
  214. - `octagon-agent`: stateful, uses a usable continuity anchor. In `stdio` hosts, that defaults to the server-managed process session unless you provide explicit `conversation`
  215. - other MCP tools: stateless and may run without session continuity
  216. Example:
  217. ```text
  218. Compare NVIDIA and AMD on latest quarterly revenue growth, margins, and management commentary.
  219. ```
  220. More examples:
  221. - "What were Amazon's revenue and net income figures in Q4 2023?"
  222. - "Analyze Tesla's R&D spending trends over the last 3 years."
  223. - "What guidance did NVIDIA's CEO provide regarding AI chip demand in their latest earnings call?"
  224. - "Compare the price-to-earnings, price-to-sales, and EV/EBITDA ratios for the top 5 semiconductor companies."
  225. - "What was Anthropic's latest funding round size, valuation, and key investors?"
  226. - "How many investments did Andreessen Horowitz make in AI startups in the last 12 months?"
  227. - "What are the latest news articles for NVIDIA stock from the past week?"
  228. ### `octagon-deep-research-agent`
  229. Performs comprehensive multi-source deep research and synthesis.
  230. **Parameters**
  231. - `prompt` (string, required): natural language research request.
  232. Example:
  233. ```text
  234. Research the impact of lower interest rates on late-stage private software valuations over the next 12 months.
  235. ```
  236. More examples:
  237. - "Extract all data fields from zillow.com/san-francisco-ca/"
  238. - "Research the financial impact of Apple's privacy changes on digital advertising companies' revenue and margins"
  239. - "Retrieve historical Bitcoin price data from 2023 and analyze the price volatility trends"
  240. - "Analyze the competitive dynamics in the EV charging infrastructure market"
  241. ### `octagon-podcasts-agent`
  242. Answers questions from what investors, strategists, operators and guests said on finance and business podcasts. Every claim cites the episode (show, title, date, link), and the answer ends with a `Sources:` list. Earnings calls are not podcasts: use `octagon-agent` for those.
  243. **Parameters**
  244. - `prompt` (string, required): natural language question. Put the time window, show, host, guest, company or ticker in the question; there are no separate filter parameters.
  245. Example:
  246. ```text
  247. What are podcast guests saying about NVDA since August?
  248. ```
  249. More examples:
  250. - "What did Chamath say about AI capex on All-In recently?"
  251. - "Summarize the last 3 episodes of Odd Lots."
  252. - "Which companies were podcasts discussing most last week?"
  253. - "How has podcast sentiment on Fed rate cuts changed since September?"
  254. ### `octagon-prediction-markets-agent`
  255. Research reports on Kalshi and Polymarket prediction markets, plus market search and edge screening across both venues.
  256. **Parameters**
  257. - `prompt` (string, required): a Kalshi market URL or event ticker, a Polymarket event URL or slug, or a natural-language question (which markets exist or are open for a topic, where the model disagrees with the price).
  258. - `cache` (boolean, optional): report mode for a single market.
  259. - omitted: `octagon-prediction-markets-agent`, the cached report if one exists, otherwise generate one.
  260. - `false`: `octagon-prediction-markets-agent:refresh`, force a fresh report (3 credits; Plus, Pro and Enterprise plans).
  261. - `true`: `octagon-prediction-markets-agent:cache`, read the cached report only; never generates; free. A question that names no market returns a structured JSON list of matching markets (`kind: "discovery"`).
  262. API errors (a missing or unresolved market reference, an ambiguous ticker, a closed market, a plan or credit limit) are returned as `Error [<code>]: <message>`.
  263. Examples:
  264. ```text
  265. Generate a report for the Kalshi market https://kalshi.com/markets/kxbtcy/btc-price-range-eoy/kxbtcy-27jan0100
  266. ```
  267. ```text
  268. Which Kalshi NBA game-winner markets are open tonight? (cache: true)
  269. ```
  270. ### `prediction_markets_history`
  271. Fetches historical data for a prediction market event ticker with optional pagination and time filters.
  272. **Parameters**
  273. - `event_ticker` (string, required)
  274. - `limit` (number, optional)
  275. - `cursor` (string, optional)
  276. - `captured_from` (string, optional)
  277. - `captured_to` (string, optional)
  278. - `include_analysis` (boolean, optional; when true, requests analysis columns)
  279. Example:
  280. ```text
  281. Fetch historical data for the Kalshi event https://kalshi.com/markets/kxbtcy/btc-price-range-eoy/kxbtcy-27jan0100
  282. ```
  283. ## Troubleshooting
  284. 1. **API Key Issues**: Ensure your Octagon API key is correctly set in the environment or config file.
  285. 2. **Connection Issues**: Make sure the connectivity to the Octagon API is working properly.
  286. 3. **Rate Limiting**: If you encounter rate limiting errors, reduce the frequency of your requests.
  287. ## License
  288. MIT
  289. ## Individual Specialized MCP Servers
  290. While this server provides comprehensive market intelligence combining all our specialized agents, you can also use our individual MCP servers for specific use cases:
  291. ### Research Tools
  292. - **[Octagon Deep Research MCP](https://github.com/OctagonAI/octagon-deep-research-mcp)** - Comprehensive research and web scraping capabilities
  293. ---
  294. ⭐ Star this repo if you find it helpful!

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.