mcp-agent-starter
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
mcp-agent-starter
A production-shaped LangGraph plus MCP agent template. Fork it, add your own tools, and you have a working agent instead of a blank file.
Built by Saif Ullah, Agentic AI Engineer at TechAurah.
What it does
You give the agent one task in plain words. It plans which tools to call, calls them through a real MCP server, and answers from what the tools returned.
The graph has three steps:
plan -> act -> act -> ... -> answerPlan: decide which tools to call, in order. The built-in planner is a small rule based planner, no LLM and no paid API. If you plug in an LLM, the planner asks it instead.
Act: call the next planned tool through the MCP server and record the result. It loops until the plan is done or
max_stepsis hit.Answer: write a short answer from the observations.
Related MCP server: Atlas MCP Server
The two built-in tools
Tool | What it does |
| Searches file names and file contents under the workspace. Never reads outside the workspace, skips hidden folders and virtual environments, and skips files over 200 KB. |
| Fetches a plain http or https URL and returns its readable text. No API key needed. |
Both tools are real MCP tools, registered on a genuine MCP server from the official MCP Python SDK (mcp 2.3.0, MCPServer). The agent calls them through server.call_tool, never by calling the functions directly, so the MCP boundary is real.
30 second demo
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python examples/demo.pyThat runs with no API key and no cost. It builds a small workspace, searches it for the word "launch", and fetches https://example.com. You will see something like this:
Task 1: search the files for launch
Task: find launch in these files
- search_files_tool: notes.txt: Launch plan plan.md: - Write the launch notes.
Task 2: fetch a plain web page
Task: fetch https://example.com and tell me what it says
- fetch_url_tool: [200] text/html; charset=utf-8 Example Domain This domain is for use in documentation examples without needing permission.Run it on your own task from the command line:
python -m mcp_agent_starter "find launch in these files" --workspace .
python -m mcp_agent_starter "fetch https://example.com and tell me what it says"Or use it from your own code:
import asyncio
from mcp_agent_starter import Config, run_task
result = asyncio.run(run_task("find launch in these files", Config(workspace=".")))
print(result["answer"])How to add a tool
Three steps, in three files:
Write the function in
src/mcp_agent_starter/tools.py.Register it on the MCP server in
src/mcp_agent_starter/server.pywith@server.tool().Add its name and a one-line description to
TOOLSinsrc/mcp_agent_starter/registry.py.
The agent plans from the registry, so a tool that is not listed there will never be picked. That is deliberate: one place controls what the agent may use.
Config
Copy config.toml and change the values, then pass --config config.toml to the CLI. Every key has a safe default, so the file is optional.
[agent]
max_steps = 6
[tools]
workspace = "."
max_results = 5
fetch_timeout_seconds = 10
fetch_max_chars = 4000Plug in an LLM (optional, off by default)
The agent works with no LLM at all. If you want one, pass a callable in the config that takes (task, tool_names) and returns a list of {"tool": ..., "args": ...}. If the callable raises, the agent falls back to the rule based planner.
from mcp_agent_starter import Config, run_task
def my_llm(task, tool_names):
return [{"tool": "search_files_tool", "args": {"query": task}}]
config = Config(workspace=".", llm_callable=my_llm)Tests
pip install pytest
PYTHONPATH=src python -m pytest -qThe 15 tests cover the tool registry, the MCP server listing, file search inside and outside the workspace, web fetch against a local test server, end to end runs for search, fetch, and both tools together, the LLM hook, config loading, the step limit, and the fallback when a broken LLM hook raises.
Honest limits
The default planner is rule based, not an LLM. It understands tasks that mention a URL or a search word. A vague task gets a file search with the whole task as the query, which is a reasonable guess, not intelligence.
The file search reads plain text files. It does not parse PDFs, images, or binary files.
The web fetch returns the readable text of a page. It does not run JavaScript, so pages that need a browser will come back thin.
There are no measured results behind this project. No stars, users, client results, or revenue are claimed here, because none have been measured.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Search and inspect source-pinned agent skills, plugins and tools through a free public MCP.
Workspace where AI agents publish, read and hand off markdown over MCP. No account.
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables file system operations, web scraping, and AI-powered search through MCP tools for use by LLM agents.1-
- FlicenseNot gradedqualityDmaintenanceEnables AI agents and users to manage workspace files, monitor system metrics, take persistent notes, and retrieve weather data via MCP tools and resources.-
- AlicenseAqualityCmaintenanceEnables AI assistants to search and ask questions about documents stored in AnythingLLM workspaces through MCP tools.4MIT
- AlicenseAqualityBmaintenanceProvides coding agents with file inventory, ranked search, location-aware reading, code packing, and note writing over the workspace folder through MCP, without involving a model.5137 PyPI70MIT