agentic-search-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@agentic-search-mcp Find where configuration is loaded in this project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
agentic-search-mcp
A minimal Model Context Protocol server that gives an MCP client three filesystem tools: read, glob, and grep.
Every path is resolved against a single search root. The agent can only see files inside that root; paths that escape it (including through symlinks) are rejected. Only text files are read, and common generated directories (.git, .venv, node_modules, __pycache__, ...) are skipped during searches.
Requirements
Python 3.10+
Related MCP server: personal-mcp-bridge
Install
cd agentic-search-mcp
uv syncThis creates a .venv with the server and its mcp dependency installed. To also install the optional dependencies for the example client, use uv sync --extra examples.
Run the server
The server communicates over stdio, which is how an SDK client (such as the OpenAI Agents SDK example below) launches it. Set the folder it is allowed to search, then start it:
export AGENTIC_SEARCH_ROOT=/path/to/your/project
uv run agentic-search-mcpAGENTIC_SEARCH_ROOT defaults to the current working directory if it is not set. One server process serves one root; start a separate server for each folder you want to expose.
Tools
Tool | Description | Key arguments |
| Read a text file as numbered lines. |
|
| Match files/directories with a pathlib-style glob. |
|
| Regex (Python |
|
Paths may be absolute or relative to the search root. Typical calls:
read(path="src/main.py", offset=0, limit=100)glob(pattern="**/*.py", path="src")grep(pattern="def .*config", glob_filter="*.py", path=".")grep(pattern="TODO", literal=True, ignore_case=True, glob_filter="*.md")
grep patterns use Python re syntax per line: | means "or", .* matches any run of characters, and (a|b) groups alternatives. Do not escape | — GNU grep's \| syntax is not supported. Use literal=True for plain text, ignore_case=True for case-insensitive matching, and max_results to cap the output. A missing read path returns the closest matching file names to help the agent correct itself; agents should confirm paths with glob before reading.
Invalid calls (missing file, directory passed to read, invalid regex, or a path outside the root) return readable error text so the model can retry with a corrected call.
Example client
examples/openai_agents_client.py is a minimal client that launches the server as a subprocess, points it at a folder, and asks an agent a question. It uses the OpenAI Agents SDK with an OpenAI model.
uv sync --extra examples
export OPENAI_API_KEY=your-api-key
uv run --extra examples python examples/openai_agents_client.py \
--root /path/to/your/project \
--prompt "Find where configuration is loaded"The default model is gpt-5.6-luna; override it with --model or OPENAI_MODEL. By default the agent is asked to list the Python files in the root if no --prompt is given, and --root defaults to the current directory.
The client passes the search root to the server with AGENTIC_SEARCH_ROOT and forwards PATH and HOME because the SDK replaces the child's environment. OPENAI_API_KEY stays in the client process and is never sent to the MCP server.
Available Tools
3 toolsglobA
Find files and directories matching a glob pattern.
Args:
pattern: A pathlib-style glob, e.g. **/*.py or src/**/*.ts.
path: Directory to search within (absolute or root-relative, default root).
max_results: Cap on returned matches (default 1000).
Inputs: pattern (required), path, max_results. Returns: result
grepA
Search file contents with a regular expression (or a literal string).
pattern is a Python re regular expression matched against each line
with re.search -- it is not a shell grep command. Use | to combine
alternatives, .* for wildcards, and groups/quantifiers such as
(foo|bar) or \w+. \| matches a literal pipe character, so do
not escape | to mean "or" (GNU grep basic-regex syntax is not used).
For example::
grep(pattern="def (load|save)_config|class .*Settings|TODO.*(refactor|migrate)", glob_filter="*.py")Set literal=True to match plain text with no regex interpretation. Use
ignore_case for case-insensitive matching and max_results to cap
output; there is no shell pipeline to pipe into head.
Args:
pattern: Regular expression (Python re syntax), or literal text
when literal is true. Combine alternatives with unescaped |.
path: File or directory to search (absolute or root-relative, default root).
glob_filter: Optional filename filter, e.g. *.py.
literal: Treat pattern as plain text instead of a regex (default false).
ignore_case: Case-insensitive matching (default false).
max_results: Cap on returned matches (default 100).
Inputs: pattern (required), path, literal, glob_filter, +2 more. Returns: result
readA
Read a text file and return numbered lines.
Args: path: File path, absolute or relative to the search root. offset: Zero-based line number to start from (default 0). limit: Maximum number of lines to return (default 2000).
Inputs: path (required), limit, offset. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
The three tools map onto the classic, well-separated search primitives: file discovery (glob), content search (grep), and file inspection (read). There is no plausible way to confuse them, and the descriptions explicitly clarify boundaries (e.g. grep is regex, not shell grep; glob is for paths, not contents).
All names are short, lowercase, unprefixed, and drawn from established CLI vocabulary, so the set reads predictably. The only minor deviation is that 'read' is a bare verb while 'glob' and 'grep' are tool-name nouns, but this matches developer expectations rather than causing confusion.
Three tools is lean but deliberate for a focused read-only search server; each tool earns its place with no redundant overlap. It sits at the low end of the comfortable range, which is acceptable given how narrow the stated purpose is.
The surface covers the full read-only search lifecycle: find files, search their contents, then open and page through them, with filters and result caps that make each step composable. There are no write/edit or file-metadata operations, but those fall outside the implied search-and-read scope, so the gap is minor.
Maintenance
Related MCP Connectors
Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.
Browse and manage files in your Moxt AI workspace from any MCP client.
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
Agent-driven search: build, import, tune, search, and score result quality — all over MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that provides a flexible lens into directory structures and files, enabling LLM clients to efficiently navigate and understand codebases with minimal noise. It offers secure, gitignore-aware file access with tools like directory listing, file reading, and grep-like search.1MIT
- AlicenseNot gradedqualityDmaintenanceEnables safe, read-only browsing of allowlisted local directories through MCP, providing tools to list roots, read files, and search text.MIT
- AlicenseAqualityCmaintenanceEnables safe filesystem and git operations confined within a single allowed directory tree, using symlink-resolved path containment to protect against path traversal. Users can read, write, list, and search files, as well as initialize repos and run status, stage, commit, diff, and log operations through MCP.11MIT
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients to read only explicitly allowlisted Linux project files and selected Codex conversation turns. It supports listing projects and files, reading UTF-8 files, bounded text search, and paged reading of authorized conversations.MIT