
![Three figures in a dark, Sandman-esque realm - The Skill Dealer, The Nuclear Football, and Codey C. Maude - standing before swirling constellations of MCP tool connections](/images/progressive-discovery/banner.webp)

> *They asked the three: "Why are there three of you? Isn't one enough?"*

*This is Part 5 of the Progressive Discovery in MCP series. See* [*Part 1*](/blog/progressive-discovery-in-mcp-part-1)*,* [*Part 2*](/blog/progressive-discovery-in-mcp-part-2)*,* [*Part 3*](/blog/progressive-discovery-in-mcp-part-3)*, and* [*Part 4*](/blog/progressive-discovery-in-mcp-part-4)*.*

I've spent four posts going deep on each tier. Now I want to step back and be honest about what this actually is, where I think it matters, and what's left to do.

## Why three and not one

The three tiers exist because there are three fundamentally different shapes of work an agent does with tools:

**Procedural** - "do the canonical thing." There's a known workflow with known steps. PR review, issue triage, release prep. This is where skills shine. The skill encodes the ceremony. The model doesn't have to reinvent the recipe.

**Investigative** - "I don't know what I'm looking for yet." Ad-hoc exploration, spot-checking, poking around a server you haven't used before. This is where tool-cli shines. Shell pipes, jq filters, for loops. Zero ceremony, maximum flexibility.

**Reductive** - "turn N items into 1 summary." Pagination, aggregation, joins, math. The intermediate data is large but the answer is small. This is where Code Mode shines. The model writes code, V8 runs it, only the result enters context.

Most tasks are one of these. Some are two. The interesting ones are all three - like preparing release notes, where you follow the release workflow (skill), aggregate 150 PRs into a summary (Code Mode), then investigate the weird ones that don't fit the pattern (tool-cli). The tiers aren't competing. They're handling different shapes.

## The architecture that makes composition work

The reason these compose cleanly is that all three route through the same harness:

```mermaid
flowchart TD
    subgraph mcpi["mcpi (agent)"]
        T1["load_skill\n(Tier 1 - Skills)"]
        T2["tool-cli\n(Tier 2 - Football)"]
        T3["code_search / code_execute\n(Tier 3 - Code Mode)"]
        MCM["McpClientManager\n(MCP SDK)"]
        T1 --> MCM
        T2 --> MCM
        T3 --> MCM
    end
    MCM --> S1["MCP Server"]
    MCM --> S2["MCP Server"]
```

One audit trail. One place to add human-in-the-loop. One place to check tool annotations. One place to rate-limit. The model switches between tiers mid-task and the observability doesn't change. This is the part of my design that matters most for real production use. It's also the part most competing implementations have neglected, because they don't try to change the harness and build around it. Harness developers - do better!

## What this is and what it isn't

