MCP Server

Suvadu includes a built-in Model Context Protocol (MCP) server that exposes 21 tools, 8 resources, and 5 prompts, letting connected AI clients query your local shell-history database, replay captured sessions, summarize agent sessions, analyze failures, and request project context.

What Is MCP?

The Model Context Protocol (MCP) is an open standard for AI agents to access external tools and data sources. Instead of the agent guessing or asking you for information, it can directly query structured data through MCP tools. Suvadu's MCP server gives AI agents direct access to your shell history, so they can understand what happened in your terminal without you having to explain it.

Starting the MCP Server

suv mcp-serve

This starts the MCP server using JSON-RPC over stdin/stdout. The server does not open a network port; it returns requested data to the connected client through standard I/O. That client may send returned history to its AI provider under its own settings.

Auto-Configuration

The MCP server is automatically configured when you run any of these commands:

• suv init claude-code — adds Suvadu as an MCP server in Claude Code's configuration
• suv init cursor — adds Suvadu as an MCP server in Cursor's configuration
• suv init codex — adds Suvadu as an MCP server in Codex's configuration
• suv init opencode — adds Suvadu as a local MCP server under opencode.jsonc's mcp key

Restart the client after setup so it loads the server and available capabilities. Client trust and tool-permission settings still apply.

Available Tools

The MCP server exposes 21 tools by default. These query history, sessions, and active skills, or assess command text. Enabling propose_skill and/or save_session_summary adds one more tool each, up to 23; disabled tools are omitted from the list.

Skills Tools

These tools do not infer the client's working directory. Use global or an absolute project path for scope, and check the returned scope when calling get_skill. See Shared Skills for the interactive manager and native sync.

Session Tools

Any connected agent can summarize any session it can read — Suvadu never generates the summary text or calls a model itself. save_session_summary is off by default. To let an agent persist a summary after you ask it to, set allow_session_summaries = true in the [mcp] section of config.toml and restart the client; this option is not in suv settings in 0.4.1 (see Configuration). Browse saved summaries interactively in suv sessions (press s on an AI session).

Resources

In addition to tools, the MCP server provides 8 resources that a compatible client can list and read. Whether a resource is read automatically or added to model context depends on the client:

The eighth resource, suvadu://skills/index, lists active skills and their descriptions, scopes, and triggers. Like the other resources, it is available for clients to read; automatic context loading depends on the client.

Reusable MCP Prompts

Version 0.4.0 added three parameterized prompts; 0.4.1 adds two more for session summaries. Clients with MCP prompt support can surface these as user-selected actions, often slash commands:

Prompts expand into requests naming the relevant tools; the connected model still needs to call those tools. The initialize response also guides clients to use project context, failure learning, risk checks, and skills discovery proactively. Client behavior determines whether that guidance is followed.

Configuration

Configure the MCP server by editing the [mcp] section of the global config.toml. Some of these options are also available in suv settings (MCP tab):

[mcp]
disabled_tools = ["assess_risk"]    # Hide tools from agents
disabled_resources = []              # Hide resources from agents
default_days = 14                    # Default time window (1-365)
default_limit = 20                   # Default result limit (1-500)
exclude_dirs = ["/secrets", "~/.ssh"] # Hide these directories (and subtrees) from every MCP tool and resource
allow_skill_proposals = false        # Opt in to pending skill proposals
allow_session_summaries = false      # Opt in to agents saving session-summary checkpoints

Disabled tools and resources won't appear in the agent's tool/resource list and cannot be called. In 0.4.1 the suv settings MCP tab has toggles for 15 of the 21 default tools and 7 of the 8 resources; the session tools, the skills tools, and suvadu://skills/index can be disabled only by adding them to disabled_tools or disabled_resources in the file.

Project .suvadu.toml overlays do not configure MCP in 0.4.1.

exclude_dirs entries match the directory itself and everything beneath it; ~ expands to your home directory. Every MCP tool and resource that returns commands or sessions enforces it, so an excluded directory's commands never reach a connected agent regardless of which tool or resource is queried.

Example Agent Queries

With the MCP server running, an AI agent can answer questions like these by calling the appropriate tools:

• "What commands failed in this project recently?" — the agent calls what_failed with the project directory
• "What's the risk of running git push --force?" — the agent calls assess_risk and gets back "Critical"
• "Show me what changed in the last hour" — the agent calls what_changed scoped to the last hour
• "What did previous Claude sessions do here?" — the agent calls find_agent_session with the project directory
• "Replay the last agent session" — the agent calls replay_agent_session for a full timeline with prompts
• "What keeps failing?" — the agent calls learn_from_failures to see recurring failures with agent vs human comparison
• "What's the context for this project?" — the agent calls project_context for build commands, failure rates, and workflow patterns
• "Summarize and save current session" — the agent calls resolve_current_agent_session, reads it with get_agent_session, and (if allow_session_summaries is enabled) calls save_session_summary

Privacy and Security

The MCP server is designed with privacy as a first principle:

• Local process — the server runs as a local subprocess, communicating over stdin/stdout only
• No network ports — it does not listen on any TCP/UDP ports
• Explicit client boundary — the server returns only data requested through enabled tools or resources, but the connected client receives that data and may send it to its provider
• Same data as the CLI — the MCP server reads from the same local SQLite database that powers suv search and all other Suvadu commands
• Configurable access — disable individual tools and resources in config.toml (most are also toggleable in suv settings)
• Writes off by default — the default tools only read; save_session_summary and propose_skill exist only after you opt in