MCP Server

Suvadu includes a built-in Model Context Protocol (MCP) server that exposes 15 tools and 7 auto-injected resources, letting AI agents query your shell history, replay past sessions, learn from failures, and get project context — all from your local database.

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 runs as a subprocess of the AI agent — it does not open any network ports and does not transmit data externally. All communication happens locally through standard I/O.

Auto-Configuration

The MCP server is automatically configured when you run either 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

After auto-configuration, the AI agent can call any of Suvadu's MCP tools without additional setup.

Available Tools

The MCP server exposes 15 tools that AI agents can call to query and analyze your shell history:

#	Tool	Description
1	`search_commands`	Search history by text, directory, executor, and date range. Returns matching commands with metadata.
2	`recent_commands`	Get the most recent commands in a directory. Useful for understanding what just happened.
3	`command_status`	Check if a specific command has been run before and what happened — exit code, when, where, and how often.
4	`get_prompts`	Browse prompts sent to AI agents and see which commands each prompt triggered.
5	`session_history`	Get the full command history of a specific session, in chronological order.
6	`get_stats`	Retrieve aggregate statistics: command counts, success rates, top commands, activity patterns.
7	`list_sessions`	Browse recent sessions with their metadata: start time, command count, directory, executor.
8	`what_changed`	Find file-modifying operations that ran recently — writes, deletes, moves, installs, and config changes.
9	`what_failed`	Find commands that failed (non-zero exit code) and, when available, which prompt caused them.
10	`suggest_next`	Predict the next commands you're likely to run, based on frecency (frequency + recency) analysis.
11	`assess_risk`	Pre-execution safety check. Pass a command and get its risk level before running it.
12	`find_agent_session`	Search past AI agent sessions by prompt text, directory, executor, or date range. Returns session summaries with command counts, success rates, and resume commands.
13	`replay_agent_session`	Get the full chronological timeline of a specific agent session with prompts interleaved between commands.
14	`learn_from_failures`	Analyze recurring command failures. Shows commands with high failure rates and agent vs human comparison.
15	`project_context`	Get a project briefing: common commands, build/test/lint patterns, failure rates, and agent activity.

Auto-Injected Resources

In addition to tools (which the agent calls on demand), the MCP server provides 7 resources that are automatically injected into the agent's context at the start of each session. These give the agent immediate awareness of your recent terminal activity without needing to make any tool calls:

Resource URI	Description
`suvadu://history/recent`	Your last 20 commands with exit codes, timestamps, and directories
`suvadu://failures/recent`	Recent failed commands, grouped by the prompt that caused them
`suvadu://stats/today`	Today's shell statistics: command count, success rate, active directories
`suvadu://risk/summary`	Risk assessment summary of recent agent commands
`suvadu://agents/activity`	Per-agent breakdown of recent activity: which agents ran what, and how it went
`suvadu://agents/sessions`	Summary of the 5 most recent AI agent sessions with prompts and command counts
`suvadu://context/project`	Project briefing: common commands, failure rates, and agent activity for the current directory

Configuration

The MCP server can be configured via suv settings (MCP tab) or by editing config.toml directly:

[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 = ["~/.ssh"]            # Exclude directories from queries

Disabled tools and resources won't appear in the agent's tool/resource list and cannot be called. The suv settings TUI provides checkboxes to toggle each tool and resource individually.

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

Privacy and Security

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

100% local — the server runs as a local subprocess, communicating over stdin/stdout only
No network ports — it does not listen on any TCP/UDP ports
No external data transmission — your shell history never leaves your machine through the MCP server
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, resources, or exclude entire directories from agent queries via suv settings

Getting started: Run suv init claude-code or suv init cursor to auto-configure the MCP server for your agent. See Agent Setup for the full setup guide.