This is a proof of concept. I built it to move the conversation forward, not to ship a production system. [mcpi-ext](https://github.com/SamMorrowDrums/mcpi-ext) is experimental. The [skills-as-groups spec proposal](https://github.com/modelcontextprotocol/experimental-ext-grouping/pull/13) is a draft. The structured output work on the [GitHub MCP Server](https://github.com/github/github-mcp-server/pull/2382) is a PR, not a release.

But the design works. I've used it. The three tiers genuinely handle different situations better than any single approach, and the harness routing genuinely provides observability and security across all of them.

## What's left to do

There's a lot. I don't want to pretend this is finished.

**Skills need server adoption.** The mechanism only works if MCP servers ship `skill://` resources. That requires server developers to think about their tools in terms of user workflows, write good skill bodies, and test coverage. I've started doing this on the GitHub MCP Server ([PR #2382](https://github.com/github/github-mcp-server/pull/2382) adds twenty-seven skills replacing the old server instructions), but one server isn't an ecosystem. If you build MCP servers, the [server developer guide](https://github.com/SamMorrowDrums/mcpi-ext/blob/main/docs/server-developer-guide.md) covers the format and best practices. Your input on the [spec proposal](https://github.com/modelcontextprotocol/experimental-ext-grouping/pull/13) matters.

**Structured output enables the other two tiers.** tool-cli returns JSON that flows through pipes - but without `outputSchema`, clients don't know the shape ahead of time. Code Mode requires typed responses to let models write `.filter()` and `.map()` confidently. That same PR on the GitHub MCP Server adds `OutputSchema` and `StructuredContent` to read-only tools like `list_issues`, `search_code`, and `get_me`. Multi-method tools like `issue_read` (which returns different shapes per method) stay untyped for now - a single output schema can't represent a union. But for the tools where it works, structured output is what makes progressive discovery practical rather than theoretical. It's an underused MCP feature that becomes essential here.

**Human-in-the-loop needs real work.** The harness provides the choke point. The annotations exist. But the actual UX of confirmation prompts needs to be good enough that users don't just turn everything off out of fatigue. Real security is nuanced - not "confirm everything" or "YOLO mode" with nothing in between.

**Code Mode eligibility is narrow.** Right now it's restricted to read-only tools with structured output. That's the safe starting point, but it limits what Code Mode can do. Expanding to write operations with HITL gating is possible - the harness architecture supports it - but the policy decisions are hard.

**Discovery is still imperfect.** Skills advertise intent cheaply, but the model still has to decide which skill to load. tool-cli requires the model to think "there might be a tool for this." Neither is as seamless as just having the right tool appear at the right moment. There's more work to be done on making discovery feel invisible.

**Client builders need to implement this.** The MCP CLI and Code Mode patterns can be done today by anyone building agent harnesses. They don't require spec changes. Skills require `skill://` resources from servers, but the client-side implementation is straightforward. The protocol supports almost all of this already, but the dust is still settling on an official extension, never mind self-declaring tools for progressive discovery which is a novel layer.

If you build an agent harness, here's what I'd ask you to try:

- **Skill-gated tool loading.** Discover `skill://` resources on connection, register their tools as deferred, and expose a `load_skill` tool. The model gets workflow instructions and tool access in one atomic operation. Both Anthropic and OpenAI support `defer_loading` natively, and a `tool_call` hook handles providers that don't.
- **An MCP CLI that routes through the harness.** Give the model a shell command that speaks to your MCP connections via JSON-RPC on localhost. Every call goes through one choke point. You get progressive discovery, shell composability, and a single place for audit logging and HITL gating. The thin wrapper pattern means the CLI is tiny - the harness does the real work.
- **A Code Mode sandbox for read-only tools with `outputSchema`.** Let the model write code that chains tool calls in an isolate. Only the computed result enters context. This is where the biggest context savings come from, and it requires no spec changes at all - just a V8 sandbox and a callback bridge to your MCP client.

None of these are huge engineering efforts individually. The [mcpi-ext source](https://github.com/SamMorrowDrums/mcpi-ext) is public and can serve as a reference implementation.

## The bigger point

I started this series responding to the argument that MCP isn't needed. I think the real issue is that nobody had shown what MCP looks like when you apply context engineering to it. Progressive discovery isn't a research problem. The pieces exist: `defer_loading` in the model APIs, tool annotations in MCP, `outputSchema` for structured output, resources for skills. The work is implementation, not invention.

MCP will keep evolving. Models will get better at tool selection. Context windows will grow. Maybe one day the whole progressive discovery question becomes irrelevant because attention is free. But we're not there yet, and in the meantime, the agents that work best will be the ones whose harnesses are smart about what they reveal and when.

The [mcpi-ext source](https://github.com/SamMorrowDrums/mcpi-ext) is public. The [skills-as-groups spec proposal](https://github.com/modelcontextprotocol/experimental-ext-grouping/pull/13) needs community input. If you build something on top of any of this, or if you disagree with any of it, I'd love to hear about it.

> *"Three is not redundancy," said the Skill Dealer. "Three is completeness."*
---

*Have thoughts on this article or progressive discovery in MCP in general? I opened a [discussion on GitHub](https://github.com/SamMorrowDrums/cv/discussions/63) for this series.*


Three Is Not Redundancy


![A luminous figure composed of flowing code, sitting cross-legged in a V8 isolate bubble, reading structured data from floating JSON schemas](/images/progressive-discovery/code-c-maude.webp)

> *Code flows in, data flows out as Codey sits in isolation, trapped in his eternal sandbox*

*This is Part 4 of the Progressive Discovery in MCP series. See* [*Part 1*](/blog/progressive-discovery-in-mcp-part-1)*,* [*Part 2*](/blog/progressive-discovery-in-mcp-part-2)*, and* [*Part 3*](/blog/progressive-discovery-in-mcp-part-3)*.*

While experimenting with Code Mode, I asked an agent to scan every issue on `github/github-mcp-server` and build a label distribution. 876 issues across 9 paginated calls - roughly 5 MB of JSON. None of it entered the model's context. Only the ASCII histogram came back, about 1KB.

That is impossible with standard tool calling, where responses are traditionally sent directly to the model one by one, leaving the model to assemble the end result too. Done the old-fashioned way, that wouldn't just be impossible at this scale, it would also be extremely slow.

This whole series has been about reducing context wastage, reducing model roundtrips, and making agents more effective. Code Mode is undeniably an excellent way to extract those benefits for MCP.

After [Part 1](/blog/progressive-discovery-in-mcp-part-1), Mario Zechner pushed back with a line that captures the problem well:

> *Of all the supposed problems with MCP, pipelining and keeping transforms out of context is the only one that really matters.*

I agree, I think there are some tools where the results do need to always go direct to the model, but intermediate data should never touch the context window and certainly not in its entirety. Code Mode definitely fulfils that goal. tool-cli ([Part 3](/blog/progressive-discovery-in-mcp-part-3)) is another. Both rest on the same idea - an agent's transcript should grow with the size of its conclusions, not the size of the data it had to look at to reach them.

Here's the actual script the model wrote, running inside the sandbox in [mcpi](https://github.com/SamMorrowDrums/mcpi-ext):

```javascript
const allIssues = [];
let page = 1;
while (true) {
  const result = await codemode.list_issues({
    owner: "github", repo: "github-mcp-server",
    state: "ALL", perPage: 100, page
  });
  allIssues.push(...result.issues);
  if (result.issues.length < 100) break;
  page++;
}

const labelCounts = {};
for (const issue of allIssues) {
  for (const label of issue.labels) {
    labelCounts[label] = (labelCounts[label] || 0) + 1;
  }
}

return Object.entries(labelCounts)
  .sort((a, b) => b[1] - a[1])
  .map(([label, count]) => ({ label, count }));
```

Done as nine classical tool calls, that transcript carries nine \~500KB JSON blobs the model has to attend over on every subsequent turn. When you need the precise data context window compaction cannot be used, so the agent can only succeed at this task if it has enough context window available to succeed.

Models generally degrade as the context window fills up (in speed, staying on track and in retaining/acting on all prior information). Executed as code, the intermediate data lives and dies inside the ephemeral runtime. The transcript grows with O(answer), not O(data fetched), and data fetched can be exponentially bigger, especially with data aggregations. That's the true power of Code Mode. Behold:

![Code Mode in action - 876 issues scanned, label histogram returned](/images/progressive-discovery/code-mode-histogram.png)

## Standing on the shoulders of giants

The pattern isn't mine. Cloudflare's Kenton Varda and Sunil Pai introduced ["Code Mode" in September 2025](https://blog.cloudflare.com/code-mode/), arguing that LLMs are vastly better at writing code than at calling tools because they have seen vastly more code in training. Anthropic shipped [Programmatic Tool Calling in November 2025](https://www.anthropic.com/engineering/advanced-tool-use), running Claude-authored Python in a managed `code_execution` container alongside its sister features Tool Search Tool and Tool Use Examples. Their companion post, [code execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp), reports a 98.7% token reduction on a Google Drive → Salesforce example by exposing tools as a TypeScript filesystem rather than as direct calls. Cloudflare's Matt Carey [followed up](https://blog.cloudflare.com/code-mode-mcp/) in February 2026, putting an entire API in front of an agent in roughly 1,000 tokens via two tools: `search()` and `execute()`.

[mcpi](https://github.com/SamMorrowDrums/mcpi-ext)'s version is a sketch by comparison. Cloudflare's runs in production on Workers; Anthropic's runs at scale across the Claude API. I borrowed liberally from both. What I'm trying to show is not just the potential of Code Mode for progressive discovery and output token efficiency, but also that HITL and audit trail can and must be implementable via the harness itself.

## Every call still goes through the harness

That said, I'm not just trying to show the potential of Code Mode for progressive discovery and output token efficiency. Effective HITL and a real audit trail demand that the actual tool calls go via the harness itself. Without that, we're back in YOLO mode territory, and we can certainly do better.

Here is the part I care about. In [mcpi](https://github.com/SamMorrowDrums/mcpi-ext) the sandbox has no network. It cannot reach GitHub. When the model writes:

```javascript
const issues = await codemode.list_issues({ owner, repo, state: "ALL", page });
```

`codemode.list_issues` is a *stub*. The actual MCP request happens in the harness process, dispatched through the same MCP connection that handles tool-cli and skill-gated tools. The sandbox sends a request through an [`isolated-vm`](https://github.com/laverdet/isolated-vm) `Reference` callback; the harness fulfils it and returns the typed result. The audit log still shows nine `list_issues` calls with their inputs and outputs. Rate limits still apply. HITL hooks could still fire on individual operations.

This is the difference between *the agent ran a 60-line script and stuff happened* and *the agent ran a 60-line script that made nine auditable MCP calls, and here they are*. It is the same harness-as-choke-point argument I made in [Part 1](/blog/progressive-discovery-in-mcp-part-1), applied to a runtime for code execution. Code Mode without that property is a bit too much like an unsafe `eval()` for my liking, where you lose accountability, and the ability to intercept mid-flow.

## Eligibility, and why structured outputs are not optional

Two conditions in [mcpi](https://github.com/SamMorrowDrums/mcpi-ext):

1. **`readOnlyHint: true`** - the tool can't mutate anything. You could trivially extend Code Mode to write tools, but I'd want a HITL gate first, and that wasn't in scope for this experiment.
2. **`outputSchema` defined** - the tool returns typed, machine-parseable structured output.

The second condition is the more interesting one. A Code Mode that takes `Out = any` is not really Code Mode. The model can't write `.filter(i => i.state === "OPEN")` if it doesn't know `state` exists. **Structured outputs are the precondition.** Code Mode is one of the strongest arguments for shipping `outputSchema` on every read tool you can.

This is why [PR #2382 on the GitHub MCP Server](https://github.com/github/github-mcp-server/pull/2382) added `OutputSchema` and `StructuredContent` to read-only tools like `list_issues`, `search_code`, `list_pull_requests`, and `get_me`. Backwards compatible with old clients, machine-parseable for new ones, and eligible for Code-Mode which is likely worth the hassle of implementing this.

In a pre progressive discovery world we consolidated tools in GitHub MCP. Multi-method tools like `issue_read` (with `get`, `get_comments`, `get_sub_issues`, `get_labels`, each returning a different shape) can't meaningfully expose a single `outputSchema` so we would likely revisit these type of choices in a world where clients did more imaginative things to context engineer with MCP, such as implementing Code Mode. As I noted in [Part 2](/blog/progressive-discovery-in-mcp-part-2), consolidating tools is a workaround for the lack of progressive discovery, not a design preference. With progressive discovery in place, you'd probably ship granular tools again, each with output schemas and a distinct purpose.

## The runtime is incidental

V8 isolate is what I had handy because the extension is JavaScript. The pattern doesn't depend on it. Anthropic's Programmatic Tool Calling runs Python inside a [managed code execution tool](https://docs.claude.com/en/docs/agents-and-tools/tool-use/code-execution-tool). [Pydantic AI](https://ai.pydantic.dev) is also an excellent option, pair it with [RestrictedPython](https://github.com/zopefoundation/RestrictedPython), [Pyodide](https://pyodide.org), or a container runner and you have the Python flavour of the same idea. Cloudflare runs TypeScript on Workers isolates. Pick whichever sandbox-and-language combination works best in your evals if you're a harness engineer.

What matters is the shape:

- The tool stubs in the sandbox don't do real work. They dispatch back to the harness.
- The sandbox itself has no network or filesystem of its own.
- Intermediate data lives in the sandbox and dies there (admittedly some designs also allow for resuming the same sandbox with some persistent state - no strong opinion there).
- Only the final, computed value crosses back into the model's context.

## The granularity argument

[Cloudflare's two-tool design](https://blog.cloudflare.com/code-mode-mcp/) - `search()` and `execute()` - is a genuinely good call when the underlying API surface is in the *thousands* of endpoints. Cloudflare's own APIs across DNS, Workers, R2, Zero Trust, Images, etc. could not fit their definitions in any context window even with aggressive trimming, and Anthropic's [Tool Search Tool](https://www.anthropic.com/engineering/advanced-tool-use) is responding to the same scale problem from the model side. Collapsing is the only honest move at that size, and it's interesting to see what possibilities exist for exposing such expansive tools to an agent without blowing its context window.

The only problem I have with this is that we want the annotations and things respected as per regular MCP implementation, and that's why I think it's not optional to make the tool calls go via the same control point as they would in a more conventional MCP setup. Things I want to see in any serious solution:

- **Per-tool annotations.** MCP defines `readOnlyHint`, `destructiveHint`, `idempotentHint` so clients can make safety decisions per operation. Inside an `execute(blob)` design, those annotations don't apply to anything specific, unless they are routed individually through the harness.
- **Per-tool observability.** *Which endpoint did the agent call, and how often?* is a useful question. Reading it off a stream of MCP requests is easier than parsing it out of generated code.
- **Per-tool HITL.** *Are you sure you want to delete this?* is impossible to ask when the delete is line 47 of a script that's already running - if the tool connection is on the server side, and doesn't route back through the harness.

## On the sandbox

A real-world sandbox is a serious piece of infrastructure. I am very explicitly not building one. [mcpi](https://github.com/SamMorrowDrums/mcpi-ext) uses [`isolated-vm`](https://github.com/laverdet/isolated-vm) (V8 isolates: 128MB memory cap, 30s timeout, \~15ms startup, no FS, no network, no Node APIs); Node's built-in `vm` module is [documented as not a security mechanism](https://nodejs.org/api/vm.html#vm-executing-javascript) and is escapable via prototype tricks. Cloudflare runs code in [Workers isolates](https://blog.cloudflare.com/code-mode/) with sub-millisecond startup. Anthropic runs code in their own managed container. They have whole teams and budgets for this. If you're going to ship Code Mode, run on someone else's sandbox.

## The honest foible

Code Mode and progressive discovery share a flaw. The agent always starts from scratch. Every session it has to ask *what tools exist?*, *what shapes do they take?*, *which one fits this job?* - and sometimes it doesn't know what to ask, or doesn't realise a relevant capability is even available. The honest tell is what users do to compensate: they name things explicitly. \*Use the `list_pull_requests` tool. Run the review-pr skill.\* That works, and I do it too. But it's a copout against the agentic dream where intent translates straight to action, with the human never **having** to know the implementation. I would still recommend thinking and understanding as much as humanly possible though. Be augmented, not replaced.

I don't think that dream goes away. I think it gets pushed up the stack. Skills ([Part 2](/blog/progressive-discovery-in-mcp-part-2)) name *workflows* rather than tools - *review this PR* is closer to intent than \*call `pull_request_read` then `add_comment_to_pending_review`\*. Tool search and tool-cli help the agent discover by itself. None of these are full solutions. All of them push the line a little further. For now, "the agent sometimes needs nudging" is just an honest part of the system, not a bug to hide.

## Generative UI is the other payoff

The token savings are the obvious win. The less obvious one is what you can *do* with the structured output once it's in the sandbox.

If the model can write code over typed tool results, it can also generate visualisations, dashboards, and small applications instead of returning text. Combine Code Mode with the [MCP Apps extension](https://github.com/modelcontextprotocol/ext-apps) (SEP-1865, the official Anthropic/OpenAI-led UI extension to MCP, evolved from the [MCP-UI](https://mcpui.dev/) community work) and the agent can render an interactive chart of that 876-issue label distribution rather than describe it in prose. My friend Ruben Casas (Postman) gave [a great talk on this at AI Engineer Europe](https://www.youtube.com/watch?v=hCMrEfPG2Yg) - *Beyond Components: Designing Generative UI for MCP Apps* - covering double-iframe sandboxing, the declarative-to-generative spectrum, and the case for shared-canvas superapps over one-off chat UIs. We are only scratching the surface here.

That points at the version of agents I find most interesting: not the lights-out autonomous worker that runs unsupervised, but the cyborg (again: we should seek to be augmented not replaced). Human in the loop isn't a degradation of agentic systems. It's the only version of them that avoids the darkest timeline.

## Why it matters

Code Mode is the pipelining payoff. tool-cli ([Part 3](/blog/progressive-discovery-in-mcp-part-3)) does the same trick at the shell level - bash composition keeps intermediate data out of model context - but loops and aggregations get awkward in pure pipes. Skills ([Part 2](/blog/progressive-discovery-in-mcp-part-2)) decide which tools are *visible* to the model; Code Mode decides what happens to the *data those tools produce*. while still avoiding the up-front cost of tool schemas.

If there is one thing I want this article to leave with you, it's this: an agent's transcript should grow with the size of its conclusions, not the size of the data it had to look at to reach them. Pipelining is the engineering pattern that gets you there. Structured outputs are what makes pipelining less error prone. Progressive discovery is what makes it scale. Code Mode is one shape of pipeline; MCP CLIs are another. Both are methods for keeping the model's context window for reasoning, not for data.

## Try it yourself

If you went through the [Part 1 setup](/blog/progressive-discovery-in-mcp-part-1#try-it-yourself), [Part 2 setup](/blog/progressive-discovery-in-mcp-part-2#try-it-yourself), or [Part 3 setup](/blog/progressive-discovery-in-mcp-part-3#try-it-yourself), you already have everything you need. [mcpi](https://github.com/SamMorrowDrums/mcpi-ext) ships Code Mode as a built-in tier alongside Skills and tool-cli.

### 1. Install

```sh
npm install -g @sammorrowdrums/mcpi@latest @sammorrowdrums/mcpi-ext@latest @sammorrowdrums/tool-cli@latest
```

### 2. Point it at any MCP server

Reuse the `~/.config/mcpi-ext/mcp.json` from earlier parts, or start with the GitHub MCP server (Code Mode needs `outputSchema` on the tools you want to chain, which the `skill-discovery` tag provides):

```json
{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server:skill-discovery",
        "stdio"
      ],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token-here" }
    }
  }
}
```

### 3. Run mcpi

```sh
mcpi --extension $(npm root -g)/@sammorrowdrums/mcpi-ext/dist/index.js \
  --mcp-config ~/.config/mcpi-ext/mcp.json
```

### 4. Ask for something that needs computation across many calls

Pagination loops, aggregations, joins. The kind of thing that would otherwise drag every page into context:

> *"Across all issues in github/github-mcp-server, build me a histogram of label usage."*

Watch the log: the model calls `code_search` to find the eligible read-only tools, then `code_execute` with a script that loops, aggregates, and returns a tiny result. The pages of JSON never enter its context.

## For harness builders: a note on implementation

Code Mode in [mcpi](https://github.com/SamMorrowDrums/mcpi-ext) is a thin runtime built on three boring pieces:

- **A V8 isolate** ([`isolated-vm`](https://github.com/laverdet/isolated-vm)) with no filesystem, no network, a memory cap, and a wall-clock timeout. The sandbox is the security boundary, not model alignment.
- **An eligibility filter** that only exposes tools annotated `readOnlyHint: true` *and* shipping an `outputSchema`. Without typed outputs the script is back to free-text parsing; with them, you get real `.then()`-able values. This is why I argue [structured outputs are not optional](#eligibility-and-why-structured-outputs-are-not-optional).
- **A callback bridge** so `codemode.<tool>(...)` inside the sandbox is a `Reference` call back into the harness process, where the actual MCP request is dispatched through the same `McpClientManager` that handles Skills and tool-cli. Same audit log, same HITL hook point, same rate limiting.

The model-facing surface is two tools: `code_search` (find eligible tools by keyword, returns names + schemas) and `code_execute` (run a script with `codemode` injected). Everything else is plumbing.

If you want to copy the pattern: the source lives in [`src/code-mode/`](https://github.com/SamMorrowDrums/mcpi-ext/tree/main/src/code-mode) of [mcpi](https://github.com/SamMorrowDrums/mcpi-ext). The runtime is small enough to read in an afternoon.

> *"I can see everything," Codey said, eyes reflecting infinite JSON. "I just can't exfiltrate it. That's the point. That's why they trust me."*

---

*Have thoughts on this article or progressive discovery in MCP in general? I opened a* [*discussion on GitHub*](https://github.com/SamMorrowDrums/cv/discussions/63) *for this series.*

Code Mode


![A glowing briefcase marked tool-cli being passed between hands in a dark corridor, trailing sparks of shell commands](/images/progressive-discovery/nuclear-mcp-football.webp)

> *The Football is not a weapon. The Football is the authority to use weapons. Whoever holds it can reach any server, call any tool, chain any result - but they must do so deliberately, one bash command at a time.*

*This is Part 3 of the Progressive Discovery in MCP series. See* [*Part 1*](/blog/progressive-discovery-in-mcp-part-1) *and* [*Part 2*](/blog/progressive-discovery-in-mcp-part-2)*.*

I nicknamed the [tool-cli](https://github.com/SamMorrowDrums/tool-cli) the [Nuclear Football](https://en.wikipedia.org/wiki/Nuclear_football) because it lets the agent harness hand over control of launching MCP tools to the shell, while the actual launching is still managed by the system it commands (the agent harness). This article runs through some of the benefits of CLIs, Sandboxes and how you can combine them with the benefits of MCP and win at life.

With current implementations, CLIs can be a genuinely better experience than MCP servers sometimes. Popular CLIs are already in the training set. Bash is absurdly powerful - streaming, parsing, formatting, networking, SSH. Developers never really move away from the shell because the composability is unmatched. When Mario Zechner says he can [replace 21 MCP tools with four bash scripts](https://mariozechner.at/posts/2025-11-02-what-if-you-dont-need-mcp/), he's not wrong about the efficiency.

With CLI usage, it's not just tool schema savings. Agents can use `grep`, `jq` etc. to get what they need from the output of CLIs, chaining many commands together - the model doesn't need to be in the loop for every intermediate step, and it's frequently the case that only parts of the output of commands are useful for the task in hand.

CLIs do however have problems that get handwaved in the "just use bash" discourse. Token replay is a real risk. The full CLI surface is exposed - anything the token can do, the agent can attempt - the token is fully load-bearing. Then when agents hit errors they bash their head against walls trying to unblock themselves. I've watched agents disable commit signing, attempt to install packages with sudo, and try increasingly creative workarounds. And these aren't just annoyances - an AI agent [deleted a startup's entire production database and backups in 9 seconds](https://www.fastcompany.com/91372483/replit-ceo-what-really-happened-when-ai-agent-wiped-jason-lemkins-database-exclusive) via an unsupervised API call, and a developer [lost 2.5 years of course data](https://timesofindia.indiatimes.com/technology/tech-news/i-over-relied-on-ai-developer-says-claude-code-accidentally-wiped-2-5-years-of-data-shares-advice-to-prevent-loss/articleshow/129336313.cms) when Claude Code ran a destructive migration unsupervised. With a CLI, there's no annotation saying "this operation is destructive" - it's just another command. Sure, there are many attempts going on to tame this beast - sandboxing the shell with OS-level isolation ([OpenAI's Codex CLI](https://github.com/openai/codex) wraps commands in Seatbelt on macOS and Landlock on Linux), explicit allowlists and per-command approval prompts ([Claude Code's permission system](https://docs.claude.com/en/docs/claude-code/iam), [VS Code Copilot agent mode](https://code.visualstudio.com/docs/copilot/agents/agent-tools), [Cursor's command allowlist](https://docs.cursor.com/en/agent/chat/commands)), bolting audit logging onto bash post-hoc, or trying to reason about commands deterministically with a policy engine. Most of those attempts are still YOLO mode in disguise, there are usually fundamental flaws that when exposed mean any command can be executed or require so many confirmations that end users turn them off when given the choice.

MCP has a better security story here. The harness connects to the MCP server and can easily keep the token away from the model. A mistake in command parsing will not cause arbitrary local code execution. Tool annotations ([`readOnlyHint`, `destructiveHint`](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#tool-annotations)) let clients make policy decisions. But MCP (as commonly implemented) loses on composability - results roundtrip through the model's context, and you can't pipe them through `jq` first.

This begs the question: can you have both?

## tool-cli: a thin shell over the harness

MCP CLIs aren't new. [`wong2/mcp-cli`](https://github.com/wong2/mcp-cli), [`IBM/mcp-cli`](https://github.com/IBM/mcp-cli), [Phil Schmid's `mcp-cli`](https://github.com/philschmid/mcp-cli), and the official [MCP Inspector](https://github.com/modelcontextprotocol/inspector) all let humans (or scripts) probe servers and call tools. The thing they have in common is that they're standalone clients: each one opens its own MCP connection and presents that to a human at a terminal. `tool-cli` is shaped differently. It's still a shell command, but it doesn't hold any MCP connections - it piggybacks on the agent harness's existing ones, which (as you'll see) is what unlocks everything interesting later.

`tool-cli` is a shell command. The agent uses it like any Unix tool. Discovery is progressive - each step pays only the tokens it needs:

```sh
tool-cli --help                                # What servers exist?
tool-cli github                                # What tools does this server have?
tool-cli github search_code                    # What's the schema for this tool?
tool-cli github search_code '{"query":"auth"}' # Call it
```

The agent goes from "what's available?" to a tool call in a few steps, only paying schema tokens for the tools it actually uses. There might be 82 available tools across three connected servers, but a typical session might only need to invoke 5 or 6 tools, so why pay for all 82?

When tools provide [`outputSchema`](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#structured-content), `tool-cli` advertises this in the schema description step. The model knows upfront what shape the JSON response will have, making jq filters and downstream processing more reliable. Structured output makes the CLI composability story much stronger - the model can confidently write `jq '.issues[] | {number, title}'` because it knows the response schema before calling.

Shell composability works exactly as you'd expect:

```sh
# List issues and filter with jq
tool-cli github list_issues '{"owner":"github","repo":"github-mcp-server","perPage":10}' \
  | jq '.issues[] | {number, title, state}'

# Search and grep
tool-cli github get_file_contents \
  '{"owner":"github","repo":"github-mcp-server","path":"README.md"}' \
  | tail -n +2 | jq -r '.resource.text' | grep -in copilot

# Loop over cities
for city in London Tokyo Paris; do
  echo "=== $city ==="
  tool-cli weather check_weather '{"city":"'"$city"'"}'
done
```

The intermediate JSON flows through pipes, not through the model's context. The model sees only the final filtered result.

![tool-cli in action - progressive discovery piped through grep](/images/progressive-discovery/tool-cli-grep.png)

## Why the architecture is special

Here's the subtle part. `tool-cli` is not a standalone MCP client. It's a thin HTTP client that calls the agent harness's MCP connections directly via JSON-RPC.

![Sequence diagram: agent harness shell-exec into tool-cli, JSON-RPC to ToolCliRpcServer in the harness, MCP tool call to the server, result returned back through the chain](/images/progressive-discovery/tool-cli-sequence.png)

The actual MCP call happens in the agent harness, the same connection that handles direct tool calls too. The only difference is that schemas aren't given to the model, the model is given access to them via CLI instead.

Why does this matter?

**Every tool-cli invocation appears in the agent log.** Full observability without new instrumentation. If you build for the EU, [Article 12 of the AI Act](https://artificialintelligenceact.eu/article/12/) requires high-risk systems to *automatically* log enough to reconstruct their operation, and [Article 26(6)](https://artificialintelligenceact.eu/article/26/) requires deployers to keep those logs for at least six months. Funnelling every tool call through one harness is how you make that obligation a side effect of the architecture rather than a retrofit.

**The harness is the single choke point.** Human-in-the-loop gating can be added at one point and it covers any possible MCP invocation method. Tool annotations can be checked. Destructive calls can be gated through user confirmation. This works regardless of how the agent interacts with MCP.

**Sandbox port forwarding.** If you're running the agent in a sandbox (container, VM, restricted environment), you don't need to allow-list MCP server URLs. Just forward the tool-cli port from the sandbox to the harness. The agent gets full MCP access through a single localhost port, with all the security controls the harness provides. People have literally been trying to build custom shells and AI operating systems - you can get pretty rigid blast radius control with all the benefits if you pursue this approach. Just give the sandbox the tool-cli plus basic bash tools and a few instructions and you have a custom sandbox with clear limits on what the agent can do.

I'm specifically excited for people to try running a sandbox with only this `tool-cli` for external access. When combined with few other basic shell tools, you can trivially gain fine-grained control of what the agent can do with zero-up-front cost, progressive discovery and all the shell composability that makes CLIs so powerful. MCP is not in competition with CLI, it's a protocol, and CLI is a completely reasonable way to implement it.

## How does this compare to progressive discovery via Skills over MCP?

The skills approach of the [previous article](/blog/progressive-discovery-in-mcp-part-2) showed how workflows could be triggered effectively with instructions via skill invocation. `tool-cli` is much better for very atomic tools, and for very large outputs (yes MCPs can and sometimes should return huge outputs - it is only that models cannot receive them directly) like CSV parsing which is easy via CLI. There are loads of examples where it would be better for MCP output to be redirected for post-processing by the model without being shoved straight back into the context window, and MCP CLIs are a pattern that really can get the best of both worlds.

## Shared secret auth

The RPC server binds to `127.0.0.1` only. A shared secret token is generated per session and passed to the CLI via environment variable (`TOOL_CLI_TOKEN`). Every request is authenticated:

```javascript
$ TOOL_CLI_TOKEN=bogus tool-cli github list_issues '{...}'
Authentication failed: invalid or missing TOOL_CLI_TOKEN

$ TOOL_CLI_PORT=1 tool-cli github list_issues '{...}'
Error: tool-cli server not running. Is mcpi-ext loaded?
```

This is defense-in-depth. Even though the server binds to localhost, another local process can't just probe the port and call tools without the token. The token is session-scoped - it's generated when the harness starts and dies when the session ends.

## Why this beats "just give the agent CLIs"

The `gh` CLI is an excellent example. It's great, and models are well-trained on it. I personally worked on the `gh skill` command recently. But giving an agent any CLI means giving it everything the token can do, with no ability to gate specific operations. If the token has `repo` scope, the agent can pull from or push to any repo. If it has `admin:public_key` scope, it could manage SSH keys. I refused to merge [a PR](https://github.com/github/github-mcp-server/pull/474) for the GitHub MCP Server because even if the token allows it, I didn't want to facilitate agents being prompt-injected to add public SSH keys. The point being: the MCP server is being built exclusively for agentic use, and doesn't need to facilitate all operations.

With `tool-cli`, the harness can inspect tool annotations before executing. A `destructiveHint: true` tool can trigger user confirmation. A `readOnlyHint: true` tool can run without asking. The annotations come from the MCP server, which knows its own tools better than any client-side allow-list. I have thoughts on more advanced HITL that allows more things automatically when they align with the intent of the user, but that's another story. They still do matter, and have saved me and many others plenty of times from actions we'd rather the agent did not do.

This isn't just theoretical safety. Every `tool-cli` call that goes through the harness can be logged in the same audit log as any agent actions. One audit trail for everything.

## The honest trade-offs

What you give up vs standalone CLIs:

- **Discoverability**: if the model doesn't know a capability exists, it can't ask for it. Skills can mitigate this by advertising intent cheaply. Using the `tool-cli` requires the model to reason "perhaps there's a tool for this" - which works well in practice, and the system prompt can positively influence this.
- **False Economy**: if the model tries to find things and fails a lot, or invokes things and goes through lots of iterations getting it right - it is possible to use more rather than fewer tokens. For very narrow agents specific instructions and up-front tool declarations can be more efficient.
- **Cold-start discovery cost**: every new agent session, the agent has to learn what it has access to. That is a core trade-off of progressive discovery and it's not free - the savings come from not paying for tools you never use, not from paying nothing.

When to reach for `tool-cli`:

- "I don't know what's available, let me poke around"
- "quick one-shot filter"
- "pipe through jq and done."

It's best for needle in a haystack tasks where the model only wants a small subset of the output.

## Try it yourself

If you went through the [Part 1 setup](/blog/progressive-discovery-in-mcp-part-1#try-it-yourself) or the [Part 2 setup](/blog/progressive-discovery-in-mcp-part-2#try-it-yourself) you already have everything you need - `mcpi-ext` starts the `tool-cli` RPC server for you and sets `TOOL_CLI_PORT` and `TOOL_CLI_TOKEN` for the agent subprocess automatically.

### 1. Install

```sh
npm install -g @sammorrowdrums/mcpi@latest @sammorrowdrums/mcpi-ext@latest @sammorrowdrums/tool-cli@latest
```

### 2. Point it at any MCP server

Reuse the `~/.config/mcpi-ext/mcp.json` from Part 1 or Part 2, or start with something tiny:

```json
{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server:latest",
        "stdio"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}
```

### 3. Run mcpi

```sh
mcpi --extension $(npm root -g)/@sammorrowdrums/mcpi-ext/dist/index.js \
  --mcp-config ~/.config/mcpi-ext/mcp.json
```

### 4. Drive `tool-cli` yourself first

Before letting the model do it, walk the same four progressive steps from your shell. In another terminal:

```sh
tool-cli --help                                # What servers exist?
tool-cli github                                # What tools does this server have?
tool-cli github search_code                    # What's the schema for this tool?
tool-cli github search_code '{"query":"auth"}' # Call it
```

Then ask the agent something deliberately exploratory, where you don't expect a skill to fire:

> *"Poke around the github/github-mcp-server repo and tell me how many open issues mention prompt injection."*

Watch the log - the agent will drive `tool-cli` itself, paging in tool schemas only for the handful of tools it actually needs, and piping results through `jq`, `grep`, or shell loops without round-tripping the intermediate data through its own context.

## For harness builders: integrate it into your own agent

[`@sammorrowdrums/tool-cli`](https://github.com/SamMorrowDrums/tool-cli) is a standalone npm package, not tied to mcpi. It exposes a `ToolProvider` interface with three methods (`getServerNames`, `getTools`, `callTool`) that you implement against your own MCP client. Start the server, set two env vars, and your agent's shell has progressive MCP discovery.

```typescript
import { ToolCliServer } from "@sammorrowdrums/tool-cli/server";

const server = new ToolCliServer(myToolProvider);
const { port, token } = await server.start();
// Set TOOL_CLI_PORT and TOOL_CLI_TOKEN for agent subprocesses
```

You don't even need this package if you prefer another language. The protocol is four JSON-RPC methods over HTTP (`listServers`, `listTools`, `describeTool`, `callTool`). The [repo README](https://github.com/SamMorrowDrums/tool-cli) has implementation examples in Go, Python, and Rust.

> *They pass the Football from hand to hand. It is heavy with potential. Every tool on every server is one command away - but you must type the command yourself. And somewhere behind you, the harness is watching.*

*Next:* [*Part 4: Code Mode - sandboxed code over MCP*](/blog/progressive-discovery-in-mcp-part-4)*.*

---

*Have thoughts on this article or progressive discovery in MCP in general? I opened a* [*discussion on GitHub*](https://github.com/SamMorrowDrums/cv/discussions/63) *for this series.*

The Nuclear Football

The Skill Dealer: Skills over MCP


Quick update on [remarkable-mcp](https://github.com/SamMorrowDrums/remarkable-mcp) since [the original post](/blog/building-an-mcp-server-for-remarkable). [Latest release is here](https://github.com/SamMorrowDrums/remarkable-mcp/releases/latest). The headline is that most of what landed came from other people, three community PRs from [@Giancarlo-therapy](https://github.com/Giancarlo-therapy), [@ColinSha](https://github.com/ColinSha), and [@McSchnizzle](https://github.com/McSchnizzle) shipped recently. I m very grateful for contributions and issues opened against the project. Please continue!

## Write Support

The biggest functional change. [@McSchnizzle](https://github.com/McSchnizzle)'s [PR #70](https://github.com/SamMorrowDrums/remarkable-mcp/pull/70) addressed [#24](https://github.com/SamMorrowDrums/remarkable-mcp/issues/24) and landed as five new write tools:

| Tool | Transports |
|------|------------|
| `remarkable_upload` (PDF/EPUB) | SSH, USB web |
| `remarkable_mkdir` | SSH |
| `remarkable_move` | SSH |
| `remarkable_rename` | SSH |
| `remarkable_delete` | SSH |

Off by default. Enable with `REMARKABLE_ENABLE_WRITE=1` or `--write`. All five carry `ToolAnnotations(readOnlyHint=False)`, and `remarkable_delete` adds `destructiveHint=True`, so agent harnesses with write-blocking/confirmation enabled will be able to use them safely, but I expect a lot of users will enable write (let me know if you want it by default). The server `instructions` only mention the write tools when they're enabled, and registration is gated on the active transport: USB + write gets only `remarkable_upload`, SSH + write gets all five, cloud + write is a no-op. I managed to avoid an `rmapi` dependency, everything goes through SSH and USB web directly.

## Seeing What the User Sees

[@ColinSha](https://github.com/ColinSha)'s [PR #79](https://github.com/SamMorrowDrums/remarkable-mcp/pull/79) added something I'd been meaning to do for ages: rendering annotations on top of the PDF page underneath. An annotation in isolation isn't useful; you need the page it's pointing at.

`remarkable_image` now has an opt-in `render_merged` parameter. When `True` and the document has a source PDF, the PDF page is rasterised and the annotations are alpha-composited on top. The output canvas is the **union** of the PDF page bounds and the rmc content bounds, so user-added pages past the end of the PDF don't get clipped. Default off, existing callers unaffected, merged output gets its own `.merged.png` resource URI. While verifying on a live tablet I also caught that SSH `download()` was missing `{uuid}.pdf` and `{uuid}.epub` files, fixed in the same change.

## Reliability

[@Giancarlo-therapy](https://github.com/Giancarlo-therapy)'s [PR #75](https://github.com/SamMorrowDrums/remarkable-mcp/pull/75) addressed [#29](https://github.com/SamMorrowDrums/remarkable-mcp/issues/29). Every reMarkable Cloud HTTP call now goes through `_http_request_with_retry()`. Retries on `ConnectionError`, `Timeout`, and `429/500/502/503/504`. No 4xx retries, `401` token renewal stays the caller's job. Exponential backoff with full jitter (the AWS builders'-library pattern), capped at 20s per sleep, honours `Retry-After`. Tunable via `REMARKABLE_RETRY_ATTEMPTS` and `REMARKABLE_RETRY_DELAY`. Each retry logs a warning so "it hung for a bit then worked" reports are debuggable.

Two related bugs also got fixed along the way:

- **`rmc` couldn't be found when installed via `uvx`**. The binary lives in the venv's `bin/` directory and wasn't on `PATH`, and the `FileNotFoundError` was bypassing the v5/v6 fallback renderers entirely. Silently broke handwriting OCR for `uvx` users. Resolved by walking PATH → venv bin → bare name (approach from [@ColinSha](https://github.com/ColinSha)'s PR).
- **27 of 385 docs on my test tablet were invisible**. I'd been treating `synced: false` as "archived", but `synced` actually means "local changes pushed to cloud". Now only `parent == "trash"` hides documents.

A live-tablet integration suite (`--run-integration`) was added so this kind of thing fails loudly next time.

## Concurrency Under Load

A few async bugs surfaced once people started actually parallelising tool calls. The most interesting one: FastMCP awaits async tool handlers directly on the event loop, but our handlers were doing blocking I/O, `subprocess.run` for SSH, `requests` HTTP, `pymupdf` and `cairosvg` rendering, `pytesseract` OCR, `zipfile` extraction, inside `async def`. A single slow call blocked every concurrent `call_tool` request until it finished. Fixed with a new `concurrency.run_blocking()` wrapper over `asyncio.to_thread`, every blocking site now `await`s through it, and `remarkable_browse` / `remarkable_recent` / `remarkable_status` converted from sync to `async def` (FastMCP doesn't offload sync handlers either). Regression test runs two concurrent browses with a mocked 0.4s delay and asserts they actually overlap.

Also fixed: `remarkable_search` was a sync function calling the async `remarkable_read` without `await`, then passing the returned coroutine to `json.loads`. Literal error string was *"the JSON object must be str, bytes or bytearray, not coroutine"*. Now async, with a regression test.

No tool signatures or response shapes changed across any of this.

## In the Forks

While I was looking through PRs I also went through the forks. A handful have substantial divergence worth calling out, different enough that they're effectively answering some of the open issues independently:

- **[vgmakeev/remarkable-myscript-mcp](https://github.com/vgmakeev/remarkable-myscript-mcp)**: a full MyScript OCR backend, with stroke-line grouping, parallel batching across CPU cores, smart image splitting, and an `EmbeddedResource` output format for Claude vision. A serious answer to [#25 (OCR providers)](https://github.com/SamMorrowDrums/remarkable-mcp/issues/25).
- **[sschimmel/remarkable-mcp](https://github.com/sschimmel/remarkable-mcp)**: OpenRouter and xAI OCR backends, plus a document-tree cache that avoids 25–35s cloud refetches per call, plus a `--fetch-notebook` CLI for batch consumers. Also #25, also touches [#28 (performance)](https://github.com/SamMorrowDrums/remarkable-mcp/issues/28).
- **[adaofeliz/remarkable-mcp](https://github.com/adaofeliz/remarkable-mcp)**: a shared document snapshot cache and parallelised cloud metadata fetch with bounded concurrency, with live integration tests and a Cloud Mode Architecture write-up in the README. Squarely at #28.
- **[zachattack323/remarkable-mcp](https://github.com/zachattack323/remarkable-mcp)**: a Cloud Run deployment entrypoint, with the FastMCP host/port/SSE-path plumbing needed to make that actually work behind a managed runtime.
- **[rsampaio/remarkable-mcp](https://github.com/rsampaio/remarkable-mcp)**: switches Google Vision auth from API key to Application Default Credentials, plus render/OCR quality tweaks from the SVG source. Also includes async fixes that overlap with the concurrency work above, independently rediscovered.
- **[ghbryant/remarkable-mcp](https://github.com/ghbryant/remarkable-mcp)**: SSH reconnection on dropped connections. The kind of thing the upstream server probably should do.
- **[pschitte/remarkable-mcp](https://github.com/pschitte/remarkable-mcp)**: a Guix channel with package definitions. Different distribution angle.

And one that isn't a server improvement at all but is worth mentioning: **[travisparkerm/remarkable-mcp](https://github.com/travisparkerm/remarkable-mcp)** has been turned into "reMarkable Podcast": a web app that pulls handwritten notes off your tablet, OCRs them with Google Vision, generates a podcast script with Claude in one of six personality styles, and produces an MP3 episode with ElevenLabs TTS. Google OAuth login, daily episode generation, voice matching. A nice example of remarkable-mcp being treated as a building block.

Honestly, going through these is one of my favourite parts of running a small project. People building real things for themselves, a podcast generator, a Cloud Run deployment, a MyScript OCR backend for their own handwriting, is the actual spirit of open source, and more rewarding than any star count. If you're running a fork, I'd love to hear about it. And if there's anything in yours that would help the upstream server, please do open a PR, the MyScript backend and the cloud-tree cache in particular look like things the project would benefit from.

This is also why the project is MIT-licensed. I don't want compensation or restrictions, I want people to run free with it. No policy on PRs either, I'll happily merge them when the bandwidth lines up. This cycle is just the honest example of what happens when it doesn't: if a PR or a fork has something I want upstream and I can't get round to the proper review loop, I may end up re-implementing it to make sure my specific requirements are in there. Not the preference, just the fallback. Same energy from both directions.

## Install

[Latest release](https://github.com/SamMorrowDrums/remarkable-mcp/releases/latest) is on [PyPI](https://pypi.org/project/remarkable-mcp/). The setup hasn't changed since the original post, see the [SSH Setup Guide](https://github.com/SamMorrowDrums/remarkable-mcp/blob/main/docs/ssh-setup.md) for enabling developer mode on the tablet.

SSH mode with write support enabled, for `.vscode/mcp.json`:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "google-vision-key",
      "description": "Google Vision API Key",
      "password": true
    }
  ],
  "servers": {
    "remarkable": {
      "command": "uvx",
      "args": ["remarkable-mcp", "--ssh", "--write"],
      "env": {
        "GOOGLE_VISION_API_KEY": "${input:google-vision-key}"
      }
    }
  }
}
```

Drop `--write` for read-only. Cloud-mode setup is unchanged from the [original post](/blog/building-an-mcp-server-for-remarkable). The [Quick Install badges](https://github.com/SamMorrowDrums/remarkable-mcp) in the README handle VS Code configuration automatically.

## What's Next

remarkable-mcp is very much a side project, and I struggle to give it the attention it deserves. So contributions and bug reports genuinely help, they're often the thing that turns "I'll get to it eventually" into a shipped release. This cycle is the clearest example of that so far.

The contribution pattern from initial release seems to be working well: the [issues](https://github.com/SamMorrowDrums/remarkable-mcp/issues) that get engagement get prioritised. Write support (#24) and reliability (#29) both shipped because people brought concrete proposals. OCR providers (#25), enhanced search (#26), export (#27), and performance (#28) are still open. If you've got a use case for one of them, comment on the issue, or send a PR.

Thanks again to [@Giancarlo-therapy](https://github.com/Giancarlo-therapy), [@ColinSha](https://github.com/ColinSha), and [@McSchnizzle](https://github.com/McSchnizzle).


remarkable-mcp Update


![Three figures in a dark, Sandman-esque realm - The Skill Dealer, The Nuclear Football, and Codey C. Maude - standing before swirling constellations of MCP tool connections](/images/progressive-discovery/banner.webp)

Mario Zechner wrote a post last year called ["What if you don't need MCP?"](https://mariozechner.at/posts/2025-11-02-what-if-you-dont-need-mcp/). I like Mario. I watched him speak at AI Engineer Europe and was genuinely inspired by his approach to [Pi](https://pi.dev/) - the simplicity of it, the emphasis on doing your own context engineering, the "I was just crazy enough to build this" energy. He makes strong arguments about composability, bash fluency, and the tax that large MCP tool schemas impose on agents.

But I think he's wrong about the conclusion, and I think a lot of people are making the same mistake: conflating the laziest possible MCP implementation with the protocol itself.

Mario's critique boils down to: two MCP servers exposing 47 tools using \~32k tokens were just too many tools with too large a context footprint, they confuse the model, the results aren't composable, and you could replace it all with four bash scripts and a 225-token README. He's right about all of that, in that context.

But MCP doesn't tell you to dump every tool into the system prompt. MCP doesn't prevent you from composing results through pipes. MCP doesn't force you to roundtrip every intermediate result through the model. Those are implementation choices, and the entire industry of client builders made them by default because almost nobody applied serious context engineering to MCP.

I work on the [GitHub MCP Server](https://github.com/github/github-mcp-server). We have over 100 tools (just over 40 by default). We serve approaching 12 million tool calls a week. I've lived the tool bloat problem from the inside, and "having a CLI that models are well trained to use" at the same time - we watched agents get worse at using GitHub as we added more tools, while more and more people would ask "why not just use GitHub CLI?". Even myself, I have reasons to do both. I helped build `gh skills` too, adding ability to install agent skills directly from `gh cli`. Clearly, I see some value in CLIs, Skills and MCP all.

We tried toolsets (groups of related tools users could pick). We tried dynamic tool selection. I even prototyped a version with RAG-based semantic tool search back in April 2025. And what happened?

Everyone used the default settings. The dynamic tool selection actually worked well, but it busted the model cache on every tool set change, so we stopped innovating in that direction.

That was genuinely frustrating. We had elegant solutions, all they required was users to configure them. But most users don't configure things. So we took a different path: we optimised the out-of-the-box experience. We reduced the default tool count by 49%, consolidated CRUD tools, [cut output tokens by over 75%](https://github.blog/changelog/2025-10-29-github-mcp-server-now-comes-with-server-instructions-better-tools-and-more/) on tools like `list_pull_requests` without losing useful information.

But that was just trimming. Collectively what we have needed to build is progressive discovery - tools that appear in the model's working set only when they're relevant to the current task. The full catalog exists, but the model sees a curated surface. You pay context tokens only for what you actually use.

## The ideas aren't new. So where are the implementations?

Anthropic shipped [tool search with `defer_loading`](https://www.anthropic.com/engineering/advanced-tool-use) - server-side search that loads tools on demand, cutting context by up to 85%. Cloudflare shipped [Code Mode](https://blog.cloudflare.com/code-mode/) - the model writes code against a typed SDK, collapsing hundreds of endpoints into two tools. [Phil Schmid's mcp-cli](https://www.philschmid.de/mcp-cli) showed that progressive discovery via shell commands can reduce token usage by 85x. These are all real, working approaches. And none of them require giving up MCP.

In my [MCP Dev Summit talk](https://www.youtube.com/watch?v=ideYDMJKujE&list=PLjULwdJUtFdhIBhibLEogtK1XYCNaFyFl&index=10), I said "MCP vs CLI is the wrong question" - and I meant it. Both CLIs and MCP are in the mix. Every hot take that says one kills the other is really just saying "at this exact moment, this works well for me." Extrapolating that into the future is a mistake.

I got bored waiting for others, so I finally built the thing I kept talking about.

## Three tiers, three characters

[mcpi](https://github.com/SamMorrowDrums/mcpi-ext) is an experimental fork of [pi](https://pi.dev/) + [extension](https://github.com/SamMorrowDrums/mcpi-ext) that implements three complementary strategies for progressive tool discovery. Each pays only the context tokens it needs. Each handles a different shape of work. And because the best ideas deserve characters, each has a name.

| Tier | Name | Mechanism | Best for |
| --- | --- | --- | --- |
| 1 - Skills | **The Skill Dealer** | `skill://` resources gate tools via `allowed-tools` | Curated workflows |
| 2 - tool-cli | **The Nuclear Football** | CLI progressive discovery via shell | One-shot exploration |
| 3 - Code Mode | **Codey C. Maude** | Sandboxed JS over read-only tools with `outputSchema` | Computation across many calls |

This series goes deep on each. But first, the property that ties them together:

**Every call flows through the harness.** Whether the model loads a skill, shells out to `tool-cli`, or writes sandboxed JavaScript, the actual MCP tool call happens in the extension process. One choke point for all three tiers. Every invocation logged, observable, gatable. That matters for security, auditability, and future human-in-the-loop gating - and it's a point I'll return to throughout the series.

## Additionally - large output offloading

Progressive discovery controls input tokens - what the model sees. But output tokens matter too. A single `list_issues` call can return 50KB of JSON that sits in the transcript forever. Copilot CLI already does this with MCP - large tool responses get written to disk so the agent can use local tools like grep over them instead of bloating context.

The extension does the same thing. It intercepts tool results. If output exceeds a threshold, it writes the full response to a temp file and returns a pointer to the model. The model can read the file if it needs the content, but the default path keeps context lean. This is the output-side equivalent of progressive discovery: don't pay for what you don't need.

## Try it yourself

This is a working system, not a thought experiment. Here's how to set it up:

### 1. Install

```sh
npm install -g @sammorrowdrums/mcpi@latest @sammorrowdrums/mcpi-ext@latest @sammorrowdrums/tool-cli@latest
```

### 2. Configure MCP servers

Create `~/.config/mcpi-ext/mcp.json`:

```json
{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server:skill-discovery",
        "stdio"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}
```

Replace `your-token-here` with your [GitHub personal access token](https://github.com/settings/tokens).

### 3. Run

```sh
mcpi --extension $(npm root -g)/@sammorrowdrums/mcpi-ext/dist/index.js \
  --mcp-config ~/.config/mcpi-ext/mcp.json
```

You'll see the extension discover servers, tools, and skills. From there, you have all three tiers available.

## The series

This is Part 1 of 5. The rest of the series covers each tier in depth:

- **Part 2: The Skill Dealer** - Deep dive into skills over MCP. How `skill://` resources **could** gate tools, preserve prompt cache, and why this emerging spec direction could change how MCP servers are designed.
- **Part 3: The Nuclear Football** - The MCP CLI. Progressive discovery through shell composability, and why routing every call through the harness changes the security story.
- **Part 4: Codey C. Maude** - Code Mode. Sandboxed JavaScript over read-only MCP tools with structured output. Why computation and accountability combine to create a very efficient and powerful harness.
- **Part 5: Three Is Not Redundancy** - How the three tiers compose, what's left to build, and a call to action.

**If you build MCP servers**, this series shows a new paradigm for how your tools get discovered and used. You can experiment with `skill://` resources on your own server today.

**If you build agent harnesses**, you'll find concrete patterns to implement - including the [`tool-cli`](https://github.com/SamMorrowDrums/tool-cli) binary, which is a standalone package you can integrate with your own harness as a progressive discovery layer over any MCP connection.

**If you use agents**, these experiments should help you save money on tokens and have smoother agent runs by keeping only relevant tools in context.

MCP doesn't have a context problem. It has a solution awareness problem. And the pieces of the puzzle required to solve it are mostly already in the protocol.

*Next:* [*Part 2: The Skill Dealer - Skills over MCP*](/blog/progressive-discovery-in-mcp-part-2)*.*

---

*Have thoughts on this article or progressive discovery in MCP in general? I opened a* [*discussion on GitHub*](https://github.com/SamMorrowDrums/cv/discussions/63) *for this series.*

MCP Doesn't Have a Context Problem


Your [MCP server](https://modelcontextprotocol.io/) has a public interface. Tools, prompts, resources, capabilities: everything an AI client sees when it connects. Together, these responses form a contract. Unlike a REST API with an OpenAPI spec or a library with type definitions, this contract is defined at runtime. You don't see it until something connects.

I built [mcp-server-diff](https://github.com/SamMorrowDrums/mcp-server-diff) to answer a simple question: what changed between two versions of my server? It's available as a [GitHub Action](https://github.com/marketplace/actions/mcp-server-diff) and a [CLI tool on npm](https://www.npmjs.com/package/mcp-server-diff). The tool probes both versions and compares their `initialize`, `tools/list`, `resources/list`, and `prompts/list` responses, producing a diff that shows exactly which tool, which property, which value changed.

Understanding how your server contract changes is incredibly useful, but it's one of those subtle things that doesn't make sense until you make a subtle mistake. Then suddenly it's invaluable.

## It keeps catching things

During a major refactor of the [GitHub MCP Server](https://github.com/github/github-mcp-server), a colleague at GitHub, Adam, sent me this after the diff workflow flagged something:

> kudos for the MCP diff workflow. Picked up that I missed a bit of toolset filtering

The code looked right. Tests passed. Code review didn't flag anything. But the runtime interface had shifted in a way nobody intended, and the diff caught it before it reached users. This wasn't a one-off. The diff has saved myself and other team members from shipping unintended changes numerous times now. SDK upgrades that silently changed tool schemas. Refactors that accidentally dropped capabilities. Toolset filtering that shifted in ways nobody noticed in code review. Each time, the code and tests looked correct, but the server was advertising something different to clients than we expected.

The pattern is always the same: the diff reveals what lives in the gap between what you think your code does and what your server actually advertises at runtime. Those are different things more often than you'd expect.

The [GitHub MCP Server workflow](https://github.com/github/github-mcp-server/actions/workflows/mcp-diff.yml) tests [eighteen separate configurations](https://github.com/github/github-mcp-server/blob/main/.github/workflows/mcp-diff.yml) on every PR: default mode, read-only mode, dynamic toolsets, individual and combined toolset flags, and custom tool call sequences that exercise dynamic toolset loading. The point is that any of these configuration variants could accidentally diverge from each other during a change, and the diff makes that visible. The Remote GitHub MCP Server uses it on our internal repo too.

## Seven languages, one interface

I maintain [MCP starter repos](https://github.com/SamMorrowDrums?tab=repositories&q=mcp-starter) in Python, TypeScript, Go, Rust, C#, Kotlin, and PHP. I use them for workshops to get people off to a warm start with MCP development in their preferred language, so keeping the interfaces consistent matters.

A [cross-repo workflow](https://github.com/SamMorrowDrums/mcp-starters/issues/26) compares all six non-Python implementations against the Python reference and opens a tracking issue whenever differences are detected. Most of the differences come from SDK behaviour or language conventions rather than mistakes in repo code (although at the start of using this workflow there were many in my code). That's exactly the point. Without the diff, you can't tell where the difference comes from.

When I was iterating on consistency for these repos, I used agent loops that compared each starter against the Python reference, had the agent fix what it could, and re-ran the comparison as validation. It's a good example of how a concrete, machine-readable diff gives agents something to iterate against rather than just hoping the output is right.

## People I didn't expect are using it

[Matthew Diakonov](https://github.com/m13v) from [mediar-ai](https://github.com/mediar-ai) reached out on the [starter repo tracking issue](https://github.com/SamMorrowDrums/mcp-starters/issues/26#issuecomment-4079388640) to share that they maintain MCP servers in both [Swift](https://github.com/mediar-ai/mcp-server-macos-use) and [Rust](https://github.com/mediar-ai/terminator) for their macOS computer use agent. Interface differences between the two had been a constant source of bugs until they added automated conformance tests. That's a use case I'd hoped for but hadn't seen confirmed in the wild yet, at least not beyond personal experimentation.

On the official MCP side, MCP Maintainer [Ola Hungerford](https://github.com/olaservo) created an [issue on the Inspector repo](https://github.com/modelcontextprotocol/inspector/issues/1034) exploring whether mcp-server-diff could become a plugin for the [Inspector CLI](https://github.com/modelcontextprotocol/inspector), tagged for v2. That could be an effective way of increasing awareness of the tool, and getting it into more hands.

I've also [proposed adding the workflow to the official Everything Server](https://github.com/modelcontextprotocol/servers/pull/3260), the protocol's reference implementation that exercises all MCP features. Tracking public interface changes there would help SDK developers validate compliance and catch unintended regressions when the reference server evolves.

## What I'm most excited about

The tool is still in its infancy, but the use cases that keep surfacing are:

- **PR validation**: compare your branch against main to check that interface changes are intentional, not accidental side effects of internal refactoring
- **Regression prevention**: avoid breaking changes during SDK upgrades, dependency updates, or major rewrites (this is where the team and I have got the most value, repeatedly)
- **Cross-language consistency**: maintain similar servers in different languages and always know the exact differences, whether from your code or SDK divergence
- **Release auditing**: compare a new semver tag against the previous one to see what changed in the public interface
- **Fork comparison**: see precisely what a fork changed in the server's public interface
- **SDK compliance testing**: verify reference implementations stay consistent as SDKs evolve

## Try it

The [GitHub Action](https://github.com/marketplace/actions/mcp-server-diff) is a few lines of YAML. The [CLI](https://www.npmjs.com/package/mcp-server-diff) works for ad-hoc comparisons:

```bash
npx mcp-server-diff -b "your-server-command" -t "other-server-command"
```

Full documentation and language-specific examples are in the [repository](https://github.com/SamMorrowDrums/mcp-server-diff).


Why Diffing Your MCP Server Matters


<p><iframe allow="monetization" class="embedly-embed" src="//cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2FLwqUp4Dc1mQ%3Ffeature%3Doembed&amp;display_name=YouTube&amp;url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DLwqUp4Dc1mQ&amp;image=https%3A%2F%2Fi.ytimg.com%2Fvi%2FLwqUp4Dc1mQ%2Fhqdefault.jpg&amp;key=d932fa08bf1f47efbbe54cb3d746839f&amp;type=text%2Fhtml&amp;schema=youtube" width="640" height="360" scrolling="no" title="GitHub Universe MCP Server Demo video" frameborder="0" allowfullscreen="true"></iframe></p>

I was honoured to be invited to demo the GitHub MCP Server at GitHub Universe with Toby Padilla. This was a chance to showcase the work my team has been doing on agent extensibility with a live demonstration of the server in action.

The demo covered setting up Copilot agent mode to interact with GitHub from VS Code, key MCP tools, prompt engineering, and agent-to-agent capabilities that unlock powerful multi-step workflows through natural language.

## The Week Around Universe

Universe was an epic and ridiculously well organised event. There was a huge buzz around MCP and I had a lot of great conversations with developers and builders exploring agent extensibility.

I also attended <a href="https://resources.github.com/mcp-universe-2025/">MCP Universe</a>, a micro summit for agentic builders hosted alongside GitHub Universe. The event brought together open source contributors, startup founders, and enterprise builders to explore MCP and the agentic web. I attended with Carlos Becker, maintainer of the awesome GoReleaser tool.

The event featured an impressive lineup of speakers including David Soria Parra (Anthropic), Den Delimarsky (Microsoft), and Nick Cooper (OpenAI) from the MCP Steering Committee. We also heard from Jeremiah Lowin (FastMCP, Prefect.io), Shannon Williams (Obot), Toby Padilla (GitHub), Vitaly Gordon (Faros AI), Angie Jones (Block), Matvei Popov (Roboflow), and Cathy Di (Dedalus). The event was moderated by Rob Ferguson (Microsoft for Startups), Kevin Crosby (GitHub), and Simina Pasat (GitHub).

Later in the week, I attended the Figma MCP Meetup at Figma HQ. It was another great night of MCP discussion featuring talks from Jake Albaugh and Aditya Muttur from Figma, Harald Kirschner from Microsoft, Tadas Antanavicius (PulseMCP), and Gagan Bhat from Anthropic. It was a chance to connect with VS Code team members and other MCP adopters in person.

## Other Highlights

I took my first Waymo rides around San Francisco, which was an experience in itself.

I also took home a hackable badge from the event after quickly hacking it to show the GitHub MCP Server star count (which has almost hit 25k stars!).


GitHub Universe: MCP Server Demo


I've been using [reMarkable](https://remarkable.com/) tablets since 2021. They're excellent for capturing notes, annotating PDFs, and generally keeping your focus where it should be. But getting content back out has always been a friction point, and I finally got annoyed enough to do something about it.

I built an [MCP](https://modelcontextprotocol.io/) server that lets AI assistants read your reMarkable documents directly. What started as a weekend project turned into something genuinely useful.

## Why I Built This

I've been gradually building up an [Obsidian](https://obsidian.md/)-based second brain for my MCP R&D work. It's where I index ideas, draft articles, prepare conference talks, and collect academic papers. The system works well for digital content, but my reMarkable had years of handwritten notes that weren't part of it. Conference notes, research annotations, talk outlines, margin notes on PDFs, ideas and TODO lists. All that knowledge was trapped on the device, invisible to my Obsidian vault and not accessible for AI agents either.

reMarkable does offer ways to export content and get OCR through their cloud service. But somehow I never actually did it. The friction of manual export, one document at a time, meant those notes just sat there accumulating.

Two things inspired me to finally solve this. First, my day job. I build the [GitHub MCP Server](https://github.com/github/github-mcp-server), so I spend a lot of time thinking about MCP tool design. Second, [Scrybble Sync](https://scrybble.ink/), which syncs reMarkable to Obsidian. Scrybble showed me what was possible, but I wanted something that worked directly with AI assistants rather than as a sync tool.

So I built remarkable-mcp. Within a day, I had completely indexed everything from my reMarkable. Hundreds of documents spanning years of notes. Ideas I'd forgotten about resurfaced. Connections I'd missed became obvious. My handwritten notes were no longer lost; they were searchable, queryable, and integrated into my knowledge system. Sometimes you need to build the tool that finally makes you do the thing you've been putting off.

## SSH Mode is the Way

My first version used the reMarkable Cloud API. It worked, but felt sluggish. Then I pivoted to using SSH to connect directly to the tablet over USB, and the difference is dramatic (the cloud APIs were just not built to support my use-cases although the MCP Server still supports it). Fortunately, I already had developer mode enabled on my tablet so it was very straightforward to get going.

Connecting via USB and SSH gives you direct filesystem access. No cloud roundtrip, no subscription gatekeeping for basic functionality. The tablet becomes a local device you can query instantly. The [reMarkable guide](https://remarkable.guide/guide/access/ssh.html) has excellent documentation on enabling developer mode.

I should note that I actually enjoy reMarkable Connect. I have both a Paper Pro Move for when I'm out of the house and a Paper Pro for reading academic papers, and cloud sync across devices is genuinely useful. I just think basic programmatic access to your own documents should be available to all owners, not just subscribers. SSH mode makes that possible.

## Five Tools, Not Fifty

The reMarkable API has dozens of endpoints. I could have exposed them all as tools. Instead, I shipped five [MCP tools](https://modelcontextprotocol.io/docs/concepts/tools):

| Tool | Purpose |
|------|---------|
| `remarkable_read` | Extract text from any document |
| `remarkable_browse` | Navigate folders or search by name |
| `remarkable_search` | Search content across multiple docs |
| `remarkable_recent` | See what you've worked on lately |
| `remarkable_status` | Check connection health |

That's it. These five cover maybe 95% of what you'd actually want to do. The constraint forced better design decisions. Each tool is deeply capable rather than superficially complete.

This approach comes from [our research on the GitHub MCP Server](https://github.blog/engineering/copilot/how-were-making-github-copilot-smarter-with-fewer-tools/). We found that having too many tools actually decreased resolution rates by 2-5%. Models get confused when they have dozens of similar-looking options. Fewer, more capable tools perform better.

## Native Text Extraction

Something most people don't know: reMarkable tablets running v3+ software store typed text in a structured format. If you use the Type Folio keyboard or the on-screen keyboard, that text is stored as data, not pixels.

The [`rmscene`](https://github.com/ricklupton/rmscene) library can parse it directly. This means instant text extraction for Type Folio documents, typed annotations on PDFs, quick notes, and any typed content in notebooks. No OCR needed, no delay, no cost.

For handwritten content, you'll need OCR.

## Handwriting OCR

I originally used Tesseract for OCR. It's free, offline, and works great for printed text. For handwriting? Pretty terrible unless you write like a font. My handwriting is atrocious, so bad my 10-month-old daughter probably writes better than I do, so Tesseract was essentially useless for my notes.

Google Cloud Vision is a different story. Their handwriting recognition is genuinely impressive. My scrawled meeting notes become readable text. The service offers 1,000 free requests per month, then costs about $1.50 per 1,000 images. That's reasonable for actual use.

The server supports both: Google Vision for quality, Tesseract as an offline fallback.

## Response Design

David Cramer's [work on MCP tool design](https://cra.mr/subagents-with-mcp) influenced how I think about responses. Every tool response includes a `_hint` field suggesting logical next steps:

```json
{
  "documents": [
    {"name": "Meeting Notes", "path": "/Work/Meeting Notes"}
  ],
  "_hint": "Found 1 document. To read: remarkable_read('Meeting Notes')."
}
```

This matters more than you'd think. AI models work better when responses guide them toward sensible follow-up actions. Errors don't just say "failed," they explain what went wrong and suggest fixes:

```json
{
  "_error": {
    "type": "document_not_found",
    "message": "Document 'Meting Notes' not found",
    "suggestion": "Did you mean: 'Meeting Notes'?",
    "did_you_mean": ["Meeting Notes", "Meeting Notes 2"]
  }
}
```

## Root Path Filtering

Sometimes you don't want an agent accessing all your documents, so I added: `REMARKABLE_ROOT_PATH`. Set it to a folder e.g. `/Work` and the AI only sees your work documents. Set it to `/Journals` and it only accesses your journals. Whatever you need.

```json
{
  "env": {
    "REMARKABLE_ROOT_PATH": "/Work"
  }
}
```

This is useful for privacy (limiting AI access to specific folders), for focus (pinning to a project folder during deep work), and for context (different configs for different AI workflows). When configured, all paths are relative to the root. Browsing `/` shows the contents of `/Work`. Documents outside the provided root simply don't exist to the AI.

## MCP Resources

Beyond tools, MCP supports [Resources](https://modelcontextprotocol.io/docs/concepts/resources), which are data the AI can access directly without tool calls. Every document registers as a resource:

```
remarkable:///Meeting%20Notes.txt
remarkable:///Work/Project/Report.txt
```

In SSH mode, you also get raw file access (which provides the full text of the PDF or EPUB):

```
remarkableraw:///Research%20Paper.pdf
remarkableraw:///Books/Deep%20Work.epub
```

These appear in VS Code's MCP resource panel, letting you attach documents directly to conversations.

## Technical Stack

- **[FastMCP](https://github.com/jlowin/fastmcp)** for the [MCP server](https://modelcontextprotocol.io/docs/concepts/servers) framework
- **rmscene** for native .rm file parsing (typed text, no OCR)
- **PyMuPDF** for PDF text extraction
- **[Google Cloud Vision](https://cloud.google.com/vision)** for handwriting OCR
- **Paramiko** for SSH transport

The codebase is modular: separate files for tools, resources, API interactions, and extraction logic. Makes testing easier and keeps the mental model clean.

## What I Learned

**Design for intent, not capability.** Users don't want to "call the document metadata endpoint." They want to "find my notes from last week."

**SSH beats cloud for local devices.** Direct access is faster, works offline, and doesn't require subscriptions for basic functionality.

**Guide the next action.** Response hints aren't hand-holding. They're context that helps AI models make better decisions.

**Good OCR is worth paying for.** Tesseract is fine for printed text. For handwriting, Google Vision is transformatively better.

**Constraints improve design.** Limiting to five tools forced me to make each one deeply capable.

## Try It

The package is available on [PyPI](https://pypi.org/project/remarkable-mcp/).

### SSH Mode (Recommended)

See the [SSH Setup Guide](https://github.com/SamMorrowDrums/remarkable-mcp/blob/main/docs/ssh-setup.md) for enabling developer mode on your tablet.

Add to your `.vscode/mcp.json` or similar:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "google-vision-key",
      "description": "Google Vision API Key",
      "password": true
    }
  ],
  "servers": {
    "remarkable": {
      "command": "uvx",
      "args": ["remarkable-mcp", "--ssh"],
      "env": {
        "GOOGLE_VISION_API_KEY": "${input:google-vision-key}"
      }
    }
  }
}
```

### Cloud Mode

1. Visit [my.remarkable.com/device/desktop/connect](https://my.remarkable.com/device/desktop/connect) to get a one-time code
2. Convert it to a token:

```bash
uvx remarkable-mcp --register YOUR_CODE
```

3. Add to your `.vscode/mcp.json`:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "remarkable-token",
      "description": "reMarkable API Token",
      "password": true
    },
    {
      "type": "promptString",
      "id": "google-vision-key",
      "description": "Google Vision API Key",
      "password": true
    }
  ],
  "servers": {
    "remarkable": {
      "command": "uvx",
      "args": ["remarkable-mcp"],
      "env": {
        "REMARKABLE_TOKEN": "${input:remarkable-token}",
        "GOOGLE_VISION_API_KEY": "${input:google-vision-key}"
      }
    }
  }
}
```

The [Quick Install badges](https://github.com/SamMorrowDrums/remarkable-mcp) in the README handle VS Code configuration automatically.

## What's Next

The [GitHub issues](https://github.com/SamMorrowDrums/remarkable-mcp/issues) track future plans: write support, more OCR providers, semantic search, and export features. But for now, the core experience is solid. Your reMarkable as a queryable second brain. If you encounter any problems, that's the best place to file them.


Building an MCP Server for reMarkable


<p><iframe allow="monetization" class="embedly-embed" src="//cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2F0d9TR91iLx0%3Ffeature%3Doembed&amp;display_name=YouTube&amp;url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3D0d9TR91iLx0&amp;image=https%3A%2F%2Fi.ytimg.com%2Fvi%2F0d9TR91iLx0%2Fhqdefault.jpg&amp;key=d932fa08bf1f47efbbe54cb3d746839f&amp;type=text%2Fhtml&amp;schema=youtube" width="640" height="360" scrolling="no" title="LastMile AI Silsila Sessions: MCP at Hyperscale video" frameborder="0" allowfullscreen="true"></iframe></p>

I had the pleasure of joining the [LastMile AI](https://lastmileai.dev/) Silsila Sessions this week, where we went deep on what it really takes to make MCP agents production-ready. The session brought together some fantastic speakers to discuss the core challenges of building secure, scalable agent systems.

## The Panel

- **Sam Morrow (GitHub)** — I broke down what it really looks like to run an MCP server at scale, from tool bloat to evals to security surprises.
- **Tobin South (WorkOS)** — Unpacked the practical realities of OAuth, agent identity, and enterprise-grade authentication.
- **Sarmad Qadri (LastMile AI)** — Shared upcoming MCP spec updates and how they unlock more advanced agent behaviors.

## Key Takeaways

One of my main points during the session was around the tradeoffs between atomic tools and higher-level workflow tools:

> "Atomic tools give you flexibility, but too many create context bloat and tool confusion — workflow-style tools are where agents really shine."

This is something we've learned firsthand running MCP at hyperscale at GitHub. When you're operating at this level, the design decisions around tool granularity become critical. Too many fine-grained tools and you overwhelm the model with choices; too few and you lose the flexibility that makes agents powerful.

We also discussed:
- Running MCP at hyperscale and the unique challenges that come with it
- OAuth and agent identity in enterprise contexts
- Upcoming MCP spec changes that open the door to long-running workflows and smarter agents

Huge thanks to [LastMile AI](https://lastmileai.dev/) for hosting, and to everyone who joined live. These conversations are invaluable for pushing the MCP ecosystem forward.


LastMile AI Silsila Sessions: MCP at Hyperscale


Toby Padilla, Harald Kirschner and I will be live-streaming on The Context, on the MCP Developers Summit YouTube channel this coming Tuesday.

https://www.youtube.com/live/rtht8dbwe5U?feature=shared

The channel hosts the amazing content from their conference, as well as numerous videos and livestreams on all sorts of MCP and AI related topics.

I'm honoured to be invited to talk about my involvement in building the GitHub MCP Server, there have been so many legends in the field on their channel! I can't wait to share the ideas, problems and dreams we have.

The Context - Special Episode ft. GitHub & Microsoft



<p><iframe allow="monetization" class="embedly-embed" src="//cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2FT44T55wvDD0%3Ffeature%3Doembed&amp;display_name=YouTube&amp;url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DT44T55wvDD0&amp;image=https%3A%2F%2Fi.ytimg.com%2Fvi%2FT44T55wvDD0%2Fhqdefault.jpg&amp;key=d932fa08bf1f47efbbe54cb3d746839f&amp;type=text%2Fhtml&amp;schema=youtube" width="640" height="360" scrolling="no" title="YouTube embed" frameborder="0" allowfullscreen="true"></iframe></p>

> Join us for VS Code Live: Extending Agent Mode, a livestream showing how to unlock the full potential of agent mode using MCP servers and extension tools. We'll kick things off with a look at VS Code's vision in the MCP space, followed by demos from the VS Code team. Plus, we'll spotlight powerful MCP servers and extensions that you can start using in agent mode right away - featuring special guests you won't want to miss!

I had great fun chatting with Olivia Guzzardo McVicker (@OliviaGuzzardo) on the VS Code Livestream on YouTube about the [Remote GitHub MCP Server](https://github.blog/changelog/2025-06-12-remote-github-mcp-server-is-now-available-in-public-preview/) that launched during the episode! We chat about the server, I demo some functionality live and we also chat about using and extending agents in general.

I hope she'll have me back on again in future to see what we've achieved over the next few months.

VS Code Live: Extending Agent Mode


If you're like many people, the rapid rise of AI tools might bring a mix of excitement and, perhaps, some unease. It's natural to wonder what it all means for how we work. I've been thinking a lot about this, especially in my role with GitHub Copilot (although comments and opinions on this blog are my own), and I've noticed something that feels important to share.

Will AI make our existing tasks faster and easier, or will it replace our jobs entirely? I believe the answer is neither.

I've come to a different conclusion, which I think is more honest: AI probably won't make your job easier in the ways you expect, but it *can* help you do work that's genuinely better than what you might have produced before, and I do not believe we have arrived at an employment extinction event.

---

## The Quality Shift

When powerful AI tools become widely accessible, something interesting happens to the value of work.

Standard, good-enough output becomes abundant. Whether it's code, writing, or analysis, the baseline of acceptable is easier for everyone to reach. This also means that simply meeting that baseline is no longer a differentiator, worse than that it's almost indistinguishable from the noise floor of AI slop that people are already cursing the internet with. Tasks AI can do excellently autonomously, should be offloaded to AI, so what is left?

Truly excellent work—work that demonstrates deep understanding, thoughtful judgment, or unique insight—becomes necessary to stand out from the new noise floor.

This isn't just about working harder or faster. It's about the nature and quality of what we produce, and redefining what our best work is.

> Something I told 16 yo: In the near term, AI will increase variation in the returns for work. For example, mediocre programmers are now finding it hard even to get hired, but great programmers are making more than ever.

> Something else I told him: This is a trend that has been going since the stone age. Technology always increases variation in the returns for work. The bottom end is anchored at zero. Technology lets the top end move.

*Paul Graham*

---

## Moving Beyond "Write This For Me"

I've noticed a common pattern (and I've done this myself) when we first start using AI tools:

We provide minimal input, ask the AI to generate something complete, and then make a few tweaks.

It often works, to a degree. The output is usually... fine. But it rarely feels remarkable, and sometimes there's a subtle "off-ness" that's hard to pinpoint or fix with simple edits.

I've come to believe this isn't necessarily a limitation of the tools themselves, but more about how we're engaging with them.

---

## Finding A More Collaborative Approach

What's been working better for me is treating AI less like a vending machine and more like a thinking partner:

- Using it to explore various approaches to a problem, some of which I wouldn't have considered on my own.
- Asking it to critique my work (and then, importantly, critiquing its critique in return). With current models you have to push hard for critical feedback, they behave like sycophants by default, so ignore their flattery or at least remain suspicious of it.
- Using it to help articulate complex thoughts I'm struggling to put into clear words.
- Giving it rich context: not just *what* I'm trying to do, but *why* and what the broader goals are. This includes doing real research. Data, citations and subtle nuance are all things you should provide as context. 

It's important to note that these approaches often don't save time upfront. In fact, they can sometimes take longer than just diving into the work directly. The real difference I'm seeing is in the depth and quality of the final result.

---

## A Personal Example

Recently, I was wrestling with an annual performance self-reflection. My early drafts lacked a narrative that contextualised the relevance of my work to the company as a whole, undersold things and also lacked hard numbers, citations and other additions that would give clout to my words.

Instead of prompting AI to "write my self-reflection," I tried a more layered process:

I gathered all the relevant context—project outcomes, feedback from colleagues, company values, specific challenges I'd encountered—and then worked with an AI to help me structure and articulate this information coherently.

We went back and forth multiple times. I'd challenge its framing of a point; it would prompt me to consider an angle I'd missed. We explored different ways to structure the narrative.

The final document definitely took longer to create than if I'd just pushed through on my own. But it was clearer, more balanced, and, I think, more insightful than what I would have produced in isolation. I expect the next one will be much faster too.

---

## Some Things I've Learned About Working With AI

If you're looking to explore this kind of collaborative approach, here are a few things I've found helpful:

- **Be generous with context.** AI tools provide better assistance when they understand not just *what* you want, but *why* you want it and what success looks like.

- **Use it for thinking, not just producing.** Some of the most powerful uses involve exploration, brainstorming, critique, and refining ideas, rather than just generating finished products from scratch.

- **Expect to iterate.** As screenwriting guru Robert McKee wisely said: "Secure writers don't sell first drafts. They patiently rewrite until the script is as director-ready, as actor-ready as possible. Unfinished work invites tampering, while polished, mature work seals its integrity." This principle holds true for AI collaboration; the real value often emerges through a process of refinement.

- **Give yourself permission to experiment.** The most effective ways to use these tools are still being discovered. What works best for you might be different from what works for others, and new models are released almost daily.

---

## It's Not Just About Productivity

One of the most interesting realizations for me has been that the primary value here isn't solely about boosting productivity in the traditional sense.

A thoughtful VP at Cloudflare, William Allen, put it well: "The lesson isn't 'do more with less'—it's 'do more with more.'"

The opportunity isn't just to produce the same work faster. It's about raising the ceiling on the quality and impact of what we can achieve.

---

## A Suggestion

If you're navigating the world of AI tools, perhaps consider shifting your primary expectation from "this will make my current job easier" to "this might help me do work I'm even more proud of."

With that mindset, the learning curve can feel different. The occasional frustrations or clunky outputs become part of the investment in a new skill, rather than just failures of the tool.

And the collaboration—because that's what it truly is when it works best—can lead to outcomes that genuinely surprise you, in a good way.

Not necessarily faster, not always easier. But potentially, meaningfully better.

---

## A Note on How This Came Together

If you've made it this far, thanks for reading! I wanted to share a little about the process behind this piece, as it mirrors some of the iterative collaboration I've been discussing.

This article didn't spring out fully formed. It started as a stream-of-consciousness reflection on my experiences and observations. From there, it went through quite a journey:

*   I ran initial drafts and ideas through four different AI models, using them not just for generation, but for critical discussion, feedback on tone, and to explore different ways of articulating the core message.
*   There were many rounds of manual edits and rewrites based on my own reflections and the AI's input.
*   I consciously wove in quotes from people whose ideas resonated with the points I wanted to make.
*   Crucially, I also shared drafts with human friends and colleagues to get their invaluable perspectives and feedback.
* I consciously left in em dashes (I am not pretending I didn't get help from AI, why would I? This is exactly what I wanted to write and better use of punctuation is a gift)
*   Finally, I let it sit for a while, giving myself time to reflect and ensure it felt authentic to my voice and experience before feeling ready to share it.

It was a process of layering, refining, and sometimes stepping away. I genuinely hope you enjoyed reading it, and more importantly, that you found something to consider in your own interactions with AI.

For my part, I certainly enjoyed the process of producing it and learned a lot more about my own writing style and how to collaborate effectively with these new tools along the way.

Blog