Skip to content
Back to search

beyond-mcp

It's time to push beyond MCP Servers... Right?

Safety scan

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

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/disler--beyond-mcp/badge.svg)](/listings/disler--beyond-mcp)

HTML

<a href="/listings/disler--beyond-mcp"><img src="/api/listings/disler--beyond-mcp/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.

1. MCP Server

cp .mcp.testing .mcp.json

claude --mcp-config .mcp.json

prompt: "kalshi: get exchange status"

2. CLI

# or by agent
claude

prompt: "/prime_kalshi_cli_tools"

prompt: "kalshi: Get exchange status"

prompt: "kalshi: List events"

prompt: "kalshi: List events in JSON"

prompt: "kalshi: List events in JSON, limit 100"

# or by hand
cd apps/2_cli
uv sync
uv run kalshi status
uv run kalshi events
uv run kalshi events --json
uv run kalshi events --json --limit 100

3. File System Scripts

# by agent
claude

prompt: "/prime_file_system_scripts"

prompt: "kalshi: Get exchange status"

prompt: "kalshi: List events"

...

# or by hand
cd apps/3_file_system_scripts/scripts

uv run status.py

uv run *.py

4. Skill

cd apps/4_skill/

claude

prompt: "kalshi markets: Get exchange status"

prompt: "kalshi markets: search for events about 'best ai'" # Note this will trigger the cache build on first run which will take several minutes

...

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.

