This server acts as an MCP (Model Context Protocol) toolkit, exposing three AI-powered tools to any compatible client (e.g., Claude Desktop, Claude Code, MCP Inspector):
web_research: Search the web for current information on any topic, returning a concise summary with key findings. Powered by the external ai-research-agent service (HTTP, port 8003).
review_code_diff: Submit a raw code diff for structured, actionable feedback. Optionally specify a focus area (e.g., 'security'); defaults to bugs and code quality. Powered by the external ai-pr-reviewer service (HTTP, port 8004).
explain_concept: Get a clear explanation of any technical or AI concept, tailored to a specified audience using concrete analogies (defaults to a senior backend engineer new to AI). Self-contained — calls Groq directly.
The server acts as a thin client for other running services, demonstrating real runtime dependencies rather than re-implementing logic.
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., "@ai-mcp-toolkit research the latest AI news"
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.
An MCP (Model Context Protocol) server that exposes AI capabilities — two of which call other running services in this portfolio over HTTP, and one self-contained — as standardized tools any MCP-compatible client can use directly, including Claude Desktop.
MCP standardizes how an AI client calls external code. Write a tool once as an MCP server, and any MCP-compatible client — Claude Desktop, Claude Code, Cursor — can discover and call it, with no client-specific integration work.
This server exposes three tools, two of which are thin clients calling other repos' running FastAPI services over HTTP — not reimplementations of similar logic:
web_research → HTTP call to ai-research-agent's /research/ endpoint (port 8003)
review_pr → HTTP call to ai-pr-reviewer's /pr-review/ endpoint (port 8004)
explain_concept → self-contained, calls Groq directly — genuinely new, no reuse claimThe distinction matters and is worth being precise about: web_research and review_pr have no logic of their own. If ai-research-agent or ai-pr-reviewer isn't running, those tools fail outright — they don't fall back to anything. That failure mode is the proof that this is real cross-service interconnection, not two repos that happen to do similar things.
Related MCP server: Friday MCP Server
MCP Inspector — tool schemas and live testing
Local dev tool showing all 3 tools auto-discovered from @mcp.tool() decorators, with their generated input/output schemas.
Connected and running in Claude Desktop
Settings → Developer → Local MCP servers, showing ai-toolkit with status running.
A real tool call inside a Claude conversation
Claude recognizing a request matches the web_research tool, invoking it, and returning a result grounded in live search — not its own training data.
Without MCP Inspector — PR REVIEW
Claude made a normal call to view the public PR and based on diff gives the suggestion.
With MCP Inspector - PR REVIEW
Now claude made custom mcp tool calls and forwarded the request to ai-pr-reviewer over HTTP and returned the identical structured result.
Side by side, these two screenshots are the actual evidence of cross-service reuse — same backend, same output, two different ways of reaching it.
Protocol-standard tool exposure — built on the official MCP Python SDK (FastMCP)
Real cross-repo interconnection — web_research and review_pr are HTTP clients of other services in this portfolio, isolated in their own module for clarity
Auto-generated schemas — tool input/output schemas derive from Python type hints and docstrings
Honest dependency, not duplication — if a backing service is down, its tool fails; nothing is silently reimplemented as a fallback
Client-agnostic — works with Claude Desktop, Claude Code, MCP Inspector, or any future MCP client unchanged
Claude Desktop (or any MCP client)
│ stdio + MCP protocol
▼
server.py (FastMCP — tool registration, schema generation)
│
├── explain_concept ──────────────► Groq directly (no other service)
│
└── inter_server_communication.py
├── web_research ─── HTTP ──► ai-research-agent (port 8003)
└── review_pr ─── HTTP ──► ai-pr-reviewer (port 8004)inter_server_communication.py is a separate module specifically because it carries the cross-service dependency — keeping it isolated from server.py makes the "this tool depends on another repo being up" relationship explicit and easy to point to, rather than buried inside tool definitions.
server.py registers tools with @mcp.tool(). Two of those tools don't contain business logic — they import functions from inter_server_communication.py, which makes an HTTP POST to another repo's running FastAPI service and returns its response, reshaped into a readable string for the MCP client.
# inter_server_communication.py
def call_research_agent(topic: str, depth: str = "quick") -> str:
response = httpx.post(
f"{RESEARCH_AGENT_URL}/research/",
json={"topic": topic, "depth": depth},
timeout=120
)
response.raise_for_status()
data = response.json()
findings = "\n".join(f"- {f}" for f in data.get("key_findings", []))
return f"{data.get('summary', '')}\n\nKey findings:\n{findings}"# server.py
@mcp.tool()
def web_research(topic: str, depth: str = "quick") -> str:
"""Run the ai-research-agent service's autonomous web research agent on a topic."""
return call_research_agent(topic, depth)When Claude calls review_pr with a GitHub PR URL, the request goes: Claude → MCP server → inter_server_communication.py → HTTP → ai-pr-reviewer's /pr-review/ endpoint → GitHub API (to fetch the diff) → Groq (to generate the review) → back through the same chain to Claude. Five hops, three repos, one conversational request.
ai-mcp-toolkit/
├── server.py # Tool registration, FastMCP entry point
├── inter_server_communication.py # HTTP clients for ai-research-agent and ai-pr-reviewer
├── .env.example
└── .gitignorePython 3.11+
Groq API key — free
Tavily API key — free
ai-research-agent and ai-pr-reviewer repos, runnable locally
git clone https://github.com/vyavahare-kishor/ai-mcp-toolkit
cd ai-mcp-toolkit
curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv
source .venv/bin/activate
uv add "mcp[cli]" httpx groq python-dotenvcp .env.example .envGROQ_API_KEY=your_groq_api_key_here
RESEARCH_AGENT_URL=http://localhost:8003
PR_REVIEWER_URL=http://localhost:8004# Terminal 1 — ai-research-agent
cd ai-research-agent && uvicorn main:app --reload --port 8003
# Terminal 2 — ai-pr-reviewer
cd ai-pr-reviewer && uvicorn main:app --reload --port 8004uv run mcp dev server.py
# for cross server testing
uv run mcp dev inter_server_communication.pyTry review_pr with a real public GitHub PR URL while watching ai-pr-reviewer's terminal — you should see the incoming request logged there, confirming the call actually crossed into that repo.
{
"mcpServers": {
"ai-toolkit": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/ai-mcp-toolkit", "run", "server.py"]
}
}
}
# for cross server testing
{
"mcpServers": {
"ai-toolkit": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/ai-mcp-toolkit", "run", "inter_server_communication.py"]
}
}
}Restart Claude Desktop, then ask: "Use review_pr to review this PR: [github PR url]"
Wrap ai-customer-support-bot's /support/ask as a 4th cross-service tool
Add a fallback message (not silent failure) when a dependent service is unreachable
Add an MCP resource exposing recent research/review history
Authentication for remote deployment beyond local stdio
Part of an AI-native engineering portfolio. Full journey: ai-engineering-journey
Project | Relationship to this one |
| |
| |
Same Groq backend pattern, but no cross-service calls — useful contrast |
Kishor Vyavahare Senior Software Engineer → AI Native Engineer
11+ years of backend engineering (Ruby on Rails, PostgreSQL, AWS). Now building production AI systems — RAG pipelines, agents, multi-agent crews, and protocol-standard tool exposure with real cross-service architecture.
MIT License — use it, fork it, build on it.
Explain a technical or AI concept tailored to a specific audience's background level, using concrete analogies.
| Name | Required | Description | Default |
|---|---|---|---|
| concept | Yes | ||
| audience | No | a senior backend engineer new to AI |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions using concrete analogies but lacks disclosure of any side effects, authorization needs, or limitations. Behavioral traits are minimally covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the key action and purpose. However, it could be slightly more structured to include additional context without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with only two simple parameters and an output schema (not shown), the description adequately covers the main functionality. It might miss details about edge cases or format, but overall it is sufficient for an AI to understand usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by indicating that 'audience' should specify background level and that the explanation uses analogies. This adds meaning beyond the schema's bare parameter names and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'explain', resource 'technical/AI concept', and specifies tailoring to audience background with concrete analogies. It distinctly differentiates from sibling tools like review_code_diff and web_research.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when explaining concepts to a specific audience, but it does not provide explicit guidance on when not to use or how it compares to alternatives. No when/when-not statements are included.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Review a code diff and return structured, actionable feedback. Pass raw diff text. Optionally specify a focus area like 'security'.
| Name | Required | Description | Default |
|---|---|---|---|
| diff | Yes | ||
| focus | No | bugs and code quality |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must fully convey behavioral traits. It mentions 'structured, actionable feedback' but does not describe what structure, any limitations, or side effects. Lacks details on return format, performance, or error handling, leaving agents uninformed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, no wasted words. It is direct and front-loaded with the primary purpose, followed by usage instructions. Highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, 1 required, output schema existing), the description covers the core usage adequately. It could mention handling of invalid diffs or output format, but the output schema likely fills that gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description adds meaning: 'Pass raw diff text' clarifies the diff parameter's content, and 'Optionally specify a focus area like 'security'' gives an example for the focus parameter. This compensates well for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Review a code diff') and the expected output ('structured, actionable feedback'). It is specific and distinguishes the tool from siblings (explain_concept, web_research) which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description instructs to 'Pass raw diff text' and optionally specify a focus area. This provides clear input guidance. While it doesn't explicitly state when to use vs. siblings, the tool's unique purpose (code review) makes it evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the web for current information on a topic and return a concise summary with key points drawn from the results.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It only mentions the output format (concise summary with key points) but does not disclose important behaviors like data freshness, source reliability, error handling, rate limits, or any side effects. For a data-fetching tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys the action, input, and output. No extraneous words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no annotations, has output schema), the description is largely complete. It could be slightly improved by hinting at the output structure or that results are drawn from live web data, but overall it provides sufficient context for an agent to understand the tool's basic function.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has only one parameter 'topic' with 0% description coverage. The description adds meaning by explaining that the tool searches for current information on a 'topic', clarifying the parameter's purpose beyond the schema's bare type definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (search the web) and the resource (current information on a topic) with a specific output (concise summary with key points). It distinguishes itself from sibling tools like 'explain_concept' and 'review_code_diff' by focusing on web search and summarization.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as when to search the web versus using other research or explanation tools. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0explain_conceptreview_code_diffweb_researchScored across 3 tools
Each tool targets a completely different function—concept explanation, code review, and web research—with no overlap in purpose or inputs. An agent would not confuse them.
Two tools follow a clear verb_noun pattern (explain_concept, review_code_diff), but web_research reverses the order (noun_verb if 'research' is the verb) or could be read as noun_noun, breaking consistency.
With only 3 tools, the server feels minimal for a general-purpose AI toolkit. While the count itself is acceptable, the scope is too narrow to be considered well-rounded.
The tools are a random collection with no domain coherence. Missing fundamental AI capabilities like text generation, summarization, or image analysis, making the surface severely incomplete for a toolkit.
An MCP server for deep research or task groups
MCP server for generating rough-draft project plans from natural-language prompts.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
