MCP Server

Suvadu includes a built-in Model Context Protocol (MCP) server that exposes 11 tools and 5 auto-injected resources, letting AI agents query your shell history, check command outcomes, assess risk, and get context-aware suggestions — 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 11 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.

Auto-Injected Resources

In addition to tools (which the agent calls on demand), the MCP server provides 5 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

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
"Has this test suite been run before?" — the agent calls command_status with the test command
"What did Cursor do in this directory today?" — the agent calls search_commands filtered by executor and directory
"What should I run next?" — the agent calls suggest_next for frecency-based predictions

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

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.