MCP-Powered AI Assistant (FastMCP + LangGraph)

An AI assistant that uses the Model Context Protocol (MCP) to connect an LLM to real tools: a sandboxed file system, a persistent notes database, live web APIs and a safe calculator. The tools live in a standalone FastMCP server; the reasoning loop is a LangGraph state graph driven by the OpenAI API.

Because the tools sit behind MCP, the same server also works with any other MCP client, such as Claude Desktop or Cursor, with no code changes.

Demo

You: What's the weather in Mumbai, and save it as a note called "Mumbai weather"
→ tool get_weather {'city': 'Mumbai'}
→ tool add_note {'title': 'Mumbai weather', 'body': '29.4°C, 78% humidity, wind 14 km/h'}
╭─ Assistant ──────────────────────────────────────────────╮
│ It's 29.4°C in Mumbai with 78% humidity. Saved as note #1. │
╰──────────────────────────────────────────────────────────╯

You: Summarize project_ideas.md and tell me which one has the highest priority
→ tool read_file {'path': 'project_ideas.md'}
╭─ Assistant ──────────────────────────────────────────────╮
│ ... The Smart Study Planner is marked high priority.     │
╰──────────────────────────────────────────────────────────╯

Architecture

flowchart LR
    U[User / CLI] --> G
    subgraph G[LangGraph agent]
        A[agent node<br/>OpenAI LLM] -- tool calls --> T[tools node]
        T -- results --> A
    end
    T <-- MCP over stdio or HTTP --> S
    subgraph S[FastMCP server]
        F[Files<br/>sandboxed]
        N[Notes<br/>SQLite]
        W[Weather API<br/>Open-Meteo]
        K[Wikipedia API]
        C[Calculator<br/>AST-safe]
    end

1. On startup, MCPToolBridge connects to the MCP server, discovers every tool with its JSON schema, and wraps each one as a LangChain tool.
2. The LangGraph graph loops between the agent node (the LLM decides what to do) and the tools node (executes MCP calls) until the LLM produces a final answer.
3. Conversation memory is stored per thread with a LangGraph checkpointer, so follow-up questions work.

Features

Tools

Quick start

git clone https://github.com/avishiii/mcp-ai-assistant.git
cd mcp-ai-assistant
python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env               # then add your OPENAI_API_KEY
python main.py

Other ways to run it:

python main.py --ask "What is 15% of 2480?"       # one-shot question
python main.py -v                                  # also print tool outputs

# Run the MCP server over HTTP and connect to it
python server/mcp_server.py --http 8000
python main.py --server http://127.0.0.1:8000/mcp

The default model is gpt-4.1-mini. Change it with OPENAI_MODEL in .env or --model.

Use the server from Claude Desktop

Copy claude_desktop_config.example.json into your Claude Desktop config, update the path, and restart the app. The same tools become available there, which shows the point of MCP: one server, many clients.

Tests

pip install -r requirements-dev.txt
pytest -q

Tests run fully offline (no OpenAI key, no network). They use FastMCP's in-memory transport and a scripted fake chat model to check tool discovery, file sandboxing, notes, calculator safety and the complete agent → tool → agent loop.

Project structure

mcp-ai-assistant/
├── server/
│   └── mcp_server.py        # FastMCP server: tools, resource, prompt
├── agent/
│   ├── mcp_bridge.py        # MCP client -> LangChain tools adapter
│   └── graph.py             # LangGraph state graph (agent <-> tools loop)
├── tests/
│   └── test_assistant.py    # offline test suite
├── workspace/               # sandbox folder the assistant can read/write
├── main.py                  # interactive CLI
├── .github/workflows/tests.yml
└── requirements.txt

Extending it

Add a new tool by writing a typed, documented function in server/mcp_server.py:

@mcp.tool
def word_count(path: str) -> int:
    """Count the words in a workspace file."""
    return len(read_file(path).split())

The agent discovers it automatically on the next start.

License

MIT