Cursor SDK + sverklo: drop-in code intelligence for programmatic agents

Cursor's TypeScript SDK launched into public beta on April 29, 2026. The intended path for adding custom retrieval to a programmatic Cursor agent is MCP — and sverklo is an MCP server. Here's the 30-line recipe to wire them together so your Cursor agent gets sverklo's symbol graph, blast-radius analysis, and bi-temporal memory alongside Cursor's built-in semSearch.

The recipe

One file. Cursor's cookbook uses TypeScript with @cursor/sdk. Add sverklo as an MCP server when you create the agent:

// agent.ts
import { Agent } from "@cursor/sdk";

const agent = await Agent.create({
  apiKey: process.env.CURSOR_API_KEY!,
  model: { id: "auto" },              // or "composer-2"
  local: { cwd: process.cwd() },
  mcpServers: {
    sverklo: {
      type: "stdio",
      command: "npx",
      args: ["-y", "sverklo", process.cwd()],
      cwd: process.cwd(),
    },
  },
});

// The agent now has 37 sverklo tools available alongside
// Cursor's built-in semSearch, glob, grep, edit, etc.
const run = await agent.send(
  "Find every caller of UserService.validate, then explain the blast radius if I rename it."
);

for await (const event of run.stream()) {
  if (event.type === "tool_call") {
    console.log("→", event.tool, event.args);
  }
  if (event.type === "text") {
    process.stdout.write(event.text);
  }
}

That is the entire recipe. Run it with a Cursor API key and a project to operate on:

npm install -g sverklo            # one-time, pulls the indexer + ONNX model
npm install @cursor/sdk           # in your SDK project
export CURSOR_API_KEY=your_key
npx tsx agent.ts

On first call, sverklo downloads its ONNX embedding model (~90 MB, ~30 sec). Every subsequent call is offline. The agent picks sverklo_search, sverklo_impact, sverklo_refs, etc. when they fit the task — and falls back to Cursor's semSearch or grep when those are sharper.

What the agent now knows how to do

Adding sverklo via MCP makes 37 tools available. The high-leverage ones for programmatic agents:

• sverklo_search — hybrid (BM25 + ONNX embedding + PageRank) semantic search. Better than semSearch on big repos because the PageRank prior surfaces structurally important hits, not just text-similar ones.
• sverklo_impact — recursive blast-radius. "What breaks if I rename X?" returns every transitive caller across the codebase, ranked by depth.
• sverklo_refs — exact references to a symbol. Faster than re-grep, and respects the symbol graph (catches wrappers and aliases).
• sverklo_overview — PageRank-ranked codebase map. The 5-minute mental model the agent needs before it edits anything.
• sverklo_review_diff — risk-scored diff review. Tells the agent which files in the working diff to read first.
• sverklo_remember / sverklo_recall — bi-temporal memory pinned to git SHAs. Decisions persist across runs and across branches.
• sverklo_audit — god classes, dead code, command-injection patterns. Agent can run a code-quality pass before merging.

All 37 tools are available; the agent picks based on the task. The full list is in the sverklo repo.

Why this is the right wedge

The Cursor SDK's TypeScript launch blog explicitly names MCP as "the most common path" for adding capabilities a built-in tool doesn't cover. There's no custom-tool registration API, no programmatic hook surface, no context-provider plug point. The SDK is intentionally minimal in those areas — extension goes through MCP, period.

That means every retrieval / code-intel / memory feature you'd want under a programmatic Cursor agent has to be an MCP server. Sverklo is built for exactly that — local-first, MIT-licensed, runs on the host machine where your Cursor SDK code runs, no cloud round-trip, no API keys, no rate limits, no per-call cost.

For cloud-mode agents (where Cursor's runtime spawns a sandbox), the same recipe works — the SDK's cloud runtime auto-loads MCP servers configured for the user/team. Local-mode agents need local.settingSources: ["project"] to pick up .cursor/mcp.json, or you can declare mcpServers inline as shown above.

File-based variant (for projects with `.cursor/mcp.json`)

If your project already has a .cursor/mcp.json (because you also use the Cursor IDE), the SDK can read from it directly:

// .cursor/mcp.json
{
  "mcpServers": {
    "sverklo": {
      "command": "npx",
      "args": ["-y", "sverklo", "."]
    }
  }
}

// agent.ts
import { Agent } from "@cursor/sdk";

const agent = await Agent.create({
  apiKey: process.env.CURSOR_API_KEY!,
  model: { id: "auto" },
  local: {
    cwd: process.cwd(),
    settingSources: ["project"],     // load .cursor/mcp.json
  },
});

const run = await agent.send("Audit this codebase for hub files and dead code.");
for await (const event of run.stream()) console.log(event);

This is the right choice if the same project is opened in the Cursor IDE — the IDE and the SDK agent share one MCP config, no drift.

Stability notes

The Cursor SDK is in public beta. Two things to know:

• Tool-call event payload schemas are not stable. Don't write code that parses event.args or event.result internals — those reflect each tool's shape and may change. Treating tool calls as opaque is the safe pattern.
• The SDK API surface is documented stable. Agent.create(), agent.send(), run.stream(), mcpServers — these are intended to remain. The recipe above only uses documented APIs.

Sverklo's MCP interface is stable across the v0.x line. Tool names, JSON schemas, and stdio transport are unchanged since v0.5. Pin sverklo to a known minor (e.g. npx -y sverklo@0.20) if you want hermetic builds.

What's next

This recipe is the minimal wiring. Three follow-up patterns worth knowing:

1. Subagent fan-out: the Cursor SDK supports subagents via agent.task(). Each subagent gets the same MCP servers — so you can fan out to "audit this repo," "summarize this PR," "find the blast radius of the rename" in parallel.
2. Cloud-mode pinning: for cloud agents, sverklo runs locally on the developer's machine and the cloud agent calls back over MCP. The auth surface is your Cursor API key; sverklo never touches the cloud.
3. Memory across runs: sverklo_remember persists to a SQLite database on disk. Two runs of the same agent on the same project share memory — decisions made in run 1 are recallable in run 2 without you wiring anything.

npm install -g sverklo
npm install @cursor/sdk
# wire mcpServers as shown above
npx tsx agent.ts

References

• Cursor TypeScript SDK docs: cursor.com/docs/sdk/typescript
• Cursor SDK launch blog (Apr 29, 2026): cursor.com/blog/typescript-sdk
• Cursor cookbook (PR-able examples repo): github.com/cursor/cookbook
• Sverklo on GitHub: github.com/sverklo/sverklo
• Sverklo's 60-task retrieval benchmark: sverklo.com/bench

See also

• I benchmarked code retrieval for AI coding agents on 60 tasks — why hybrid search beats pure embeddings on code
• Git for AI agent memory — how sverklo_remember survives context compaction
• The 30-second audit for any MCP server you're about to install — including ones you wire into your Cursor SDK agent
• Comparison matrix — 12 code-intel tools across 9 dimensions