README.md · README · 376 lines

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

  1. # Beyond MCP
  2. > It's time to push beyond MCP Servers... Right?
  3. >
  4. > Let's breakdown real engineering trade offs between MCP, CLI, File System Scripts, and Skills based approaches for building reusable toolsets for your AI Agents.
  5. >
  6. > Watch the full video breakdown here: [Beyond MCP](https://youtu.be/OIKTsVjTVJE)
  7. ## Purpose of this Repo
  8. - MCP Servers are the standard way to build reusable toolsets for your AI Agents. But they are not the only way.
  9. - MCP Servers come with a massive cost - **instant context loss**.
  10. - When you have a single, or a few MCP Servers, this is not a big deal. But as you scale to many agents, many tools, and many contexts - this cost quickly becomes a bottleneck.
  11. - So what are the alternatives that big players are using to build powerful, reusable, context preserving toolsets for their AI Agents?
  12. _Here we explore 4 concrete approaches in this repo, all implementing access to Kalshi prediction market data._
  13. ## The 4 Approaches
  14. ![The 4 Approaches Revealed](images/NodeGraphLR-revealed.gif)
  15. ### `apps/1_mcp_server/` - MCP Server
  16. ![MCP Server Architecture](images/NodeGraphLR-mcp-server.gif)
  17. ### `apps/2_cli/` - CLI
  18. ![CLI Architecture](images/NodeGraphLR-cli.gif)
  19. ### `apps/3_file_system_scripts/` - File System Scripts
  20. ![File System Scripts Architecture](images/NodeGraphLR-scripts.gif)
  21. ### `apps/4_skill/` - Skill
  22. ![Agent Skill Architecture](images/NodeGraphLR-skills.gif)
  23. ## Quick Start
  24. ### 1. MCP Server
  25. ```bash
  26. cp .mcp.testing .mcp.json
  27. claude --mcp-config .mcp.json
  28. prompt: "kalshi: get exchange status"
  29. ```
  30. ### 2. CLI
  31. ```bash
  32. # or by agent
  33. claude
  34. prompt: "/prime_kalshi_cli_tools"
  35. prompt: "kalshi: Get exchange status"
  36. prompt: "kalshi: List events"
  37. prompt: "kalshi: List events in JSON"
  38. prompt: "kalshi: List events in JSON, limit 100"
  39. # or by hand
  40. cd apps/2_cli
  41. uv sync
  42. uv run kalshi status
  43. uv run kalshi events
  44. uv run kalshi events --json
  45. uv run kalshi events --json --limit 100
  46. ```
  47. ### 3. File System Scripts
  48. ```bash
  49. # by agent
  50. claude
  51. prompt: "/prime_file_system_scripts"
  52. prompt: "kalshi: Get exchange status"
  53. prompt: "kalshi: List events"
  54. ...
  55. # or by hand
  56. cd apps/3_file_system_scripts/scripts
  57. uv run status.py
  58. uv run *.py
  59. ```
  60. ### 4. Skill
  61. ```bash
  62. cd apps/4_skill/
  63. claude
  64. prompt: "kalshi markets: Get exchange status"
  65. prompt: "kalshi markets: search for events about 'best ai'" # Note this will trigger the cache build on first run which will take several minutes
  66. ...
  67. ```
  68. ## The 4 Approaches In Detail
  69. - `apps/1_mcp_server/` - MCP Server
  70. - `apps/2_cli/` - CLI
  71. - `apps/3_file_system_scripts/` - File System Scripts
  72. - `apps/4_skill/` - Skill
  73. ### 1. MCP Server (`apps/1_mcp_server/`)
  74. **Classic Model Context Protocol implementation**
  75. - ✅ **Standardized integration** - Works with any MCP-compatible client
  76. - ✅ **Tool discovery** - Auto-exposes 15 tools to LLMs
  77. - ✅ **Clean abstractions** - MCP protocol handles complexity
  78. - ❌ **Instant context loss** - Every tool call loses conversational context
  79. - ❌ **Wrapper overhead** - Delegates to CLI via subprocess
  80. **Architecture:**
  81. ```
  82. Claude/LLM → MCP Protocol → MCP Server → subprocess → CLI → Kalshi API
  83. ```
  84. **Key files:**
  85. - `server.py` - FastMCP server with 15 tool definitions
  86. - Wraps CLI commands in MCP tool interface
  87. - Each tool call is stateless
  88. **When to use:** Building tools for multiple LLM clients, need standardized protocol, context loss is acceptable.
  89. ---
  90. ### 2. CLI (`apps/2_cli/`)
  91. **Direct HTTP API access via command-line interface**
  92. - ✅ **Single source of truth** - Direct API calls, no wrappers
  93. - ✅ **Dual output modes** - Human-readable or pure JSON
  94. - ✅ **Smart caching** - Pandas-based search with 6-hour TTL
  95. - ✅ **Minimal overhead** - Direct httpx calls, no SDK
  96. - ✅ **Improved Context** - Agent reads ~half as much context as the MCP Server
  97. **Architecture:**
  98. ```
  99. Claude → subprocess → CLI (13 commands) → Direct HTTP → Kalshi API
  100. ```
  101. **Key files:**
  102. - `kalshi_cli/cli.py` - All 13 commands (552 lines)
  103. - `kalshi_cli/modules/client.py` - HTTP client & search cache
  104. - `kalshi_cli/modules/formatting.py` - Output formatters
  105. **When to use:** Need direct API control, want both CLI and programmatic access, caching important, okay with subprocess overhead.
  106. ---
  107. ### 3. File System Scripts (`apps/3_file_system_scripts/`)
  108. **Progressive disclosure via standalone scripts**
  109. - ✅ **Progressive disclosure** - Only load scripts you need (~200-300 lines each)
  110. - ✅ **Complete isolation** - Each script is fully self-contained
  111. - ✅ **Zero dependencies** - HTTP client embedded in each script
  112. - ✅ **Context efficient** - Agent only reads relevant scripts
  113. - ⚠️ **Code duplication** - HTTP client repeated in each script
  114. - ⚠️ **No shared state** - Cache and utilities duplicated
  115. **Architecture:**
  116. ```
  117. Claude → Read tool → Individual script → Embedded HTTP client → Kalshi API
  118. ```
  119. **Available scripts (10):**
  120. - `status.py` - Exchange operational status
  121. - `markets.py` - Browse markets with filters
  122. - `market.py` - Detailed market information
  123. - `orderbook.py` - Bid/ask depth
  124. - `trades.py` - Recent trading activity
  125. - `search.py` - Keyword search (with caching)
  126. - `events.py` - List event collections
  127. - `event.py` - Event details
  128. - `series_list.py` - Browse all ~6900 series
  129. - `series.py` - Series information
  130. **When to use:** Context preservation critical, want progressive disclosure, okay with code duplication, need standalone portability.
  131. ---
  132. ### 4. Skill (`apps/4_skill/.claude/skills/kalshi-markets/`)
  133. **Claude Code Agent Skills with embedded scripts**
  134. - ✅ **Model-invoked** - Claude autonomously decides when to use
  135. - ✅ **Progressive disclosure** - Same scripts as approach #3
  136. - ✅ **Team sharing** - Commit to git for team access
  137. - ✅ **Discovery** - Description triggers automatic activation
  138. - ✅ **Context preservation** - Agent reads only what's needed
  139. - ⚠️ **Claude Code specific** - Only works in Claude Code
  140. - ⚠️ **Learning curve** - Requires understanding Skill system
  141. **Architecture:**
  142. ```
  143. Claude (detects trigger) → Loads SKILL.md → Runs scripts → Kalshi API
  144. ```
  145. **Structure:**
  146. ```
  147. .claude/skills/kalshi-markets/
  148. ├── SKILL.md (concise description & instructions)
  149. └── scripts/ (copies of all 10 file system scripts)
  150. ```
  151. **When to use:** Using Claude Code, want automatic skill discovery, team collaboration via git, need context preservation with progressive disclosure.
  152. ---
  153. ## My Approach ([IndyDevDan](https://www.youtube.com/@indydevdan))
  154. ### External Tools
  155. 1. 80% Just use **MCP servers**. Don't overthink it.
  156. 2. 15% **CLI** - If you need modify, extend, or control tools and context.
  157. 3. 5% **Scripts or Skills** - For serious context preservation, portability or ecosystem reuse
  158. ### New Tools
  159. 1. 80% Just use **CLI** + Prime Prompt (works for you, your team and your agents).
  160. 2. 10% Wrap in **MCP Server** when I need multiple agents at scale - and don't want to add 'another' thing for my agents to focus on.
  161. 3. 10% **Scripts or Skills** - For serious context preservation, portability or ecosystem reuse.
  162. ## Key Technical Details
  163. **API Access:**
  164. - Base URL: `https://api.elections.kalshi.com/trade-api/v2`
  165. - No authentication required (read-only public data)
  166. - ~6900 market series available
  167. **Search Caching:**
  168. The Kalshi API doesn't provide a native search endpoint, which creates a challenge for finding markets by keyword. Our solution: intelligent local caching.
  169. - **The Problem:** No API search endpoint means we'd need to paginate through thousands of markets on every search
  170. - **The Solution:** Build a complete local cache once, then search instantly using pandas
  171. - **First run:** 2-5 minutes to fetch all ~6900 markets and build cache
  172. - **Subsequent searches:** Instant (searches cached pandas DataFrame)
  173. - **Cache location:** `.kalshi_cache/` at project root (shared across CLI and scripts)
  174. - **TTL:** 6 hours (auto-refresh when stale)
  175. - **Search scope:** Searches titles, subtitles, tickers, series names, and descriptions
  176. **Why the delay matters:**
  177. - First search in a session will take 2-5 minutes while the cache builds
  178. - Users will see progress messages during cache building
  179. - After initial build, searches are instant for 6 hours
  180. - This trade-off enables comprehensive keyword search across ALL markets instead of just the first 100-500 results from paginated API calls
  181. **Path Resolution:**
  182. - All scripts use absolute path resolution via `Path(__file__).resolve()`
  183. - Works correctly when invoked from any directory
  184. - Cache always resolves to project root
  185. ## Trade-off Comparison
  186. | | MCP | CLI | Scripts | Skills |
  187. | ------------------------------ | -------------------------------------------------------------------------------- | ------------------------------ | ------------------------------ | --------------------------------- |
  188. | **Agent Invoked** | Yes | No | No | Yes |
  189. | **Context Window Consumption** | High | Medium (Depends) | Low (w/incr) | Low (w/incr) |
  190. | **Customizable** | No (unless you own) | Yes | Yes | Yes |
  191. | **Portability** | Low | Medium | High | High |
  192. | **Composability** | Yes (MCP Prompts) | Yes but requires local prompts | Yes but requires local prompts | Yes but requires local prompts |
  193. | **Simplicity** | High | Medium | Medium | Medium |
  194. | **Engineering Investment** | Low if external, Medium if custom | Medium | Medium | Low if external, Medium if custom |
  195. | **Feature Set** | Tools, Resources, Prompts, Elicitation, Completion, Sampling, Logging, Auth. etc | Whatever you build | Whatever you build | Whatever you build |
  196. ### Key Insights
  197. **Context Window Consumption:**
  198. - **MCP & CLI** consume full context on every tool call
  199. - **Scripts & Skills** use progressive disclosure - only load what's needed
  200. **Agent Invoked:**
  201. - **MCP & Skills** are automatically triggered by Claude based on context
  202. - **CLI & Scripts** require explicit agent decision to use
  203. **Customizable:**
  204. - **MCP** is locked unless you own/fork the server
  205. - **CLI, Scripts, Skills** are fully under your control
  206. **Portability:**
  207. - **Scripts & Skills** are most portable (just Python files)
  208. - **CLI** requires installation but works anywhere
  209. - **MCP** needs MCP-compatible client setup
  210. ## When to Use Each Approach
  211. ### Choose MCP Server if:
  212. - Building for multiple LLM clients (not just Claude)
  213. - Need standardized tool protocol
  214. - Context loss per call is acceptable
  215. - Want automatic tool discovery across clients
  216. - Using external MCP servers you don't control
  217. ### Choose CLI if:
  218. - Need both human CLI and programmatic access
  219. - Want single source of truth for API logic
  220. - Direct HTTP control is important
  221. - Willing to accept subprocess overhead
  222. - Building general-purpose tooling
  223. ### Choose File System Scripts if:
  224. - Context preservation is critical
  225. - Want maximum portability (just Python + httpx)
  226. - Need progressive disclosure (minimize token usage)
  227. - Okay with code duplication for isolation
  228. - Building one-off integrations
  229. ### Choose Skill if:
  230. - Using Claude Code (and the ecosystem) specifically
  231. - Want autonomous skill discovery
  232. - Team collaboration via git is important
  233. - Need context preservation + progressive disclosure
  234. - Building reusable team capabilities
  235. ## Project Structure
  236. ```
  237. beyond-mcp/
  238. ├── apps/
  239. │ ├── 1_mcp_server/ # MCP Server implementation
  240. │ │ ├── server.py # 15 MCP tools wrapping CLI
  241. │ │ └── README.md
  242. │ ├── 2_cli/ # CLI implementation
  243. │ │ ├── kalshi_cli/
  244. │ │ │ ├── cli.py # 13 commands (552 lines)
  245. │ │ │ └── modules/ # HTTP client, cache, formatters
  246. │ │ └── README.md
  247. │ ├── 3_file_system_scripts/ # Progressive disclosure scripts
  248. │ │ ├── scripts/ # 10 standalone scripts
  249. │ │ │ ├── status.py
  250. │ │ │ ├── markets.py
  251. │ │ │ ├── market.py
  252. │ │ │ ├── orderbook.py
  253. │ │ │ ├── trades.py
  254. │ │ │ ├── search.py
  255. │ │ │ ├── events.py
  256. │ │ │ ├── event.py
  257. │ │ │ ├── series_list.py
  258. │ │ │ └── series.py
  259. │ │ └── README.md
  260. │ └── 4_skill/ # Claude Code Skill
  261. │ └── .claude/skills/kalshi-markets/
  262. │ ├── SKILL.md # Skill description & instructions
  263. │ └── scripts/ # Same 10 scripts as #3
  264. └── .kalshi_cache/ # Shared cache directory (CLI & scripts)
  265. ```
  266. ## Resources
  267. - [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
  268. - [Claude Code Skills Documentation](https://docs.claude.com/en/docs/agents-and-tools/agent-skills)
  269. - [Kalshi API Documentation](https://docs.kalshi.com/)
  270. - [FastMCP Framework](https://github.com/jlowin/fastmcp)
  271. ## Master **Agentic Coding**
  272. > Prepare for the future of software engineering
  273. Learn tactical agentic coding patterns with [Tactical Agentic Coding](https://agenticengineer.com/tactical-agentic-coding?y=byndmcp).
  274. Follow the [IndyDevDan YouTube channel](https://www.youtube.com/@indydevdan) to improve your agentic coding advantage.

Ratings and comments

Sign in to rate this skill.

Sign in

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